IOBluetoothHandsFreeGateway

Overview

In order to use this object with a Bluetooth Handsfree device, developers need to publish a Handsfree Audio Gateway SDP service. Some devices will be fine without seeing a published HF Gateway service on your machine/device, but a majority of them will not like it and will behave sporadically. Fields in the SDP record are used to tell the device about what features the Gateway supports so its required to have it published.

There are some suggested error checks developers should provide before using this object. When connecting out to a remote device developers need to check that the device has the Handsfree service in its SDP records. Use the provided class method in this object.

To attach to a device that has connected into the machine, developers need to check for the existence of the service (using the provided class method in this object), that the device is attaching to the RFCOMM channel associated with the Handsfree Gateway SDP record published on the machine, and that the device that is connecting is configured as a headset with the machine. Developers will need to search the local SDP records to find the Gateway record for the machine, the provided APIs are only for the target device.

Methods

-getDeviceSupportedFeatures

Get the supported device features

-getGatewaySupportedFeatures

Get the supported gateway features

+getRequiredSDPRFCOMMChannelIDForDevice:

Return the rfcomm channel ID as specified in the Handsfree SDP record of the device.

+getRequiredSDPServiceRecordForDevice:

Returns the Handsfree SDP service record for the device.

-initForConnectionToDevice:supportedFeatures:delegate:

Create a new IOBluetoothHandsFreeGateway for outgoing connect to a device

-initWithIncomingDevice:incomingRFCOMMChannelID:supportedFeatures:delegate:

Create a new IOBluetoothHandsFreeGateway for a device that is trying to connect in

-setGatewaySupportedFeatures:

Set the supported gateway features

Get the supported device features

- (UInt32) getDeviceSupportedFeatures; 

Return Value

A mask of feature values from the IOBluetoothHandsFreeFeatures enum

Discussion

Get the device features set during the connection setup process with the device.

Get the supported gateway features

- (UInt32) getGatewaySupportedFeatures; 

Return Value

A mask of feature values from the IOBluetoothHandsFreeFeatures enum

Return the rfcomm channel ID as specified in the Handsfree SDP record of the device.

+ (BluetoothRFCOMMChannelID) 
        getRequiredSDPRFCOMMChannelIDForDevice:(IOBluetoothDevice*)device; 

Parameters

device

A valid IOBluetoothDevice

Return Value

The SDP specified RFCOMM channel ID for the device on success, 0 on failure

Returns the Handsfree SDP service record for the device.

+ (IOBluetoothSDPServiceRecord *) 
        getRequiredSDPServiceRecordForDevice:(IOBluetoothDevice*)device; 

Parameters

device

A valid IOBluetoothDevice

Return Value

The Handsfree SDP record for the device on success, nil on failure

Create a new IOBluetoothHandsFreeGateway for outgoing connect to a device

- (id) initForConnectionToDevice: (IOBluetoothDevice *)device supportedFeatures: (UInt32)supportedFeatures delegate: (id)inDelegate; 

Parameters

device

A valid IOBluetoothDevice

supportedFeatures

A bitmask of IOBluetoothHandsFreeFeatures values. This object does not support any features

inDelegate

An object to act as delegate

Return Value

A newly created IOBluetoothHandsFreeGateway object on success, nil on failure

Create a new IOBluetoothHandsFreeGateway for a device that is trying to connect in

- (id) initWithIncomingDevice: (IOBluetoothDevice *)device incomingRFCOMMChannelID: (BluetoothRFCOMMChannelID)incomingRFCOMMChannelID supportedFeatures: (UInt32)supportedFeatures delegate: (id)inDelegate; 

Parameters

device

A valid IOBluetoothDevice with baseband connection

incomingRFCOMMChannelID

The RFCOMM ID the device is trying to connect to

supportedFeatures

A bitmask of IOBluetoothHandsFreeFeatures values. This object does not support any features

inDelegate

An object to act as delegate

Return Value

A newly created IOBluetoothHandsFreeGateway object on success, nil on failure

Discussion

An incoming connection from a Headset/Handsfree device must be validated against the local Gateway service records to find out what the device is trying to connect to. For example, headsets must be connecting over RFCOMM to a corresponding headset audio gateway rfcomm channel published in the service, handsfree to a handsfree audio gateway service. If this were L2CAP we could just look at the PSM, but these devices use RFCOMM. This method will do the proper check internally and will return nil if the incoming channel does not match with a published Handsfree AG record.

Set the supported gateway features

- (void) setGatewaySupportedFeatures:(UInt32)gatewaySupportedFeatures; 

Parameters

gatewaySupportedFeatures

A mask of feature values from the IOBluetoothHandsFreeFeatures enum

Discussion

Sets the class variable which is sent to the remote device during connection and setup. Once the setup process is complete, shortly after connecting, calling this method will do nothing. Also note that this object does not support any features, so developers will need to subclass this object, override the rfcomm delegate method from the baseclass, and handle the feature setup on their own to make the features work.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.