ADC Home > Reference Library > Reference > Hardware & Drivers > Bluetooth > Bluetooth Framework Reference

IOBluetoothUserLib.h

Include Path:	<IOBluetooth/IOBluetoothUserLib.h>
Path:	/System/Library/Frameworks/IOBluetooth.framework/Versions/A/Headers/IOBluetoothUserLib.h
See Also:	Bluetooth
Includes:	<IOKit/IOKitLib.h> <CoreFoundation/CFMachPort.h> <IOBluetooth/Bluetooth.h> <AvailabilityMacros.h>

Overview

This header contains the public interfaces for Apple's implementation of Bluetooth technology. Technology-specific typedefs and information are contained in the documentation for Bluetooth.h.

For more information about accessing Bluetooth devices, see Working With Bluetooth Devices.

Functions

IOBluetoothAddSCOAudioDevice: Creates a persistent audio driver that will route audio data to/from the specified device.
IOBluetoothAddServiceDict: Adds a service to the local SDP server.
IOBluetoothDeviceAddToFavorites: Adds the target device to the user's list of favorite devices.
IOBluetoothDeviceCloseConnection: Closes down the baseband connection to the device.
IOBluetoothDeviceCreateWithAddress: Returns the IOBluetoothDeviceRef for the given BluetoothDeviceAddress.
IOBluetoothDeviceGetAddress: Gets the Bluetooth device address for the target device.
IOBluetoothDeviceGetAddressString: Gets a string containing the Bluetooth device address for the target device.
IOBluetoothDeviceGetClassOfDevice: Gets the full class of device value for the remote device.
IOBluetoothDeviceGetClockOffset: Gets the clock offset value of the device.
IOBluetoothDeviceGetConnectionHandle: Gets the connection handle for the baseband connection.
IOBluetoothDeviceGetDeviceClassMajor: Gets the major device class of the device.
IOBluetoothDeviceGetDeviceClassMinor: Gets the minor service class of the device.
IOBluetoothDeviceGetEncryptionMode: Gets the encryption mode for the baseband connection.
IOBluetoothDeviceGetLastInquiryUpdate: Gets the date/time of the last time the device was returned during an inquiry.
IOBluetoothDeviceGetLastNameUpdate: Gets the date/time of the last successful remote name request.
IOBluetoothDeviceGetLastServicesUpdate: Gets the date/time of the last SDP query.
IOBluetoothDeviceGetLinkType: Gets the link type for the baseband connection.
IOBluetoothDeviceGetName: Gets the human-readable name of the remote device.
IOBluetoothDeviceGetNameOrAddress: Gets the human-readable name of the remote device (if the name is not present, it will return a string containing the device's address).
IOBluetoothDeviceGetPageScanMode: Gets the page scan mode for the device.
IOBluetoothDeviceGetPageScanPeriodMode: Gets the value of the page scan period mode for the device.
IOBluetoothDeviceGetPageScanRepetitionMode: Gets the value of the page scan repetition mode for the device.
IOBluetoothDeviceGetRecentAccessDate: Returns a date representing the last time the user accessed the target device.
IOBluetoothDeviceGetServiceClassMajor: Gets the major service class of the device.
IOBluetoothDeviceGetServiceRecordForUUID: Searches for a service record containing the given UUID.
IOBluetoothDeviceGetServices: Gets an array of service records for the device.
IOBluetoothDeviceInquiryClearFoundDevices: Removes all found devices from the inquiry object.
IOBluetoothDeviceInquiryCreateWithCallbackRefCon: Returns a new inquiry object.
IOBluetoothDeviceInquiryDelete: Frees the IOBluetoothDeviceInquiryRef. You do not need to do anything further with the inquiry after this.
IOBluetoothDeviceInquiryGetFoundDevices: Returns found IOBluetoothDeviceRef objects as an array.
IOBluetoothDeviceInquiryGetInquiryLength: Returns the number of seconds the search will be performed.
IOBluetoothDeviceInquiryGetUpdateNewDeviceNames: Returns whether or the inquiry object will perform remote name requests on found devices.
IOBluetoothDeviceInquiryGetUserRefCon: Gets the user reference constant.
IOBluetoothDeviceInquirySetCompleteCallback: Sets the function callback that is invoked when the inquiry is complete.
IOBluetoothDeviceInquirySetDeviceFoundCallback: Sets the function callback that is invoked when the inquiry finds a new device.
IOBluetoothDeviceInquirySetDeviceNameUpdatedCallback: Sets the function callback that is invoked when the inquiry updates a device name.
IOBluetoothDeviceInquirySetInquiryLength: Sets the length of the inquiry that is performed each time -start is used on an inquiry object.
IOBluetoothDeviceInquirySetSearchCriteria: Sets the criteria for the device search.
IOBluetoothDeviceInquirySetStartedCallback: Sets the function callback that is invoked when the inquiry is started.
IOBluetoothDeviceInquirySetUpdateNewDeviceNames: Sets whether or not the inquiry object will retrieve the names of devices found during the search.
IOBluetoothDeviceInquirySetUpdatingNamesStartedCallback: Set the function callback that is invoked when the inquiry begins to update device names (using remote name requests).
IOBluetoothDeviceInquirySetUserRefCon: Sets the user reference constant that is provided to the callbacks when they are called.
IOBluetoothDeviceInquiryStart: Starts the inquiry using the IOBluetoothDeviceInquiryRef.
IOBluetoothDeviceInquiryStop: Stops the inquiry using the IOBluetoothDeviceInquiryRef.
IOBluetoothDeviceIsConnected: Indicates whether a baseband connection to the device exists.
IOBluetoothDeviceIsFavorite: Indicates whether the target device is a favorite.
IOBluetoothDeviceIsPaired: Indicates whether the target device is paired.
IOBluetoothDeviceOpenConnection: Creates a baseband connection to the device.
IOBluetoothDeviceOpenConnectionWithOptions: Creates a baseband connection to the device.
IOBluetoothDeviceOpenL2CAPChannel: Opens a new L2CAP channel to the target device.
IOBluetoothDeviceOpenL2CAPChannelAsync: Opens a new L2CAP channel to the target device. Returns immedialty after starting the opening process.
IOBluetoothDeviceOpenL2CAPChannelSync: Opens a new L2CAP channel to the target device. Returns only after the channel is opened.
IOBluetoothDeviceOpenRFCOMMChannel: Opens a new RFCOMM channel to the target device.
IOBluetoothDeviceOpenRFCOMMChannelAsync: Opens a new RFCOMM channel to the target device. Returns immedialty after starting the opening process.
IOBluetoothDeviceOpenRFCOMMChannelSync: Opens a new RFCOMM channel to the target device. Does not return until the channel is open or failed to open.
IOBluetoothDevicePerformSDPQuery: Performs an SDP query on the target device.
IOBluetoothDeviceRegisterForDisconnectNotification: Allows a client to register for device disconnect notification.
IOBluetoothDeviceRemoteNameRequest: Issues a remote name request to the target device.
IOBluetoothDeviceRemoteNameRequestWithTimeout: Issues a remote name request to the target device.
IOBluetoothDeviceRemoveFromFavorites: Removes the target device from the user's list of favorite devices.
IOBluetoothDeviceRequestAuthentication: Requests that the existing baseband connection be authenticated.
IOBluetoothDeviceSendL2CAPEchoRequest: Send an echo request over the L2CAP connection to a remote device.
IOBluetoothFavoriteDevices: Returns an array containing all of the user's favorite devices.
IOBluetoothGetObjectIDFromArguments: Returns the BluetoothObjectID passed as an argument to an auto-launched app.
IOBluetoothGetVersion: Returns the versions of the bluetooth software and local hardware.
IOBluetoothL2CAPChannelCloseChannel: Initiates the close process on an open L2CAP channel.
IOBluetoothL2CAPChannelCreateFromObjectID: Returns the IOBluetoothL2CAPChannelRef with the given IOBluetoothObjectID.
IOBluetoothL2CAPChannelGetDevice: Returns the IOBluetoothDevice to which the target L2CAP channel is open.
IOBluetoothL2CAPChannelGetIncomingMTU: Returns the current incoming MTU for the L2CAP channel.
IOBluetoothL2CAPChannelGetLocalChannelID: Returns the local L2CAP channel ID for the target L2CAP channel.
IOBluetoothL2CAPChannelGetObjectID: Returns the IOBluetoothObjectID of the given IOBluetoothL2CAPChannelRef.
IOBluetoothL2CAPChannelGetOutgoingMTU: Returns the current outgoing MTU for the L2CAP channel.
IOBluetoothL2CAPChannelGetPSM: Returns the PSM for the target L2CAP channel.
IOBluetoothL2CAPChannelGetRemoteChannelID: Returns the remote L2CAP channel ID for the target L2CAP channel.
IOBluetoothL2CAPChannelIsIncoming: Returns TRUE if the channel is an incoming channel.
IOBluetoothL2CAPChannelRegisterForChannelCloseNotification: Allows a client to register for a channel close notification.
IOBluetoothL2CAPChannelRegisterIncomingDataListener: Allows a client to register a callback that gets called when new incoming data arrives.
IOBluetoothL2CAPChannelRegisterIncomingEventListener: Registers a callback for events.
IOBluetoothL2CAPChannelRequestRemoteMTU: Initiates the process to reconfigure the L2CAP channel with a new outgoing MTU.
IOBluetoothL2CAPChannelWrite: Writes the given data over the target L2CAP channel to the remote device.
IOBluetoothL2CAPChannelWriteAsync: Writes asynchronously the given data over the target L2CAP channel to the remote device.
IOBluetoothL2CAPChannelWriteSync: Writes synchronously the given data over the target L2CAP channel to the remote device.
IOBluetoothLocalDeviceAvailable: Determines if a bluetooth device is available on a local machine or not.
IOBluetoothLocalDeviceGetDiscoverable: Returns the discoverability state of the local device.
IOBluetoothLocalDeviceGetPowerState: Determines the current power state of the Bluetooth hardware.
IOBluetoothLocalDeviceReadAddress
IOBluetoothLocalDeviceReadAuthenticationEnable
IOBluetoothLocalDeviceReadClassOfDevice
IOBluetoothLocalDeviceReadConnectionAcceptTimeout
IOBluetoothLocalDeviceReadEncryptionMode
IOBluetoothLocalDeviceReadName
IOBluetoothLocalDeviceReadPageScanMode
IOBluetoothLocalDeviceReadPageScanPeriodMode
IOBluetoothLocalDeviceReadPageTimeout
IOBluetoothLocalDeviceReadScanEnable
IOBluetoothLocalDeviceReadSupportedFeatures
IOBluetoothLocalDeviceReadVersionInformation
IOBluetoothObjectRelease: Decrements the ref count on the target object.
IOBluetoothObjectRetain: Increments the ref count on the target object.
IOBluetoothPairedDevices: Returns an array of the currently paired devices.
IOBluetoothRecentDevices: Returns an array of the most recently accessed devices.
IOBluetoothRegisterForDeviceConnectNotifications: Allows a client to register for device connect notifications for any connection.
IOBluetoothRegisterForFilteredL2CAPChannelOpenNotifications: Allows a client to register for L2CAP channel open notifications for certain types of L2CAP channels.
IOBluetoothRegisterForFilteredRFCOMMChannelOpenNotifications: Allows a client to register for RFCOMM channel open notifications for certain types of RFCOMM channels.
IOBluetoothRegisterForL2CAPChannelOpenNotifications: Allows a client to register for L2CAP channel open notifications for any L2CAP channel.
IOBluetoothRegisterForRFCOMMChannelOpenNotifications: Allows a client to register for RFCOMM channel open notifications for any RFCOMM channel.
IOBluetoothRemoveSCOAudioDevice: Removes a persistent audio driver for a device that had already been added using IOBluetoothAddAudioDevice().
IOBluetoothRemoveServiceWithRecordHandle: Removes the given service from the local SDP server.
IOBluetoothRFCOMMChannelCloseChannel
IOBluetoothRFCOMMChannelCreateFromObjectID: Returns the IOBluetoothRFCOMMChannelRef with the given IOBluetoothObjectID.
IOBluetoothRFCOMMChannelGetChannelID: Returns the RFCOMM channel number for a given IOBluetoothRFCOMMChannelRef.
IOBluetoothRFCOMMChannelGetDevice
IOBluetoothRFCOMMChannelGetMTU
IOBluetoothRFCOMMChannelGetObjectID: Returns the IOBluetoothObjectID of the given IOBluetoothRFCOMMChannelRef.
IOBluetoothRFCOMMChannelIsIncoming: Returns the direction of the channel.
IOBluetoothRFCOMMChannelIsOpen
IOBluetoothRFCOMMChannelIsTransmissionPaused
IOBluetoothRFCOMMChannelRegisterForChannelCloseNotification: Allows a client to register for a channel close notification.
IOBluetoothRFCOMMChannelRegisterIncomingDataListener: Registers a callback for the incoming data.
IOBluetoothRFCOMMChannelRegisterIncomingEventListener: Registers a callback for events.
IOBluetoothRFCOMMChannelWrite: Writes data to an RFCOMM channel synchronusly.
IOBluetoothRFCOMMChannelWriteAsync: Writes data to an RFCOMM channel asynchronously.
IOBluetoothRFCOMMChannelWriteSimple
IOBluetoothRFCOMMChannelWriteSync: Writes data to an RFCOMM channel synchronously.
IOBluetoothRFCOMMSendRemoteLineStatus
IOBluetoothRFCOMMSetSerialParameters
IOBluetoothSDPDataElementContainsDataElement: Checks to see if the target data element is the same as the dataElement parameter or if it contains the dataElement parameter (if its a sequence type).
IOBluetoothSDPDataElementGetArrayValue: Returns the value of the data element as a CFArrayRef, if the data element is represented by an array object.
IOBluetoothSDPDataElementGetDataValue: Returns the value of the data element as a CFDataRef, if the data element is represented by a data object.
IOBluetoothSDPDataElementGetNumberValue: Returns the value of the data element as a CFNumberRef, if the data element is represented by a number.
IOBluetoothSDPDataElementGetSize: Returns the size in bytes of the target data element.
IOBluetoothSDPDataElementGetSizeDescriptor: Returns the SDP spec defined data element size descriptor for the target data element.
IOBluetoothSDPDataElementGetStringValue: Returns the value of the data element as a CFStringRef, if the data element is represented by a string object.
IOBluetoothSDPDataElementGetTypeDescriptor: Returns the SDP spec defined data element type descriptor for the target data element.
IOBluetoothSDPDataElementGetUUIDValue: Returns the value of the data element as an IOBluetoothSDPUUIDRef, if the data element is a UUID (type 3).
IOBluetoothSDPDataElementIsEqualToDataElement: Compares the target data element with the given object.
IOBluetoothSDPServiceRecordGetAttributeDataElement: Returns the data element for the given attribute ID in the target service.
IOBluetoothSDPServiceRecordGetAttributes: Returns a CFDictionaryRef containing the attributes for the service.
IOBluetoothSDPServiceRecordGetDevice: Returns the IOBluetoothDeviceRef that the target service belongs to.
IOBluetoothSDPServiceRecordGetL2CAPPSM: Allows the discovery of the L2CAP PSM assigned to the service.
IOBluetoothSDPServiceRecordGetRFCOMMChannelID: Allows the discovery of the RFCOMM channel ID assigned to the service.
IOBluetoothSDPServiceRecordGetServiceName: Returns the name of the service.
IOBluetoothSDPServiceRecordGetServiceRecordHandle: Allows the discovery of the service record handle assigned to the service.
IOBluetoothSDPServiceRecordHasServiceFromArray: Returns TRUE if any one of the UUIDs in the given array is found in the target service.
IOBluetoothSDPUUIDCreateUUID16: Creates a new 16-bit IOBluetoothSDPUUIDRef with the given UUID16.
IOBluetoothSDPUUIDCreateUUID32: Creates a new 32-bit IOBluetoothSDPUUIDRef with the given UUID32.
IOBluetoothSDPUUIDCreateWithBytes: Creates a new IOBluetoothSDPUUIDRef with the given bytes of the given length.
IOBluetoothSDPUUIDCreateWithData: Creates a new IOBluetoothSDPUUIDRef from the given CFDataRef.
IOBluetoothSDPUUIDGetBytes: Returns a pointer to the array of UUID bytes.
IOBluetoothSDPUUIDGetLength: Returns the length (in bytes) of the UUID.
IOBluetoothSDPUUIDGetUUIDWithLength: Returns an IOBluetoothSDPUUIDRef matching the target UUID, but with the given number of bytes.
IOBluetoothSDPUUIDIsEqualToUUID: Compares the two IOBluetoothSDPUUIDRefs.
IOBluetoothSetSupervisionTimeout: Sets the connection supervision timeout.
IOBluetoothUserNotificationUnregister: Unregisters the target notification.

IOBluetoothAddSCOAudioDevice

Creates a persistent audio driver that will route audio data to/from the specified device.

extern IOReturn IOBluetoothAddSCOAudioDevice(
    IOBluetoothDeviceRef device,
    CFDictionaryRef configDict ) AVAILABLE_BLUETOOTH_VERSION_1_6_AND_LATER;

Discussion

Teh Bluetooth device must be paired before it can be added. The Bluetooth hardware must also support SCO connections for devices to be added.

When a client attempts to use the audio driver, it will automatically open the baseband connection and the SCO connection if necessary. Once they are open, it will route audio data to/from the audio system. The audio driver will continue to exist (even through reboots) until IOBluetoothRemoveAudioDevice is called.

Currently, the only recognized entry in the configDict is "IOAudioControls". That entry will be an NSArray of NSDictionary objects where each dictionary represents a single audio control. Following is a description of the mandatory and optional entries in each control dictionary.

Mandatory entries:

kIOAudioControlTypeKey = Four-char-code representing the control type (see IOAudioTypes.h) Possible values: kIOAudioControlTypeLevel kIOAudioControlTypeToggle kIOAudioControlTypeSelector kIOAudioControlSubTypeKey = Four-char-code representing the control subtype. The value is dependent on the control type. Following are common subtypes for each control type: kIOAudioControlTypeLevel: kIOAudioLevelControlSubTypeVolume kIOAudioControlTypeToggle: kIOAudioToggleControlSubTypeMute kIOAudioControlTypeSelector: kIOAudioSelectorControlSubTypeOutput kIOAudioSelectorControlSubTypeInput kIOAudioControlUsageKey = Four-char-code representing the usage of the control (i.e. what part of the I/O chain the control affects - input, output, pass-thru, ...) (see IOAudioTypes.h) Possible values: kIOAudioControlUsageOutput kIOAudioControlUsageInput kIOAudioControlUsagePassThru kIOAudioControlChannelIDKey = channel ID for the channel(s) the control acts on (see IOAudioControl.h and IOAudioTypes.h for more info) kIOAudioControlChannelNameKey = name for the channel (see IOAudioControl.h and IOAudioDefines.h for more info) kIOAudioControlValueKey = Initial value of the control - as an NSNumber

Optional entries: kIOAudioControlIDKey = Optional developer-defined ID field used to uniquely identify each control.

Level control-specific entries (see IOAudioDefines.h) kIOAudioLevelControlMinValueKey = Min value for the range for the level control kIOAudioLevelControlMaxValueKey = Max value for the range for the level control kIOAudioLevelControlMinDBKey = Min value in db for the range for the level control. Value is a fixed-point 16.16 number represented as an integer in an NSNumber. kIOAudioLevelControlMaxDBKey = Max value in db for the range for the level control. Value is a fixed-point 16.16 number represented as an integer in an NSNumber. For a more detailed description of these attributes and how IOAudioControls work, see the headerdoc for IOAudioControl, IOAudioLevelControl, IOAudioToggleControl and IOAudioSelectorControl in the Kernel.framework. @param device A paired Bluetooth audio device @param configDict Configuration dictionary containing a description of the audio controls to be attached to the driver. Passing NULL will result in default controls @result Returns kIOReturnSuccess if the audio driver was successfully created, error if hardware does not support SCO or device is not paired.

IOBluetoothAddServiceDict

Adds a service to the local SDP server.

extern IOReturn IOBluetoothAddServiceDict(
    CFDictionaryRef serviceDict,
    IOBluetoothSDPServiceRecordRef *outServiceRecord);

Parameters

serviceDict: A dictionary containing the attributes for the new service.
outServiceRecord: A pointer to the newly created IOBluetoothSDPServiceRecordRef. The assigned RFCOMM channel ID can be retrieved from the service record (as can other assigned parameters.) This value only gets set if kIOReturnSuccess is returned. The caller is responsible for releasing the IOBluetoothSDPServiceRecordRef by calling IOBluetoothObjectRelease() when done.

Return Value

Returns kIOReturnSuccess if successful.

Discussion

Each entry in the dictionary representing the service contains the individual attributes. Each attribute in the dict is keyed by a string that must begin with a hex number representing the attribute ID. The key string may contain additional characters if desired as long as they follow a space after the ID hex string. The attribute value must follow the dictionary format described by IOBluetoothSDPDataElement. This dictionary format allows a service dict to be created as a plist file and then loaded into the system rather than built up in code. See the example code for an example of how can be done.

If the service record handle, L2CAP PSM or RFCOMM channel ID specified in the dictionary are in use, an alternate one will be assigned.

In addition to attributes that represent the service itself, additional attributes may be specified that control the local behavior of the service. To specify these local attributes, an additional property titled "LocalAttributes" may be added to the root of the service dict. The value of this property must be a dictionary that contains the individual local attributes.

Currently, only two local attributes are supported: "Persistent" and "TargetApplication".

The "Persistent" local attribute must be either a boolean or number representing whether the service should be persistent. A persistent service will be saved off and restored any time the Bluetooth hardware is present. It will persist through reboots and can only be removed by calling IOBluetoothRemoveServiceWithRecordHandle(). This attribute is optional. By default, if no "Persistent" local property is present, the service will only exist temporarily. It will be removed either when IOBluetoothRemoveServiceWithRecordHandle() is called or when the client application exits.

The "TargetApplication" local attribute is used to specify an application to be launched when a remote device attempts to connect to the service (by opening either an L2CAP or RFCOMM channel of the type specified in the service). This value must be a string representing the absolute path to the target executable (not just the .app wrapper - i.e. /System/Library/CoreServices/OBEXAgent.app/Contents/MacOS/OBEXAgent). This attribute is optional. If no "TargetApplication" local attribute is specified, no special action will take place when an incoming connection to the service is created. It is up to the client to be monitoring for the connection and to do the right thing when one appears.

The "LocalAttributes" property is optional. If it is not specified, by default the created service is transient and will be removed when the client exits.

Additional local attributes to further control incoming services will be added in the future.

IOBluetoothDeviceAddToFavorites

Adds the target device to the user's list of favorite devices.

extern IOReturn IOBluetoothDeviceAddToFavorites(
    IOBluetoothDeviceRef device) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns kIOReturnSuccess if the device was successfully added to the user's list of favorite devices.

Discussion

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDeviceCloseConnection

Closes down the baseband connection to the device.

extern IOReturn IOBluetoothDeviceCloseConnection(
    IOBluetoothDeviceRef btDevice);

Parameters

btDevice: The target IOBluetoothDeviceRef.

Return Value

Returns kIOReturnSuccess if the connection has successfully been closed.

Discussion

This method is synchronous and will not return until the connection has been closed (or the command failed). In the future this API will be changed to allow asynchronous operation.

IOBluetoothDeviceCreateWithAddress

Returns the IOBluetoothDeviceRef for the given BluetoothDeviceAddress.

extern IOBluetoothDeviceRef IOBluetoothDeviceCreateWithAddress(
    BluetoothDeviceAddress *bdAddr);

Parameters

bdAddr: Pointer to a BluetoothDeviceAddress for which an IOBluetoothDeviceRef is desired.

Return Value

Returns the IOBluetoothDeviceRef for the given BluetoothDeviceAddress.

Discussion

Within a single application, there will be only one IOBluetoothDeviceRef for a given remote device address. This function will return that shared device object. The IOBluetoothDeviceRef MUST be released by the caller (by calling IOBluetoothObjectRelease()).

IOBluetoothDeviceGetAddress

Gets the Bluetooth device address for the target device.

extern const BluetoothDeviceAddress *IOBluetoothDeviceGetAddress(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns a pointer to the Bluetooth device address of the target device.

IOBluetoothDeviceGetAddressString

Gets a string containing the Bluetooth device address for the target device.

extern CFStringRef IOBluetoothDeviceGetAddressString(
    IOBluetoothDeviceRef device) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns a pointer to a CFStringRef containing the Bluetooth device address of the target device. The returned string MUST be released by the caller by calling CFRelease().

Discussion

Because this function may have to create a new string object, the resulting string must be released by the caller (by calling CFRelease()).

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDeviceGetClassOfDevice

Gets the full class of device value for the remote device.

extern BluetoothClassOfDevice IOBluetoothDeviceGetClassOfDevice(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the class of device for the remote device.

Discussion

This value is only meaningful if the target device has been seen during an inquiry. This can be by checking the result of IOBluetoothDeviceGetLastInquiryUpdate(). If NULL is returned, then the device hasn't been seen.

IOBluetoothDeviceGetClockOffset

Gets the clock offset value of the device.

extern BluetoothClockOffset IOBluetoothDeviceGetClockOffset(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the clock offset value for the device.

Discussion

IOBluetoothDeviceGetConnectionHandle

Gets the connection handle for the baseband connection.

extern BluetoothConnectionHandle IOBluetoothDeviceGetConnectionHandle(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the connection handle for the baseband connection. If no baseband connection is present, kBluetoothConnectionHandleNone is returned.

Discussion

This method only returns a valid result if a baseband connection is present (IOBluetoothDeviceIsConnected() returns TRUE).

IOBluetoothDeviceGetDeviceClassMajor

Gets the major device class of the device.

extern BluetoothDeviceClassMajor IOBluetoothDeviceGetDeviceClassMajor(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the major device class of the remote device.

Discussion

IOBluetoothDeviceGetDeviceClassMinor

Gets the minor service class of the device.

extern BluetoothDeviceClassMinor IOBluetoothDeviceGetDeviceClassMinor(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the minor device class of the remote device.

Discussion

IOBluetoothDeviceGetEncryptionMode

Gets the encryption mode for the baseband connection.

extern BluetoothHCIEncryptionMode IOBluetoothDeviceGetEncryptionMode(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the encryption mode for the baseband connection. If no baseband connection is present, kEncryptionDisabled is returned.

Discussion

This method only returns a valid result if a baseband connection is present (IOBluetoothDeviceIsConnected() returns TRUE).

IOBluetoothDeviceGetLastInquiryUpdate

Gets the date/time of the last time the device was returned during an inquiry.

extern CFDateRef IOBluetoothDeviceGetLastInquiryUpdate(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the date/time of the last time the device was seen during an inquiry. If the device has never been seen during an inquiry, NULL is returned. The returned CFDateRef does NOT need to be released by the caller.

IOBluetoothDeviceGetLastNameUpdate

Gets the date/time of the last successful remote name request.

extern CFDateRef IOBluetoothDeviceGetLastNameUpdate(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the date/time of the last successful remote name request. If no remote name request has been completed on the target device, NULL is returned. The returned CFDateRef does NOT need to be released by the caller.

IOBluetoothDeviceGetLastServicesUpdate

Gets the date/time of the last SDP query.

extern CFDateRef IOBluetoothDeviceGetLastServicesUpdate(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the date/time of the last SDP query. If an SDP query has never been performed on the device, NULL is returned. The resulting CFDateRef does NOT need to be released by the caller.

IOBluetoothDeviceGetLinkType

Gets the link type for the baseband connection.

extern BluetoothLinkType IOBluetoothDeviceGetLinkType(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the link type for the baseband connection. If no baseband connection is present, kBluetoothLinkTypeNone is returned.

Discussion

This method only returns a valid result if a baseband connection is present (IOBluetoothDeviceIsConnected() returns TRUE).

IOBluetoothDeviceGetName

Gets the human-readable name of the remote device.

extern CFStringRef IOBluetoothDeviceGetName(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the name of the remote device name. This value is a CFStringRef generated from the UTF-8 format of the most recent remote name request. The returned string does NOT need to be released by the caller.

Discussion

This only returns a value if a remote name request has been performed on the target device. If a successful remote name request has not been completed, NULL is returned. To perform a remote name request, call IOBluetoothDeviceRemoteNameRequest(). If a remote name request has been successfully completed, the function IOBluetoothDeviceGetLastNameUpdate() will return the date/time of the last successful request.

IOBluetoothDeviceGetNameOrAddress

Gets the human-readable name of the remote device (if the name is not present, it will return a string containing the device's address).

extern CFStringRef IOBluetoothDeviceGetNameOrAddress(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the device's name or a string containing the device's address. The returned string MUST be released by the caller by calling CFRelease().

Discussion

If a remote name request has been successfully completed, the device name will be returned. If not, a string containg the device address in the format of "XX-XX-XX-XX-XX-XX" will be returned. Because this function may have to create a new string object, the resulting string must be released by the caller (by calling CFRelease()).

IOBluetoothDeviceGetPageScanMode

Gets the page scan mode for the device.

extern BluetoothPageScanMode IOBluetoothDeviceGetPageScanMode(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the value for the page scan mode for the device.

Discussion

IOBluetoothDeviceGetPageScanPeriodMode

Gets the value of the page scan period mode for the device.

extern BluetoothPageScanPeriodMode IOBluetoothDeviceGetPageScanPeriodMode(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns page scan period mode value for the device.

Discussion

IOBluetoothDeviceGetPageScanRepetitionMode

Gets the value of the page scan repetition mode for the device.

extern BluetoothPageScanRepetitionMode IOBluetoothDeviceGetPageScanRepetitionMode(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the page scan repetition mode value for this device.

Discussion

IOBluetoothDeviceGetRecentAccessDate

Returns a date representing the last time the user accessed the target device.

extern CFDateRef IOBluetoothDeviceGetRecentAccessDate(
    IOBluetoothDeviceRef device) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns a CFDateRef representing the last date/time that the user accessed the target device. The resulting CFDateRef must be released by the caller by calling CFRelease().

Discussion

The CFDateRef returned by this function must be released by calling CFRelease().

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDeviceGetServiceClassMajor

Gets the major service class of the device.

extern BluetoothServiceClassMajor IOBluetoothDeviceGetServiceClassMajor(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns the major service class of the device.

Discussion

IOBluetoothDeviceGetServiceRecordForUUID

Searches for a service record containing the given UUID.

extern IOBluetoothSDPServiceRecordRef IOBluetoothDeviceGetServiceRecordForUUID(
    IOBluetoothDeviceRef device,
    IOBluetoothSDPUUIDRef uuidRef);

Parameters

device: The target IOBluetoothDeviceRef.
uuidRef: UUID value to search for.

Return Value

Returns the first service record that contains the given uuid. If no service record is found, NULL is returned. The resulting IOBluetoothSDPServiceRecordRef does NOT need to be released by the caller.

Discussion

This method searches through the device's services to find a service that contains the given UUID. Only the first service record will be returned. This method only operates on services that have already been queried. It will not initiate a new query. This method should probably be updated to return an array of service records if more than one contains the UUID.

IOBluetoothDeviceGetServices

Gets an array of service records for the device.

extern CFArrayRef IOBluetoothDeviceGetServices(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns an array of service records (IOBluetoothDeviceRefs) for the device if an SDP query has been performed. If no SDP query has been performed, NULL is returned. The resulting CFArrayRef does NOT need to be released by the caller.

Discussion

The resulting array contains IOBluetoothSDPServiceRecordRefs. The service records are only present if an SDP query has been done on the target object. This can be determined by calling IOBluetoothDeviceGetLastServicesUpdate(). It will return the last date/time of the SDP query. To peform an SDP query, use IOBluetoothDevicePerformSDPQuery().

Instead of allowing individual clients to query for different services and service attributes, the system request all of the device's services and service attributes.

IOBluetoothDeviceInquiryClearFoundDevices

Removes all found devices from the inquiry object.

extern IOReturn IOBluetoothDeviceInquiryClearFoundDevices(
    IOBluetoothDeviceInquiryRef inInquiryRef ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

IOBluetoothDeviceInquiryCreateWithCallbackRefCon

Returns a new inquiry object.

extern IOBluetoothDeviceInquiryRef IOBluetoothDeviceInquiryCreateWithCallbackRefCon(
    void *inUserRefCon ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

inUserRefCon: Client-supplied refCon to be passed to the callback.

Return Value

Returns whether the inquiry was successfully created.

IOBluetoothDeviceInquiryDelete

Frees the IOBluetoothDeviceInquiryRef. You do not need to do anything further with the inquiry after this.

extern IOReturn IOBluetoothDeviceInquiryDelete(
    IOBluetoothDeviceInquiryRef inquiryRef ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

inquiryRef: Client-supplied refCon to be passed to the callback.

IOBluetoothDeviceInquiryGetFoundDevices

Returns found IOBluetoothDeviceRef objects as an array.

extern CFArrayRef IOBluetoothDeviceInquiryGetFoundDevices(
    IOBluetoothDeviceInquiryRef inInquiryRef ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Return Value

Returns an CFArrayRef of IOBluetoothDeviceRef objects.

Discussion

Will not return nil. If there are no devices found, returns an array with length of 0.

IOBluetoothDeviceInquiryGetInquiryLength

Returns the number of seconds the search will be performed.

extern uint8_t IOBluetoothDeviceInquiryGetInquiryLength(
    IOBluetoothDeviceInquiryRef inInquiryRef ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Return Value

Returns the number of seconds the search will be performed.

IOBluetoothDeviceInquiryGetUpdateNewDeviceNames

Returns whether or the inquiry object will perform remote name requests on found devices.

extern Boolean IOBluetoothDeviceInquiryGetUpdateNewDeviceNames(
    IOBluetoothDeviceInquiryRef inInquiryRef ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Return Value

Returns TRUE if the inquiry will get device name for found objects, FALSE if not.

IOBluetoothDeviceInquiryGetUserRefCon

Gets the user reference constant.

extern void * IOBluetoothDeviceInquiryGetUserRefCon(
    IOBluetoothDeviceInquiryRef inInquiryRef ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Return Value

void * A ptr to an object that was previously supplied with IOBluetoothDeviceInquirySetUserRefCon.

IOBluetoothDeviceInquirySetCompleteCallback

Sets the function callback that is invoked when the inquiry is complete.

extern IOReturn IOBluetoothDeviceInquirySetCompleteCallback(
    IOBluetoothDeviceInquiryRef inInquiryRef, 
    IOBluetoothDeviceInquiryCompleteCallback callback ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

callback: Function pointer that conforms to IOBluetoothDeviceInquiryCompleteCallback.

IOBluetoothDeviceInquirySetDeviceFoundCallback

Sets the function callback that is invoked when the inquiry finds a new device.

extern IOReturn IOBluetoothDeviceInquirySetDeviceFoundCallback(
    IOBluetoothDeviceInquiryRef inInquiryRef, 
    IOBluetoothDeviceInquiryDeviceFoundCallback callback ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

callback: Function pointer that conforms to IOBluetoothDeviceInquiryDeviceFoundCallback.

IOBluetoothDeviceInquirySetDeviceNameUpdatedCallback

Sets the function callback that is invoked when the inquiry updates a device name.

extern IOReturn IOBluetoothDeviceInquirySetDeviceNameUpdatedCallback(
    IOBluetoothDeviceInquiryRef inInquiryRef, 
    IOBluetoothDeviceInquiryDeviceNameUpdatedCallback callback ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

callback: Function pointer that conforms to IOBluetoothDeviceInquiryDeviceNameUpdatedCallback.

IOBluetoothDeviceInquirySetInquiryLength

Sets the length of the inquiry that is performed each time -start is used on an inquiry object.

extern IOReturn IOBluetoothDeviceInquirySetInquiryLength(
    IOBluetoothDeviceInquiryRef inInquiryRef, 
    int8_t inSeconds ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

inSeconds: Number of seconds the inquiry will search for in-range devices before refreshing device names, if specified.

Return Value

Returns the number of seconds the search will be performed.

Discussion

A default of 10 seconds is used, unless a different value is specifed using this method. Note that if you have called -start again too quickly, your inquiry may actually take much longer than the length you specify, as inquiries are throttled in the system.

Also note that this length value is only the amount of time the hardware spends "discovering" devices. The total inquiry might take longer, however, if it is also updating device names.

IOBluetoothDeviceInquirySetSearchCriteria

Sets the criteria for the device search.

extern IOReturn IOBluetoothDeviceInquirySetSearchCriteria(
    IOBluetoothDeviceInquiryRef inInquiryRef, 
    BluetoothServiceClassMajor inServiceClassMajor, 
    BluetoothDeviceClassMajor inMajorDeviceClass, 
    BluetoothDeviceClassMinor inMinorDeviceClass ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

inServiceClassMajor: Set the major service class for found devices. Set to kBluetoothServiceClassMajorAny for all devices. See BluetoothAssignedNumbers.h for possible values.
inMajorDeviceClass: Set the major device class for found devices. Set to kBluetoothDeviceClassMajorAny for all devices. See BluetoothAssignedNumbers.h for possible values.
inMinorDeviceClass: Set the minor device class for found devices. Set to kBluetoothDeviceClassMinorAny for all devices. See BluetoothAssignedNumbers.h for possible values.

Discussion

The default inquiry object qill search for all types of devices. If you wish to find only keyboards, for example, you might use this method like this:

IOBluetoothDeviceInquirySetSearchCriteria( myInquiryObjectRef, kBluetoothServiceClassMajorAny, kBluetoothDeviceClassMajorPeripheral, kBluetoothDeviceClassMinorPeripheral1Keyboard );

However, we recommend only using this if you are certain of the device class you are looking for, as some devices may report a different/unexpected device class, and the search may miss the device you are interested in.

IOBluetoothDeviceInquirySetStartedCallback

Sets the function callback that is invoked when the inquiry is started.

extern IOReturn IOBluetoothDeviceInquirySetStartedCallback(
    IOBluetoothDeviceInquiryRef inInquiryRef, 
    IOBluetoothDeviceInquiryStartedCallback callback ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

callback: Function pointer that conforms to IOBluetoothDeviceInquiryStartedCallback.

IOBluetoothDeviceInquirySetUpdateNewDeviceNames

Sets whether or not the inquiry object will retrieve the names of devices found during the search.

extern IOReturn IOBluetoothDeviceInquirySetUpdateNewDeviceNames(
    IOBluetoothDeviceInquiryRef inInquiryRef, 
    Boolean inUpdateNames ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

inUpdateNames: Pass TRUE if names are to be updated, otherwise pass FALSE.

Discussion

The default value for the inquiry object is TRUE, unless this method is used to change it.

IOBluetoothDeviceInquirySetUpdatingNamesStartedCallback

Set the function callback that is invoked when the inquiry begins to update device names (using remote name requests).

extern IOReturn IOBluetoothDeviceInquirySetUpdatingNamesStartedCallback(
    IOBluetoothDeviceInquiryRef inInquiryRef, 
    IOBluetoothDeviceInquiryUpdatingNamesStartedCallback callback ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

callback: Function ptr that conforms to IOBluetoothDeviceInquiryUpdatingNamesStartedCallback.

IOBluetoothDeviceInquirySetUserRefCon

Sets the user reference constant that is provided to the callbacks when they are called.

extern IOReturn IOBluetoothDeviceInquirySetUserRefCon(
    IOBluetoothDeviceInquiryRef inInquiryRef, 
    void *inUserRefCon ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Parameters

inUserRefCon: A pointer to an object.

IOBluetoothDeviceInquiryStart

Starts the inquiry using the IOBluetoothDeviceInquiryRef.

extern IOReturn IOBluetoothDeviceInquiryStart(
    IOBluetoothDeviceInquiryRef inInquiryRef ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Return Value

Returns whether the inquiry was started with or without error.

IOBluetoothDeviceInquiryStop

Stops the inquiry using the IOBluetoothDeviceInquiryRef.

extern IOReturn IOBluetoothDeviceInquiryStop(
    IOBluetoothDeviceInquiryRef inInquiryRef ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;

Return Value

Returns whether the inquiry was stopped with or without error.

IOBluetoothDeviceIsConnected

Indicates whether a baseband connection to the device exists.

extern Boolean IOBluetoothDeviceIsConnected(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns YES if a baseband connection to the device exists.

IOBluetoothDeviceIsFavorite

Indicates whether the target device is a favorite.

extern Boolean IOBluetoothDeviceIsFavorite(
    IOBluetoothDeviceRef device) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns TRUE if the device is one of the user's favorites.

Discussion

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDeviceIsPaired

Indicates whether the target device is paired.

extern Boolean IOBluetoothDeviceIsPaired(
    IOBluetoothDeviceRef device) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns TRUE if the device is paired.

Discussion

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDeviceOpenConnection

Creates a baseband connection to the device.

extern IOReturn IOBluetoothDeviceOpenConnection(
    IOBluetoothDeviceRef btDevice,
    IOBluetoothCreateConnectionCallback callback,
    void *refCon);

Parameters

btDevice: The target IOBluetoothDeviceRef.
callback: The function to be called when the connection has been established (or the create connection has failed).
refCon: A client-supplied reference to be passed to the callback.

Return Value

Returns kIOReturnSuccess if the connection was successfully created (synchronously) or if the create connection call was successfully sent (asynchronously). If kIOReturnSuccess is not received in the asynchronous case, the callback will not be called.

Discussion

This method can be either synchronous or asynchronous. If a callback is specified, the operation is performed asynchronously and the callback called when the connection complete event is received. If no callback is specified, the operation is synchronous and the function will not return until the connection complete event is received.

IOBluetoothDeviceOpenConnectionWithOptions

Creates a baseband connection to the device.

extern IOReturn IOBluetoothDeviceOpenConnectionWithOptions(
    IOBluetoothDeviceRef btDevice,
    IOBluetoothCreateConnectionCallback callback,
    void *refCon,
    BluetoothHCIPageTimeout inPageTimeout,
    Boolean inAuthenticationRequired) AVAILABLE_BLUETOOTH_VERSION_1_3_AND_LATER;

Parameters

btDevice: The target IOBluetoothDeviceRef.
callback: The function to be called when the connection has been established (or the create connection has failed).
refCon: A client-supplied reference to be passed to the callback.
inPageTimeout: A client-supplied Page timeout value to use for the create connection call.
inAuthenticationRequired: A client-supplied Boolean to indicate whether we require authentication for the new connection.

Return Value

Discussion

This function can be either synchronous or asynchronous. If a callback is specified, the operation is performed asynchronously and the callback called when the connection complete event is received. If no callback is specified, the operation is synchronous and the function will not return until the connection complete event is received.

NOTE: This function is only available in Mac OS X 10.2.7 (Bluetooth v1.3) or later.

IOBluetoothDeviceOpenL2CAPChannel

Opens a new L2CAP channel to the target device.

extern IOReturn IOBluetoothDeviceOpenL2CAPChannel(
    IOBluetoothDeviceRef btDevice,
    BluetoothL2CAPPSM psm,
    Boolean findExisting,
    IOBluetoothL2CAPChannelRef *newChannel) DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER;

Parameters

btDevice: The target IOBluetoothDeviceRef.
psm: The L2CAP PSM value for the new channel.
findExisting: This value should be set to TRUE if it should look for an existing channel with the PSM. Typically this value will be FALSE. It should be TRUE only in the case where a single channel is allowed by the spec for the given PSM.
newChannel: A pointer to an IOBluetoothL2CAPChannelRef to receive the L2CAP channel requested to be opened. The newChannel pointer will only be set if kIOReturnSuccess is returned.

Return Value

Returns kIOReturnSuccess if the open process was successfully started (or if an existing L2CAP channel was found).

Discussion

This function will begin the process of opening a new L2CAP channel to the target device. The baseband connection to the device will be opened if it is not open already. The L2CAP channel open process will not complete until the client has registered an incoming data listener on the new channel. This prevents a situation where the channel succeeds in being configured and opened and receives data before the client is listening and is ready for it.

Because a new IOBluetoothL2CAPChannelRef will be created for the client as a result of this function, the client is responsible for releasing the resulting IOBluetoothL2CAPChannelRef (by calling IOBluetoothObjectRelease()).

IOBluetoothDeviceOpenL2CAPChannelAsync

Opens a new L2CAP channel to the target device. Returns immedialty after starting the opening process.

extern IOReturn IOBluetoothDeviceOpenL2CAPChannelAsync(
    IOBluetoothDeviceRef btDevice,
    IOBluetoothL2CAPChannelRef *newChannel,
    BluetoothL2CAPPSM psm,
    IOBluetoothL2CAPChannelIncomingEventListener eventListener,
    void *refcon) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

btDevice: The target IOBluetoothDeviceRef.
newChannel: A pointer to an IOBluetoothL2CAPChannelRef to receive the L2CAP channel requested to be opened. The newChannel pointer will only be set if kIOReturnSuccess is returned.
psm: The L2CAP PSM value for the new channel.
eventListener: An IOBluetoothL2CAPChannelIncomingEventListener where to receive events regarding the channel (MUST be specified).
refcon: A refcon pointer (for the callback specified above).

Return Value

Returns kIOReturnSuccess if the open process was successfully started (or if an existing L2CAP channel was found).

Discussion

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDeviceOpenL2CAPChannelSync

Opens a new L2CAP channel to the target device. Returns only after the channel is opened.

extern IOReturn IOBluetoothDeviceOpenL2CAPChannelSync(
    IOBluetoothDeviceRef btDevice,
    IOBluetoothL2CAPChannelRef *newChannel,
    BluetoothL2CAPPSM psm,
    IOBluetoothL2CAPChannelIncomingEventListener eventListener,
    void *refcon) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

btDevice: The target IOBluetoothDeviceRef.
newChannel: A pointer to an IOBluetoothL2CAPChannelRef to receive the L2CAP channel requested to be opened. The newChannel pointer will only be set if kIOReturnSuccess is returned.
psm: The L2CAP PSM value for the new channel.
eventListener: An IOBluetoothL2CAPChannelIncomingEventListener where to receive events regarding the channel (MUST be specified).
refcon: A refcon pointer (for the callback specified above).

Return Value

Returns kIOReturnSuccess if the open process was successfully started (or if an existing L2CAP channel was found).

Discussion

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDeviceOpenRFCOMMChannel

Opens a new RFCOMM channel to the target device.

extern IOReturn IOBluetoothDeviceOpenRFCOMMChannel(
    IOBluetoothDeviceRef btDevice,
    BluetoothRFCOMMChannelID channelID,
    IOBluetoothRFCOMMChannelRef *rfcommChannel) DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER;

Parameters

btDevice: The target IOBluetoothDeviceRef.
channelID: The RFCOMM channel ID for the new channel.
rfcommChannel: A pointer to an IOBluetoothRFCOMMChannelRef to receive the RFCOMM channel requested to be opened. The rfcommChannel pointer will only be set if kIOReturnSuccess is returned.

Return Value

Returns kIOReturnSuccess if the open process was successfully started (or if an existing RFCOMM channel was found).

Discussion

This function will begin the process of opening a new RFCOMM channel to the target device. The baseband connection to the device will be opened if it is not open already. The RFCOMM channel open process will not complete until the client has registered an incoming data listener on the new channel.

Because a new IOBluetoothRFCOMMChannelRef will be created for the client as a result of this function, the client is responsible for releasing the resulting IOBluetoothRFCOMMChannelRef (by calling IOBluetoothObjectRelease()).

IOBluetoothDeviceOpenRFCOMMChannelAsync

Opens a new RFCOMM channel to the target device. Returns immedialty after starting the opening process.

IOReturn IOBluetoothDeviceOpenRFCOMMChannelAsync(
    IOBluetoothDeviceRef btDevice,
    IOBluetoothRFCOMMChannelRef *newChannel,
    BluetoothRFCOMMChannelID channelID,
    IOBluetoothRFCOMMChannelIncomingEventListener eventListener,
    void *refcon) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

btDevice: The target IOBluetoothDeviceRef.
newChannel: A pointer to an IOBluetoothRFCOMMChannelRef to receive the RFCOMM channel requested to be opened. The rfcommChannel pointer will only be set if kIOReturnSuccess is returned.
channelID: The RFCOMM channel ID for the new channel.
eventListener: An IOBluetoothRFCOMMChannelIncomingEventListener where to receive events regarding the channel (MUST be specified).
refcon: A refcon pointer (for the callback specified above).

Return Value

Returns kIOReturnSuccess if the open process was successfully started .

Discussion

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDeviceOpenRFCOMMChannelSync

Opens a new RFCOMM channel to the target device. Does not return until the channel is open or failed to open.

IOReturn IOBluetoothDeviceOpenRFCOMMChannelSync(
    IOBluetoothDeviceRef btDevice,
    IOBluetoothRFCOMMChannelRef *newChannel,
    BluetoothRFCOMMChannelID channelID,
    IOBluetoothRFCOMMChannelIncomingEventListener eventListener,
    void *refcon) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

btDevice: The target IOBluetoothDeviceRef.
newChannel: A pointer to an IOBluetoothRFCOMMChannelRef to receive the RFCOMM channel requested to be opened. The rfcommChannel pointer will only be set if kIOReturnSuccess is returned.
channelID: The RFCOMM channel ID for the new channel.
eventListener: An IOBluetoothRFCOMMChannelIncomingEventListener where to receive events regarding the channel (MUST be specified).
refcon: A refcon pointer (for the callback specified above).

Return Value

Returns kIOReturnSuccess if the open process was successfully started .

Discussion

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDevicePerformSDPQuery

Performs an SDP query on the target device.

extern IOReturn IOBluetoothDevicePerformSDPQuery(
    IOBluetoothDeviceRef inDeviceRef, 
    IOBluetoothSDPQueryCallback inCallback, 
    void *inUserRefCon );

Parameters

inDeviceRef: The target IOBluetoothDeviceRef.
inCallback: The callback to call when the SDP query is complete.
inUserRefCon: User-supplied reference that will be passed to the callback.

Return Value

Returns kIOReturnSuccess if the SDP query was successfully started.

Discussion

As a result of this call, a baseband connection will be built to the device (if not already connected). Then, an L2CAP channel will be opened to the SDP server on the device. At that point, a Service Search Attribute request will be issued with a UUID of 0x0100 (L2CAP) and an attribute range of 0x0000 - 0xffff specified. This will cause the SDP server to return all attributes of all L2CAP-derived services on the device. The results essentially encompass all services on the device. This function is always asynchronous. If a callback is specified, when the SDP query is complete (or an error is encountered), the callback will be called with the given refCon. If no target is specified, the request is still asynchronous, but no callback will be made. That can be useful if the client has registered for SDP service changed notifications.

IOBluetoothDeviceRegisterForDisconnectNotification

Allows a client to register for device disconnect notification.

IOBluetoothUserNotificationRef IOBluetoothDeviceRegisterForDisconnectNotification(
    IOBluetoothDeviceRef inDevice, 
    IOBluetoothUserNotificationCallback callback, 
    void *inRefCon );

Parameters

callback: The callback to be called when the target's connection is destroyed.
inRefCon: Client-supplied refCon to be passed to the callback.

Return Value

Returns an IOBluetoothUserNotificationRef representing the outstanding device disconnect notification. To unregister the notification, call IOBluetoothUserNotificationUnregister() with the returned IOBluetoothUserNotificationRef. If an error is encountered creating the notification, NULL is returned. The returned IOBluetoothUserNotificationRef will be valid for as long as the notification is registered. It is not necessary to retain the result. Once the notification is unregistered, it will no longer be valid.

Discussion

The given callback will be called when the target device's connection is closed.

IOBluetoothDeviceRemoteNameRequest

Issues a remote name request to the target device.

extern IOReturn IOBluetoothDeviceRemoteNameRequest(
    IOBluetoothDeviceRef inDeviceRef, 
    IOBluetoothRemoteNameRequestCallback inCallback, 
    void *inUserRefCon, 
    BluetoothDeviceName outDeviceName );

Parameters

inDeviceRef: The target IOBluetoothDeviceRef.
inCallback: The callback to call when the remote name request is complete.
inUserRefCon: User-supplied reference that will be passed to the callback.
outDeviceName: Contains the device name if the request is synchronous and completes successfully.

Return Value

Returns kIOReturnSuccess if the remote name request was successfully issued (and if synchronous, if the request completed successfully).

Discussion

If a callback is specified, the request is asynchronous and on completion of the REMOTE_NAME_REQUEST command, the callback will be called with the given refCon. If no target is specified, the request is made synchronously and won't return until the request is complete.

IOBluetoothDeviceRemoteNameRequestWithTimeout

Issues a remote name request to the target device.

extern IOReturn IOBluetoothDeviceRemoteNameRequestWithTimeout(
    IOBluetoothDeviceRef inDeviceRef, 
    IOBluetoothRemoteNameRequestCallback inCallback, 
    void *inUserRefCon, 
    BluetoothDeviceName outDeviceName, 
    BluetoothHCIPageTimeout inTimeout ) AVAILABLE_BLUETOOTH_VERSION_1_3_AND_LATER;

Parameters

inDeviceRef: The target IOBluetoothDeviceRef.
inCallback: The callback to call when the remote name request is complete.
inUserRefCon: User-supplied reference that will be passed to the callback.
outDeviceName: Contains the device name if the request is synchronous and completes successfully.
inTimeout: User supplied page timeout value to use for the remote name request call.

Return Value

Returns kIOReturnSuccess if the remote name request was successfully issued (and if synchronous, if the request completed successfully).

Discussion

NOTE: This function is only available in Mac OS X 10.2.7 (Bluetooth v1.3) or later.

IOBluetoothDeviceRemoveFromFavorites

Removes the target device from the user's list of favorite devices.

extern IOReturn IOBluetoothDeviceRemoveFromFavorites(
    IOBluetoothDeviceRef device) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns kIOReturnSuccess if the device was successfully removed from the user's list of favorite devices or if the device was not in the list at all.

Discussion

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothDeviceRequestAuthentication

Requests that the existing baseband connection be authenticated.

extern IOReturn IOBluetoothDeviceRequestAuthentication(
    IOBluetoothDeviceRef device);

Parameters

device: The target IOBluetoothDeviceRef.

Return Value

Returns kIOReturnSuccess if the connection has been successfully been authenticated. Returns an error if authentication fails or no baseband connection exists.

Discussion

In order to authenticate a baseband connection, a link key needs to be generated as a result of the pairing process. This call will synchronously initiate the pairing process with the target device and not return until the authentication process is complete. This API will be updated to allow for asynchronous operation.

IOBluetoothDeviceSendL2CAPEchoRequest

Send an echo request over the L2CAP connection to a remote device.

extern IOReturn IOBluetoothDeviceSendL2CAPEchoRequest(
    IOBluetoothDeviceRef btDevice,
    void *data,
    UInt16 length);

Parameters

btDevice: The target IOBluetoothDeviceRef.
data: A pointer to buffer to send.
length: The length of the buffer to send.

Return Value

Returns kIOReturnSuccess if the echo request was able to be sent.

Discussion

The current implementation returns when the request has been sent, but does not indicate when a response is received. Also, the baseband connection must be up for the echo request to be sent. In the future, this method will also open the connection if necessary. The API will be updated to allow the client to be informed when the echo response has been received (both synchronously and asynchronously).

IOBluetoothFavoriteDevices

Returns an array containing all of the user's favorite devices.

extern CFArrayRef IOBluetoothFavoriteDevices() AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Return Value

Returns a CFArray of IOBluetoothDeviceRef objects. The resulting CFArrayRef must be released by the caller by calling CFRelease().

Discussion

The CFArrayRef returned by this function must be released by calling CFRelease().

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothGetObjectIDFromArguments

Returns the BluetoothObjectID passed as an argument to an auto-launched app.

extern IOBluetoothObjectID IOBluetoothGetObjectIDFromArguments(
    int argc,
    const char *argv[] );

Parameters

argc: The argc parameter passed to main().
argv: The argv parameter passed to main().

Return Value

Returns the BluetoothObjectID passed in the given arguments. If no ID is present, kIOBluetoothObjectIDNULL is returned.

Discussion

When an application gets auto-launched by the blued process (as a result of an incoming connection to an appropriately configured service), it has a BluetoothObjectID passed to it on the command line. To get the BluetoothObjectID, simply pass the argc and argv parameters received in main() to this function. The returned BluetoothObjectID can then be used to find the appropriate IOBluetoothL2CAPChannel or IOBluetoothRFCOMMChannel depending on the type of service (using IOBluetoothL2CAPChannelCreateFromObjectID() or IOBluetoothRFCOMMChannelCreateFromObjectID.)

IOBluetoothGetVersion

Returns the versions of the bluetooth software and local hardware.

extern IOReturn IOBluetoothGetVersion(
    NumVersion *outSoftwareVersion,
    BluetoothHCIVersionInfo *outHardwareVersion );

Parameters

outSoftwareVersion: Bluetooth software stack version. This parameter is optional.
outHardwareVersion: HCI/Controller version information. This parameter is optional.

Return Value

IOReturn Determines if successful at getting local hardware version or not.

Discussion

Error or not, the software version will be returned correctly.

IOBluetoothL2CAPChannelCloseChannel

Initiates the close process on an open L2CAP channel.

extern IOReturn IOBluetoothL2CAPChannelCloseChannel(
    IOBluetoothL2CAPChannelRef l2capChannel);

Parameters

l2capChannel: Target L2CAP channel ref.

Return Value

Returns kIOReturnSuccess on success.

Discussion

This method may only be called by the client that opened the channel in the first place. In the future asynchronous and synchronous versions will be provided that let the client know when the close process has been finished.

IOBluetoothL2CAPChannelCreateFromObjectID

Returns the IOBluetoothL2CAPChannelRef with the given IOBluetoothObjectID.

extern IOBluetoothL2CAPChannelRef IOBluetoothL2CAPChannelCreateFromObjectID(
    IOBluetoothObjectID objectID );

Parameters

objectID: IOBluetoothObjectID of the desired IOBluetoothL2CAPChannelRef.

Return Value

Returns the IOBluetoothL2CAPChannelRef that matches the given IOBluetoothObjectID if one exists. The resulting IOBluetoothL2CAPChannelRef must be released by the caller by calling IOBluetoothObjectRelease. If no matching L2CAP channel exists, NULL is returned.

Discussion

The IOBluetoothObjectID can be used as a global reference for a given IOBluetoothL2CAPChannelRef. It allows two separate applications to refer to the same IOBluetoothL2CAPChannelRef.

IOBluetoothL2CAPChannelGetDevice

Returns the IOBluetoothDevice to which the target L2CAP channel is open.

extern IOBluetoothDeviceRef IOBluetoothL2CAPChannelGetDevice(
    IOBluetoothL2CAPChannelRef l2capChannel);

Parameters

l2capChannel: Target L2CAP channel ref.

Return Value

Returns the IOBluetoothDevice to which the target L2CAP channel is open. The caller does NOT need to release the returned IOBluetoothDeviceRef.

IOBluetoothL2CAPChannelGetIncomingMTU

Returns the current incoming MTU for the L2CAP channel.

extern BluetoothL2CAPMTU IOBluetoothL2CAPChannelGetIncomingMTU(
    IOBluetoothL2CAPChannelRef l2capChannel);

Parameters

l2capChannel: Target L2CAP channel ref.

Return Value

Returns the current incoming MTU for the L2CAP channel.

Discussion

The incoming MTU represents the maximum L2CAP packet size for packets being sent by the remote device.

IOBluetoothL2CAPChannelGetLocalChannelID

Returns the local L2CAP channel ID for the target L2CAP channel.

extern BluetoothL2CAPChannelID IOBluetoothL2CAPChannelGetLocalChannelID(
    IOBluetoothL2CAPChannelRef l2capChannel);

Parameters

l2capChannel: Target L2CAP channel ref.

Return Value

Returns the local L2CAP channel ID for the target L2CAP channel.

IOBluetoothL2CAPChannelGetObjectID

Returns the IOBluetoothObjectID of the given IOBluetoothL2CAPChannelRef.

extern IOBluetoothObjectID IOBluetoothL2CAPChannelGetObjectID(
    IOBluetoothL2CAPChannelRef l2capChannel );

Parameters

l2capChannel: Target IOBluetoothL2CAPChannelRef.

Return Value

Returns the IOBluetoothObjectID of the given IOBluetoothl2CAPChannelRef.

Discussion

The IOBluetoothObjectID can be used as a global reference for a given IOBluetoothL2CAPChannelRef. It allows two separate applications to refer to the same IOBluetoothL2CAPChannelRef.

IOBluetoothL2CAPChannelGetOutgoingMTU

Returns the current outgoing MTU for the L2CAP channel.

extern BluetoothL2CAPMTU IOBluetoothL2CAPChannelGetOutgoingMTU(
    IOBluetoothL2CAPChannelRef l2capChannel);

Parameters

l2capChannel: Target L2CAP channel ref.

Return Value

Returns the current outgoing MTU for the L2CAP channel.

Discussion

The outgoing MTU represents the maximum L2CAP packet size for packets being sent to the remote device.

IOBluetoothL2CAPChannelGetPSM

Returns the PSM for the target L2CAP channel.

extern BluetoothL2CAPPSM IOBluetoothL2CAPChannelGetPSM(
    IOBluetoothL2CAPChannelRef l2capChannel);

Parameters

l2capChannel: Target L2CAP channel ref.

Return Value

Returns the PSM for the target L2CAP channel.

IOBluetoothL2CAPChannelGetRemoteChannelID

Returns the remote L2CAP channel ID for the target L2CAP channel.

extern BluetoothL2CAPChannelID IOBluetoothL2CAPChannelGetRemoteChannelID(
    IOBluetoothL2CAPChannelRef l2capChannel);

Parameters

l2capChannel: Target L2CAP channel ref.

Return Value

Returns the remote L2CAP channel ID for the target L2CAP channel.

IOBluetoothL2CAPChannelIsIncoming

Returns TRUE if the channel is an incoming channel.

extern Boolean IOBluetoothL2CAPChannelIsIncoming(
    IOBluetoothL2CAPChannelRef l2capChannel);

Parameters

l2capChannel: Target L2CAP channel ref.

Return Value

Returns TRUE if the channel is an incoming channel.

Discussion

An incoming channel is one that was initiated by a remote device.

IOBluetoothL2CAPChannelRegisterForChannelCloseNotification

Allows a client to register for a channel close notification.

IOBluetoothUserNotificationRef IOBluetoothL2CAPChannelRegisterForChannelCloseNotification(
    IOBluetoothL2CAPChannelRef channel, 
    IOBluetoothUserNotificationCallback callback, 
    void *inRefCon );

Parameters

channel: The target L2CAP channel.
callback: Callback to be called when the L2CAP channel is closed.
inRefCon: Client-supplied refCon to be passed to the callback.

Return Value

Returns an IOBluetoothUserNotificationRef representing the outstanding L2CAP channel close notification. To unregister the notification, call IOBluetoothUserNotificationUnregister() with the returned IOBluetoothUserNotificationRef. If an error is encountered creating the notification, NULL is returned. The returned IOBluetoothUserNotificationRef will be valid for as long as the notification is registered. It is not necessary to retain the result. Once the notification is unregistered, it will no longer be valid.

Discussion

The given callback will be called when the L2CAP channel is closed.

IOBluetoothL2CAPChannelRegisterIncomingDataListener

Allows a client to register a callback that gets called when new incoming data arrives.

extern IOReturn IOBluetoothL2CAPChannelRegisterIncomingDataListener(
    IOBluetoothL2CAPChannelRef l2capChannel,
    IOBluetoothL2CAPChannelIncomingDataListener listener,
    void *refCon);

Parameters

l2capChannel: Target L2CAP channel ref.
listener: Callback function that gets called when new incoming data is received.
refCon: Client-supplied reference that gets passed to the listener function.

Return Value

Returns kIOReturnSuccess if the listener is successfully registered.

Discussion

A newly opened L2CAP channel will not complete its configuration process until the client that opened it registers an incoming data listener. This prevents that case where incoming data is received before the client is ready.

IOBluetoothL2CAPChannelRegisterIncomingEventListener

Registers a callback for events.

extern IOReturn IOBluetoothL2CAPChannelRegisterIncomingEventListener(
    IOBluetoothL2CAPChannelRef l2capChannel,
    IOBluetoothL2CAPChannelIncomingEventListener listener,
    void *refCon) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

l2capChannel: The channel reference.
listener: The callback function.
refCon: A void*, its meaning is up to the developer. This parameter will be passed back as second parameter of the callback function.

Return Value

Returns an error code value. 0 if successful.

Discussion

Registers a callback for events generated by the L2CAP channel. The form for the callback is:

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothL2CAPChannelRequestRemoteMTU

Initiates the process to reconfigure the L2CAP channel with a new outgoing MTU.

extern IOReturn IOBluetoothL2CAPChannelRequestRemoteMTU(
    IOBluetoothL2CAPChannelRef l2capChannel,
    BluetoothL2CAPMTU remoteMTU );

Parameters

l2capChannel: Target L2CAP channel ref.
remoteMTU: The desired outgoing MTU.

Return Value

Returns kIOReturnSuccess if the channel re-configure process was successfully initiated.

Discussion

Currently, this API does not give an indication that the re-config process has completed. In the future additional API will be available to provide that information both synchronously and asynchronously.

IOBluetoothL2CAPChannelWrite

Writes the given data over the target L2CAP channel to the remote device.

extern IOReturn IOBluetoothL2CAPChannelWrite(
    IOBluetoothL2CAPChannelRef l2capChannel,
    void *data,
    UInt16 length) DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER;

Parameters

l2capChannel: Target L2CAP channel ref.
data: Pointer to the buffer containing the data to send.
length: The length of the given data buffer.

Return Value

Returns kIOReturnSuccess if the data was buffered successfully.

Discussion

The length of the data may not exceed the L2CAP channel's ougoing MTU.

IOBluetoothL2CAPChannelWriteAsync

Writes asynchronously the given data over the target L2CAP channel to the remote device.

extern IOReturn IOBluetoothL2CAPChannelWriteAsync(
    IOBluetoothL2CAPChannelRef l2capChannel,
    void *data,
    UInt16 length,
    void *refcon) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

l2capChannel: Target L2CAP channel ref.
data: Pointer to the buffer containing the data to send.
length: The length of the given data buffer.
refcon: A write identificator (is a void*, so it is up to the developer) that will be returned in the kIOBluetoothL2CAPWriteCompletedEvent.

Return Value

Returns kIOReturnSuccess if the data was buffered successfully.

Discussion

The length of the data may not exceed the L2CAP channel's ougoing MTU.

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothL2CAPChannelWriteSync

Writes synchronously the given data over the target L2CAP channel to the remote device.

extern IOReturn IOBluetoothL2CAPChannelWriteSync(
    IOBluetoothL2CAPChannelRef l2capChannel,
    void *data,
    UInt16 length) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

l2capChannel: Target L2CAP channel ref.
data: Pointer to the buffer containing the data to send.
length: The length of the given data buffer.

Return Value

Returns kIOReturnSuccess if the data was buffered successfully.

Discussion

The length of the data may not exceed the L2CAP channel's ougoing MTU. This method may block if previous writes have not been delivered.

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothLocalDeviceAvailable

Determines if a bluetooth device is available on a local machine or not.

extern Boolean IOBluetoothLocalDeviceAvailable();

Return Value

A Boolean value. TRUE if a Bluetooth device is connected to the local machine, FALSE otherwise.

Discussion

Determines if a bluetooth device is available on a local machine or not.

IOBluetoothLocalDeviceGetDiscoverable

Returns the discoverability state of the local device.

extern IOReturn IOBluetoothLocalDeviceGetDiscoverable(
    Boolean *discoverableStatus);

Parameters

discoverableStatus: is a pointer to boolean, it will hold the discoverabilty state.

Return Value

An error code value. 0 if successful.

Discussion

Returns the discoverability state of the local device.

IOBluetoothLocalDeviceGetPowerState

Determines the current power state of the Bluetooth hardware.

extern IOReturn IOBluetoothLocalDeviceGetPowerState(
    BluetoothHCIPowerState *powerState) AVAILABLE_BLUETOOTH_VERSION_1_1_AND_LATER;

Return Value

An error code value. 0 if successful.

Discussion

If successful, it passes the current power state of the Bluetooth hardware back to the caller.

NOTE: This function is only available in Mac OS X 10.2.4 (Bluetooth v1.1) or later.

IOBluetoothLocalDeviceReadAddress

extern IOReturn IOBluetoothLocalDeviceReadAddress(
    BluetoothDeviceAddress *outResults, 
    IOBluetoothReadAddressCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadAuthenticationEnable

extern IOReturn IOBluetoothLocalDeviceReadAuthenticationEnable(
    BluetoothHCIAuthenticationEnable *outResults, 
    IOBluetoothReadAuthenticationEnableCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadClassOfDevice

extern IOReturn IOBluetoothLocalDeviceReadClassOfDevice(
    BluetoothClassOfDevice *outResults, 
    IOBluetoothReadClassOfDeviceCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadConnectionAcceptTimeout

extern IOReturn IOBluetoothLocalDeviceReadConnectionAcceptTimeout(
    BluetoothHCIConnectionAcceptTimeout *outResults, 
    IOBluetoothReadConnectionAcceptTimeoutCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadEncryptionMode

extern IOReturn IOBluetoothLocalDeviceReadEncryptionMode(
    BluetoothHCIEncryptionMode *outResults, 
    IOBluetoothReadEncryptionModeCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadName

extern IOReturn IOBluetoothLocalDeviceReadName(
    BluetoothDeviceName outResults, 
    IOBluetoothReadNameCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadPageScanMode

extern IOReturn IOBluetoothLocalDeviceReadPageScanMode(
    BluetoothHCIPageScanMode *outResults, 
    IOBluetoothReadPageScanModeCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadPageScanPeriodMode

extern IOReturn IOBluetoothLocalDeviceReadPageScanPeriodMode(
    BluetoothHCIPageScanPeriodMode *outResults, 
    IOBluetoothReadPageScanPeriodModeCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadPageTimeout

extern IOReturn IOBluetoothLocalDeviceReadPageTimeout(
    BluetoothHCIPageTimeout *outResults, 
    IOBluetoothReadPageTimeoutCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadScanEnable

extern IOReturn IOBluetoothLocalDeviceReadScanEnable(
    BluetoothHCIPageScanMode *outResults, 
    IOBluetoothReadPageScanEnableCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadSupportedFeatures

extern IOReturn IOBluetoothLocalDeviceReadSupportedFeatures(
    BluetoothHCISupportedFeatures *outResults, 
    IOBluetoothReadLocalSupportedFeaturesCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothLocalDeviceReadVersionInformation

extern IOReturn IOBluetoothLocalDeviceReadVersionInformation(
    BluetoothHCIVersionInfo *outResults, 
    IOBluetoothReadLocalVersionInformationCallback inCallback, 
    void *inUserRefCon, 
    void *reserved );

Parameters

outResults
inCallback
inUserRefCon
reserved: Pass NULL here.

Return Value

An error code value. 0 if successful.

IOBluetoothObjectRelease

Decrements the ref count on the target object.

extern void IOBluetoothObjectRelease(
    IOBluetoothObjectRef bluetoothObject );

Parameters

bluetoothObject: The target IOBluetoothObjectRef.

Discussion

The ref counting scheme allows the IOBluetoothObjectRefs to be freed when they are no longer used. When the ref count reaches zero, the target object will be freed.

IOBluetoothObjectRetain

Increments the ref count on the target object.

extern IOBluetoothObjectRef IOBluetoothObjectRetain(
    IOBluetoothObjectRef bluetoothObject );

Parameters

bluetoothObject: The target IOBluetoothObjectRef.

Return Value

Returns the IOBluetoothObjectRef passed in with one more ref count.

Discussion

The Bluetooth user lib implements a reference counting scheme similar to CoreFoundation. In general, any function that is named with Create returns an IOBluetoothObjectRef that must be released by the caller. Unless otherwise documented, the other functions do not return an object that must be released. However, if the caller wants to keep a reference to the returned object outside of the caller's scope, that object must be retained.

IOBluetoothPairedDevices

Returns an array of the currently paired devices.

extern CFArrayRef IOBluetoothPairedDevices() AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Return Value

Returns a CFArray of IOBluetoothDeviceRef objects. The resulting CFArrayRef must be released by the caller by calling CFRelease().

Discussion

The CFArrayRef returned by this function must be released by calling CFRelease().

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothRecentDevices

Returns an array of the most recently accessed devices.

extern CFArrayRef IOBluetoothRecentDevices(
    unsigned long numDevices) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

numDevices: The number of recent devices to return. If numDevices is zero, all devices accessed by the user will be returned.

Return Value

Returns a CFArray of the most recently accessed IOBluetoothDeviceRef objects. The resulting CFArrayRef must be released by the caller by calling CFRelease().

Discussion

The CFArrayRef returned by this function must be released by calling CFRelease().

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothRegisterForDeviceConnectNotifications

Allows a client to register for device connect notifications for any connection.

IOBluetoothUserNotificationRef IOBluetoothRegisterForDeviceConnectNotifications(
    IOBluetoothUserNotificationCallback callback, 
    void *inRefCon );

Parameters

callback: The callback to be called when a new connection is made.
inRefCon: Client-supplied refCon to be passed to the callback.

Return Value

Returns an IOBluetoothUserNotificationRef representing the outstanding device connect notification. To unregister the notification, call IOBluetoothUserNotificationUnregister() with the returned IOBluetoothUserNotificationRef. If an error is encountered creating the notification, NULL is returned. The returned IOBluetoothUserNotificationRef will be valid for as long as the notification is registered. It is not necessary to retain the result. Once the notification is unregistered, it will no longer be valid.

Discussion

The given callback will be called whenever any device connection is made.

IOBluetoothRegisterForFilteredL2CAPChannelOpenNotifications

Allows a client to register for L2CAP channel open notifications for certain types of L2CAP channels.

IOBluetoothUserNotificationRef IOBluetoothRegisterForFilteredL2CAPChannelOpenNotifications(
    IOBluetoothUserNotificationCallback callback, 
    void *inRefCon, 
    BluetoothL2CAPPSM inPSM, 
    IOBluetoothUserNotificationChannelDirection inDirection );

Parameters

callback: The callback to be called when a new L2CAP channel is opened.
inRefCon: Client-supplied refCon to be passed to the callback.
inPSM: PSM to match a new L2CAP channel. If the PSM doesn't matter, 0 may be passed in.
inDirection: The desired direction of the L2CAP channel - kIOBluetoothUserNotificationChannelDirectionAny if the direction doesn't matter.

Return Value

Returns an IOBluetoothUserNotificationRef representing the outstanding L2CAP channel notification. To unregister the notification, call IOBluetoothUserNotificationUnregister() with the returned IOBluetoothUserNotificationRef. If an error is encountered creating the notification, NULL is returned. The returned IOBluetoothUserNotificationRef will be valid for as long as the notification is registered. It is not necessary to retain the result. Once the notification is unregistered, it will no longer be valid.

Discussion

The given callback will be called whenever any L2CAP channel is opened.

IOBluetoothRegisterForFilteredRFCOMMChannelOpenNotifications

Allows a client to register for RFCOMM channel open notifications for certain types of RFCOMM channels.

IOBluetoothUserNotificationRef IOBluetoothRegisterForFilteredRFCOMMChannelOpenNotifications(
    IOBluetoothUserNotificationCallback callback, 
    void *inRefCon, 
    BluetoothRFCOMMChannelID channelID, 
    IOBluetoothUserNotificationChannelDirection inDirection );

Parameters

callback: The callback to be called when a new RFCOMM channel is opened.
inRefCon: Client-supplied refCon to be passed to the callback.
channelID: RFCOMM channel ID to match a new RFCOMM channel. If the channel ID doesn't matter, 0 may be passed in.
inDirection: The desired direction of the RFCOMM channel - kIOBluetoothUserNotificationChannelDirectionAny if the direction doesn't matter.

Return Value

Returns an IOBluetoothUserNotificationRef representing the outstanding RFCOMM channel notification. To unregister the notification, call IOBluetoothUserNotificationUnregister() with the returned IOBluetoothUserNotificationRef. If an error is encountered creating the notification, NULL is returned. The returned IOBluetoothUserNotificationRef will be valid for as long as the notification is registered. It is not necessary to retain the result. Once the notification is unregistered, it will no longer be valid.

Discussion

The given callback will be called whenever any RFCOMM channel is opened.

IOBluetoothRegisterForL2CAPChannelOpenNotifications

Allows a client to register for L2CAP channel open notifications for any L2CAP channel.

IOBluetoothUserNotificationRef IOBluetoothRegisterForL2CAPChannelOpenNotifications(
    IOBluetoothUserNotificationCallback callback, 
    void *inRefCon );

Parameters

callback: The callback to be called when a new L2CAP channel is opened.
inRefCon: Client-supplied refCon to be passed to the callback.

Return Value

Discussion

The given callback will be called whenever any L2CAP channel is opened.

IOBluetoothRegisterForRFCOMMChannelOpenNotifications

Allows a client to register for RFCOMM channel open notifications for any RFCOMM channel.

IOBluetoothUserNotificationRef IOBluetoothRegisterForRFCOMMChannelOpenNotifications(
    IOBluetoothUserNotificationCallback callback, 
    void *inRefCon );

Parameters

callback: The callback to be called when a new RFCOMM channel is opened.
inRefCon: Client-supplied refCon to be passed to the callback.

Return Value

Discussion

The given callback will be called whenever any RFCOMM channel is opened.

IOBluetoothRemoveSCOAudioDevice

Removes a persistent audio driver for a device that had already been added using IOBluetoothAddAudioDevice().

extern IOReturn IOBluetoothRemoveSCOAudioDevice(
    IOBluetoothDeviceRef device ) AVAILABLE_BLUETOOTH_VERSION_1_6_AND_LATER;

Parameters

device: Bluetooth audio device to remove

Return Value

Returns kIOReturnSuccess if the audio driver was successfully removed.

IOBluetoothRemoveServiceWithRecordHandle

Removes the given service from the local SDP server.

extern IOReturn IOBluetoothRemoveServiceWithRecordHandle(
    BluetoothSDPServiceRecordHandle serviceRecordHandle );

Parameters

serviceRecordHandle: The handle of the service to be removed.

Return Value

Returns kIOReturnSuccess if successful.

Discussion

The service record handle passed to this function must match the handle in the service record returned by IOBluetoothAddServiceDict.

IOBluetoothRFCOMMChannelCloseChannel

extern IOReturn IOBluetoothRFCOMMChannelCloseChannel(
    IOBluetoothRFCOMMChannelRef rfcommChannel);

Parameters

rfcommChannel: The channel reference.

Return Value

Returns an error code value. 0 if successful.

IOBluetoothRFCOMMChannelCreateFromObjectID

Returns the IOBluetoothRFCOMMChannelRef with the given IOBluetoothObjectID.

extern IOBluetoothRFCOMMChannelRef IOBluetoothRFCOMMChannelCreateFromObjectID(
    IOBluetoothObjectID objectID );

Parameters

objectID: IOBluetoothObjectID of the desired IOBluetoothRFCOMMChannelRef.

Return Value

Returns the IOBluetoothRFCOMMChannelRef that matches the given IOBluetoothObjectID if one exists. The resulting IOBluetoothRFCOMMChannelRef must be released by the caller by calling IOBluetoothObjectRelease. If no matching RFCOMM channel exists, NULL is returned.

Discussion

The IOBluetoothObjectID can be used as a global reference for a given IOBluetoothRFCOMMChannelRef. It allows two separate applications to refer to the same IOBluetoothRFCOMMChannelRef.

IOBluetoothRFCOMMChannelGetChannelID

Returns the RFCOMM channel number for a given IOBluetoothRFCOMMChannelRef.

extern BluetoothRFCOMMChannelID IOBluetoothRFCOMMChannelGetChannelID(
    IOBluetoothRFCOMMChannelRef rfcommChannel );

Parameters

rfcommChannel: The channel reference.

Return Value

Returns the RFCOMM channel number for this channel.

Discussion

Returns the RFCOMM channel number for a given IOBluetoothRFCOMMChannelRef.

IOBluetoothRFCOMMChannelGetDevice

extern IOBluetoothDeviceRef IOBluetoothRFCOMMChannelGetDevice(
    IOBluetoothRFCOMMChannelRef rfcommChannel);

Parameters

rfcommChannel: The channel reference.

Return Value

Returns a reference to the device where this RFCOMM channel was open. 0 if unsuccessful. The caller does NOT need to release the returned IOBluetoothDeviceRef.

IOBluetoothRFCOMMChannelGetMTU

extern BluetoothRFCOMMMTU IOBluetoothRFCOMMChannelGetMTU(
    IOBluetoothRFCOMMChannelRef rfcommChannel );

Parameters

rfcommChannel: The channel reference.

Return Value

Returns the channel MTU size.

Discussion

Returns the length of the largest chunk of data that this channel can carry. If the caller wishes to use the write:length:sleep: api the length of the data can not be bigger than the channel MTU (maximum transfer unit).

IOBluetoothRFCOMMChannelGetObjectID

Returns the IOBluetoothObjectID of the given IOBluetoothRFCOMMChannelRef.

extern IOBluetoothObjectID IOBluetoothRFCOMMChannelGetObjectID(
    IOBluetoothRFCOMMChannelRef rfcommChannel );

Parameters

rfcommChannel: Target IOBluetoothRFCOMMChannelRef.

Return Value

Returns the IOBluetoothObjectID of the given IOBluetoothRFCOMMChannelRef.

Discussion

The IOBluetoothObjectID can be used as a global reference for a given IOBluetoothRFCOMMChannelRef. It allows two separate applications to refer to the same IOBluetoothRFCOMMChannelRef.

IOBluetoothRFCOMMChannelIsIncoming

Returns the direction of the channel.

extern Boolean IOBluetoothRFCOMMChannelIsIncoming(
    IOBluetoothRFCOMMChannelRef rfcommChannel);

Parameters

rfcommChannel: The channel reference.

Return Value

Returns TRUE if the channel was opened by the remote device, FALSE if the channel was opened by this object.

Discussion

An incoming channel is one that was opened by the remote device.

IOBluetoothRFCOMMChannelIsOpen

extern Boolean IOBluetoothRFCOMMChannelIsOpen(
    IOBluetoothRFCOMMChannelRef rfcommChannel);

Parameters

rfcommChannel: The channel reference.

Return Value

Returns true if the channel is open false if the channel is not open.

Discussion

Note that "not open" means closed, opening and closing.

IOBluetoothRFCOMMChannelIsTransmissionPaused

extern Boolean IOBluetoothRFCOMMChannelIsTransmissionPaused(
    IOBluetoothRFCOMMChannelRef rfcommChannel );

Parameters

rfcommChannel: The channel reference.

Return Value

Returns true if the action of sending data will block the current thread, false otherwise.

Discussion

Returns true if the remote device flow control is stopping out transmission. This is useful because we do not buffer data, we stop the transmitting actor. With this method the transmitter can check if sending data is going to be successful or is going to block.

IOBluetoothRFCOMMChannelRegisterForChannelCloseNotification

Allows a client to register for a channel close notification.

IOBluetoothUserNotificationRef IOBluetoothRFCOMMChannelRegisterForChannelCloseNotification(
    IOBluetoothRFCOMMChannelRef inChannel, 
    IOBluetoothUserNotificationCallback callback, 
    void *inRefCon );

Parameters

channel: The target RFCOMM channel.
callback: Callback to be called when the RFCOMM channel is closed.
inRefCon: Client-supplied refCon to be passed to the callback.

Return Value

Returns an IOBluetoothUserNotificationRef representing the outstanding RFCOMM channel close notification. To unregister the notification, call IOBluetoothUserNotificationUnregister() with the returned IOBluetoothUserNotificationRef. If an error is encountered creating the notification, NULL is returned. The returned IOBluetoothUserNotificationRef will be valid for as long as the notification is registered. It is not necessary to retain the result. Once the notification is unregistered, it will no longer be valid.

Discussion

The given callback will be called when the RFCOMM channel is closed.

IOBluetoothRFCOMMChannelRegisterIncomingDataListener

Registers a callback for the incoming data.

extern IOReturn IOBluetoothRFCOMMChannelRegisterIncomingDataListener(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    IOBluetoothRFCOMMChannelIncomingDataListener listener,
    void *refCon) DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER;

Parameters

rfcommChannel: The channel reference.
listener: The callback function.
refCon: A void*, its meaning is up to the developer. This parameter will be passed back as last parameter of the callback function.

Return Value

Returns an error code value. 0 if successful.

Discussion

The form for the callback is:

void function(IOBluetoothRFCOMMChannelRef rfcommChannel, void *data, UInt16 length, void *refCon)

where rfcommChannel is the refernce to the channel that received data, data is a buffer with the received data, length is the buffer length (in bytes) and refCon is a user defined void* (maybe the reference to the object to call back ?).

IOBluetoothRFCOMMChannelRegisterIncomingEventListener

Registers a callback for events.

extern IOReturn IOBluetoothRFCOMMChannelRegisterIncomingEventListener(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    IOBluetoothRFCOMMChannelIncomingEventListener listener,
    void *refCon);

Parameters

rfcommChannel: The channel reference.
listener: The callback function.
refCon: A void*, its meaning is up to the developer. This parameter will be passed back as second parameter of the callback function.

Return Value

Returns an error code value. 0 if successful.

Discussion

Registers a callback for events generated by the RFCOMM channel. The form for the callback is:

void function(IOBluetoothRFCOMMChannelRef rfcommChannel, void *refCon, IOBluetoothRFCOMMChannelEvent *event)

where rfcommChannel is the refernce to the channel that generated the event, refCon is a user defined void* (maybe the reference to the object to call back?) and event is the generated event. There are three types of events available:

kIOBluetoothRFCOMMNewDataEvent when new data is received.
kIOBluetoothRFCOMMFlowControlChangedEvent change of flow control.
kIOBluetoothRFCOMMChannelTerminatedEvent when the rfcomm channel is no more valid.

Note that the kIOBluetoothRFCOMMNewDataEvent provides the same functionality of the data listener callback. This means that if the developer has both an event callback and a data listener callback both functions will be called when new data arrives. It is up to the developer to properly filter the events (or better, to use only one callback). For a better descriptions of the events and the event structure see IOBluetoothUserLib.h.

IOBluetoothRFCOMMChannelWrite

Writes data to an RFCOMM channel synchronusly.

extern IOReturn IOBluetoothRFCOMMChannelWrite(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    void *data,
    UInt16 length,
    Boolean sleepFlag) DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER;

Parameters

rfcommChannel: The channel reference.
data: A pointer to the data buffer to be sent.
length: The length of the buffer to be sent (in bytes).
sleepFlag: A Boolean value: if set to TRUE the call will wait until it is possible to send data, if set to FALSE and it is not possible to send data the method will return immediately with an error.

Return Value

Returns an error code value. 0 if successful.

Discussion

Sends data through the channel. The number of bytes to be sent must not exceed the channel MTU. If the return value is an error condition none of the data was sent.

IOBluetoothRFCOMMChannelWriteAsync

Writes data to an RFCOMM channel asynchronously.

extern IOReturn IOBluetoothRFCOMMChannelWriteAsync(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    void *data,
    UInt16 length,
    void *refcon) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

rfcommChannel: The channel reference.
data: A pointer to the data buffer to be sent.
length: The length of the buffer to be sent (in bytes).
refcon: A NON NULL value that will be contained in the return event (once the data is sent).

Return Value

Returns an error code value. 0 if successful.

Discussion

Sends data through the channel. The number of bytes to be sent must not exceed the channel MTU. If the return value is an error condition none of the data was sent.

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothRFCOMMChannelWriteSimple

extern IOReturn IOBluetoothRFCOMMChannelWriteSimple(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    void *data,
    UInt16 length,
    Boolean sleepFlag,
    UInt32 *numBytesSent) DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER;

Parameters

rfcommChannel: The channel reference
data: A pointer to the data buffer to be sent.
length: The length of the buffer to be sent (in bytes).
sleepFlag: A Boolean value: if set to true the call will wait until it is possible to send all the data, if set to FALSE and it is not possible to send part of the data the method will return immediately.
numBytesSent: A UInt32 pointer in which the caller received the number of bytes sent.

Return Value

Returns an error code value. 0 if successful.

Discussion

Sends data through the channel. The number of bytes to be sent is arbitrary. The caller does not have to worry about the MTU.

IOBluetoothRFCOMMChannelWriteSync

Writes data to an RFCOMM channel synchronously.

extern IOReturn IOBluetoothRFCOMMChannelWriteSync(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    void *data,
    UInt16 length) AVAILABLE_BLUETOOTH_VERSION_1_2_AND_LATER;

Parameters

rfcommChannel: The channel reference
data: A pointer to the data buffer to be sent.
length: The length of the buffer to be sent (in bytes).

Return Value

Returns an error code value. 0 if successful.

Discussion

Sends data through the channel. The number of bytes to be sent must not exceed the channel MTU. If the return value is an error condition none of the data was sent.

NOTE: This function is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

IOBluetoothRFCOMMSendRemoteLineStatus

extern IOReturn IOBluetoothRFCOMMSendRemoteLineStatus(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    BluetoothRFCOMMLineStatus lineStatus);

Parameters

rfcommChannel: The channel reference.
lineStatus: The error code (can be NoError, OverrunError, ParityError or FramingError).

Return Value

Returns an error code value. 0 if successful.

IOBluetoothRFCOMMSetSerialParameters

extern IOReturn IOBluetoothRFCOMMSetSerialParameters(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    UInt32 speed,
    UInt8 nBits,
    BluetoothRFCOMMParityType parity,
    UInt8 bitStop);

Parameters

rfcommChannel: The channel reference.
speed
nBits
parity
bitStop

Return Value

Returns an error code value. 0 if successful.

IOBluetoothSDPDataElementContainsDataElement

Checks to see if the target data element is the same as the dataElement parameter or if it contains the dataElement parameter (if its a sequence type).

extern Boolean IOBluetoothSDPDataElementContainsDataElement(
    IOBluetoothSDPDataElementRef dataElement,
    IOBluetoothSDPDataElementRef subDataElement);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.
subDataElement: The data element to compare with (and search for).

Return Value

Returns TRUE if the target either matches the given data element or if it contains the given data element.

Discussion

If the target data element is not a sequence type, this method simply compares the two data elements. If it is a sequence type, it will search through the sequence (and sub-sequences) for the dataElement parameter.

IOBluetoothSDPDataElementGetArrayValue

Returns the value of the data element as a CFArrayRef, if the data element is represented by an array object.

extern CFArrayRef IOBluetoothSDPDataElementGetArrayValue(
    IOBluetoothSDPDataElementRef dataElement);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.

Return Value

Returns a CFArrayRef representation of the data element if it is a sequence type. The caller is NOT responsible for releasing the returned CFArrayRef.

Discussion

The data types represented by an array object are 6 (data element sequence) and 7 (data element alternative).

IOBluetoothSDPDataElementGetDataValue

Returns the value of the data element as a CFDataRef, if the data element is represented by a data object.

extern CFDataRef IOBluetoothSDPDataElementGetDataValue(
    IOBluetoothSDPDataElementRef dataElement);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.

Return Value

Returns a CFDataRef representation of the data element if it is a 128-bit number. The caller is NOT responsible for releasing the returned IOBluetoothSDPDataElementRef.

Discussion

The data types represented by a data object are 128-bit versions of 1 (unsigned int) and 2 (signed int).

IOBluetoothSDPDataElementGetNumberValue

Returns the value of the data element as a CFNumberRef, if the data element is represented by a number.

extern CFNumberRef IOBluetoothSDPDataElementGetNumberValue(
    IOBluetoothSDPDataElementRef dataElement);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.

Return Value

Returns a CFNumberRef representation of the data element if it is a numeric type. The caller is NOT responsible for releasing the returned CFNumberRef.

Discussion

The data types represented by a number are 1 (unsigned int), 2 (signed int) and 5 (boolean) except for 128-bit versions of 1 and 2.

IOBluetoothSDPDataElementGetSize

Returns the size in bytes of the target data element.

extern UInt32 IOBluetoothSDPDataElementGetSize(
    IOBluetoothSDPDataElementRef dataElement);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.

Return Value

Returns the size in bytes of the target data element.

Discussion

The size is valid whether the data element has a fixed or variable size descriptor.

IOBluetoothSDPDataElementGetSizeDescriptor

Returns the SDP spec defined data element size descriptor for the target data element.

extern BluetoothSDPDataElementSizeDescriptor IOBluetoothSDPDataElementGetSizeDescriptor(
    IOBluetoothSDPDataElementRef dataElement);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.

Return Value

Returns the size descriptor for the target data element.

IOBluetoothSDPDataElementGetStringValue

Returns the value of the data element as a CFStringRef, if the data element is represented by a string object.

extern CFStringRef IOBluetoothSDPDataElementGetStringValue(
    IOBluetoothSDPDataElementRef dataElement);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.

Return Value

Returns a CFStringRef representation of the data element if it is a text or URL type. The caller is NOT responsible for releasing the returned CFStringRef.

Discussion

The data types represented by a string object are 4 (text string) and 8 (URL).

IOBluetoothSDPDataElementGetTypeDescriptor

Returns the SDP spec defined data element type descriptor for the target data element.

extern BluetoothSDPDataElementTypeDescriptor IOBluetoothSDPDataElementGetTypeDescriptor(
    IOBluetoothSDPDataElementRef dataElement);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.

Return Value

Returns the type descriptor for the target data element.

IOBluetoothSDPDataElementGetUUIDValue

Returns the value of the data element as an IOBluetoothSDPUUIDRef, if the data element is a UUID (type 3).

extern IOBluetoothSDPUUIDRef IOBluetoothSDPDataElementGetUUIDValue(
    IOBluetoothSDPDataElementRef dataElement);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.

Return Value

Returns an IOBluetoothSDPUUIDRef representation of the data element if it is a UUID. The caller is NOT responsible for releasing the returned IOBluetoothSDPUUIDRef.

IOBluetoothSDPDataElementIsEqualToDataElement

Compares the target data element with the given object.

extern Boolean IOBluetoothSDPDataElementIsEqualToDataElement(
    IOBluetoothSDPDataElementRef dataElement,
    IOBluetoothSDPDataElementRef dataElement2);

Parameters

dataElement: The target IOBluetoothSDPDataElementRef.
dataElement2: The IOBluetoothSDPDataElementRef to compare the target to.

Return Value

Returns TRUE if the target data element is the same as the given object or if it's value matches the given object.

Discussion

This method will compare a data element with either another data element or a data element value.

IOBluetoothSDPServiceRecordGetAttributeDataElement

Returns the data element for the given attribute ID in the target service.

extern IOBluetoothSDPDataElementRef IOBluetoothSDPServiceRecordGetAttributeDataElement(
    IOBluetoothSDPServiceRecordRef serviceRecord,
    BluetoothSDPServiceAttributeID attributeID);

Parameters

serviceRecord: The target IOBluetoothSDPServiceRecordRef.
attributeID: The attribute ID of the desired attribute.

Return Value

Returns the data element for the given attribute ID in the target service. If the service does not contain an attribute with the given ID, then NULL is returned.

IOBluetoothSDPServiceRecordGetAttributes

Returns a CFDictionaryRef containing the attributes for the service.

extern CFDictionaryRef IOBluetoothSDPServiceRecordGetAttributes(
    IOBluetoothSDPServiceRecordRef serviceRecord);

Parameters

serviceRecord: The target IOBluetoothSDPServiceRecordRef.

Return Value

Returns a CFDictionaryRef containing the attributes for the target service.

Discussion

The attribute dictionary is keyed off of the attribute id represented as a CFNumberRef. The values in the CFDictionaryRef are IOBluetoothSDPDataElementRefs representing the data element for the given attribute.

IOBluetoothSDPServiceRecordGetDevice

Returns the IOBluetoothDeviceRef that the target service belongs to.

extern IOBluetoothDeviceRef IOBluetoothSDPServiceRecordGetDevice(
    IOBluetoothSDPServiceRecordRef serviceRecord);

Parameters

serviceRecord: The target IOBluetoothSDPServiceRecordRef.

Return Value

Returns the IOBluetoothDeviceRef that the target service belongs to. If the service is one the local host is vending, then NULL is returned.

Discussion

If the service is a local service (i.e. one the current host is vending out), then NULL is returned.

IOBluetoothSDPServiceRecordGetL2CAPPSM

Allows the discovery of the L2CAP PSM assigned to the service.

extern IOReturn IOBluetoothSDPServiceRecordGetL2CAPPSM(
    IOBluetoothSDPServiceRecordRef serviceRecord,
    BluetoothL2CAPPSM *outPSM);

Parameters

serviceRecord: The target IOBluetoothSDPServiceRecordRef.
outPSM: A pointer to the location that will get the found L2CAP PSM.

Return Value

Returns kIOReturnSuccess if the PSM is found.

Discussion

This function will search through the ProtoclDescriptorList attribute to find an entry with the L2CAP UUID (UUID16: 0x0100). If one is found, it gets the second element of the data element sequence and sets the outPSM pointer to it. The PSM value only gets set when kIOReturnSuccess is returned.

IOBluetoothSDPServiceRecordGetRFCOMMChannelID

Allows the discovery of the RFCOMM channel ID assigned to the service.

extern IOReturn IOBluetoothSDPServiceRecordGetRFCOMMChannelID(
    IOBluetoothSDPServiceRecordRef serviceRecord,
    BluetoothRFCOMMChannelID *channelID);

Parameters

serviceRecord: The target IOBluetoothSDPServiceRecordRef.
channelID: A pointer to the location that will get the found RFCOMM channel ID.

Return Value

Returns kIOReturnSuccess if the channel ID is found.

Discussion

This function will search through the ProtoclDescriptorList attribute to find an entry with the RFCOMM UUID (UUID16: 0x0003). If one is found, it gets the second element of the data element sequence and sets the rfcommChannelID pointer to it. The channel ID only gets set when kIOReturnSuccess is returned.

IOBluetoothSDPServiceRecordGetServiceName

Returns the name of the service.

extern CFStringRef IOBluetoothSDPServiceRecordGetServiceName(
    IOBluetoothSDPServiceRecordRef serviceRecord);

Parameters

serviceRecord: The target IOBluetoothSDPServiceRecordRef.

Return Value

Returns the name of the target service.

Discussion

This is currently implemented to simply return the attribute with an id of 0x0100. In the future, it will be extended to allow name localization based on the user's chosen language or other languages.

IOBluetoothSDPServiceRecordGetServiceRecordHandle

Allows the discovery of the service record handle assigned to the service.

extern IOReturn IOBluetoothSDPServiceRecordGetServiceRecordHandle(
    IOBluetoothSDPServiceRecordRef serviceRecord,
    BluetoothSDPServiceRecordHandle *serviceRecordHandle);

Parameters

serviceRecord: The target IOBluetoothSDPServiceRecordRef.
serviceRecordHandle: A pointer to the location that will get the found service record handle.

Return Value

Returns kIOReturnSuccess if the service record handle is found.

Discussion

This method will search through the attributes to find the one representing the service record handle. If one is found the outServiceRecordHandle param is set with the value. The outServiceRecordHandle value only gets set when kIOReturnSuccess is returned.

IOBluetoothSDPServiceRecordHasServiceFromArray

Returns TRUE if any one of the UUIDs in the given array is found in the target service.

extern Boolean IOBluetoothSDPServiceRecordHasServiceFromArray(
    IOBluetoothSDPServiceRecordRef serviceRecord,
    CFArrayRef array);

Parameters

serviceRecord: The target IOBluetoothSDPServiceRecordRef.
array: An NSArray of IOBluetoothSDPUUIDRefs to search for in the target service.

Return Value

Returns TRUE if any of the given UUIDs are present in the service.

Discussion

The given array should contain IOBluetoothSDPUUIDRefs. It is currently implemented such that it returns TRUE if any of the UUIDs are found. However in the future, it is likely that this will change to more closely match the functionality in the SDP spec so that it only returns TRUE if all of the given UUIDs are present. That way, both AND and OR comparisons can be implemented. Please make a note of this potential change.

IOBluetoothSDPUUIDCreateUUID16

Creates a new 16-bit IOBluetoothSDPUUIDRef with the given UUID16.

extern IOBluetoothSDPUUIDRef IOBluetoothSDPUUIDCreateUUID16(
    BluetoothSDPUUID16 uuid16);

Parameters

uuid16: A scalar representing a 16-bit UUID.

Return Value

Returns the new IOBluetoothSDPUUIDRef or NULL on failure. The caller MUST release the returned IOBluetoothSDPUUIDRef by calling IOBluetoothObjectRelease().

IOBluetoothSDPUUIDCreateUUID32

Creates a new 32-bit IOBluetoothSDPUUIDRef with the given UUID32.

extern IOBluetoothSDPUUIDRef IOBluetoothSDPUUIDCreateUUID32(
    BluetoothSDPUUID32 uuid32);

Parameters

uuid32: A scalar representing a 32-bit UUID.

Return Value

Returns the new IOBluetoothSDPUUIDRef or NULL on failure. The caller MUST release the returned IOBluetoothSDPUUIDRef by calling IOBluetoothObjectRelease().

IOBluetoothSDPUUIDCreateWithBytes

Creates a new IOBluetoothSDPUUIDRef with the given bytes of the given length.

extern IOBluetoothSDPUUIDRef IOBluetoothSDPUUIDCreateWithBytes(
    const void *bytes,
    UInt8 length);

Parameters

bytes: An array of bytes representing the UUID.
length: The length of the array of bytes.

Return Value

Returns the new IOBluetoothSDPUUIDRef or NULL on failure. The caller MUST release the returned IOBluetoothSDPUUIDRef by calling IOBluetoothObjectRelease().

Discussion

If the length is invalid for a UUID, NULL is returned.

IOBluetoothSDPUUIDCreateWithData

Creates a new IOBluetoothSDPUUIDRef from the given CFDataRef.

extern IOBluetoothSDPUUIDRef IOBluetoothSDPUUIDCreateWithData(
    CFDataRef data);

Parameters

data: The CFDataRef containing the UUID bytes.

Return Value

Returns the new IOBluetoothSDPUUIDRef or NULL on failure. The caller MUST release the returned IOBluetoothSDPUUIDRef by calling IOBluetoothObjectRelease().

Discussion

If the length of the CFDataRef is invalid for a UUID, NULL is returned.

IOBluetoothSDPUUIDGetBytes

Returns a pointer to the array of UUID bytes.

extern const void *IOBluetoothSDPUUIDGetBytes(
    IOBluetoothSDPUUIDRef uuid);

Parameters

uuid: The target IOBluetoothSDPUUIDRef.

Return Value

Returns a pointer to the array of UUID bytes.

IOBluetoothSDPUUIDGetLength

Returns the length (in bytes) of the UUID.

extern UInt8 IOBluetoothSDPUUIDGetLength(
    IOBluetoothSDPUUIDRef uuid);

Parameters

uuid: The target IOBluetoothSDPUUIDRef.

Return Value

Returns the length (in bytes) of the UUID.

IOBluetoothSDPUUIDGetUUIDWithLength

Returns an IOBluetoothSDPUUIDRef matching the target UUID, but with the given number of bytes.

extern IOBluetoothSDPUUIDRef IOBluetoothSDPUUIDGetUUIDWithLength(
    IOBluetoothSDPUUIDRef uuid,
    UInt8 newLength);

Parameters

uuid: The target IOBluetoothSDPUUIDRef.
newLength: The desired length for the UUID.

Return Value

Returns an IOBluetoothSDPUUIDRef with the same data as the target but with the given length if it is possible to do so. Otherwise, NULL is returned.

Discussion

If the target IOBluetoothSDPUUIDRef is the same length as newLength, it returns the IOBluetoothSDPUUIDRef itself. If newLength is greater it creates a new IOBluetoothSDPUUIDRef with the correct value for the given length. If newLength is smaller, it will attempt to create a new IOBluetoothSDPUUIDRef that is smaller if the data matches the Bluetooth UUID base. This downconversion is currently unimplemented.

Because this function creates a new IOBluetoothSDPUUIDRef to be returned, the caller is responsible for calling IOBluetoothObjectRelease() on the returned IOBluetoothSDPUUIDRef.

IOBluetoothSDPUUIDIsEqualToUUID

Compares the two IOBluetoothSDPUUIDRefs.

extern Boolean IOBluetoothSDPUUIDIsEqualToUUID(
    IOBluetoothSDPUUIDRef uuid1,
    IOBluetoothSDPUUIDRef uuid2);

Parameters

uuid1: The first IOBluetoothSDPUUIDRef to be compared.
uuid2: The second IOBluetoothSDPUUIDRef to be compared.

Return Value

Returns TRUE if the UUID values of each IOBluetoothSDPUUIDRef are equal. This includes the case where the sizes are different but the data itself is the same when the Bluetooth UUID base is applied.

Discussion

This function will compare the two UUID values independent of their length.

IOBluetoothSetSupervisionTimeout

Sets the connection supervision timeout.

extern IOReturn IOBluetoothSetSupervisionTimeout(
    IOBluetoothDeviceRef device,
    UInt16 timeout) AVAILABLE_BLUETOOTH_VERSION_2_0_AND_LATER;

Parameters

device: The target IOBluetoothDeviceRef
timeout: A client-supplied link supervision timeout value to use to monitor the connection.

Return Value

Returns kIOReturnSuccess if it was possible to set the connection supervision timeout.

Discussion

NOTE: This method is only available in Mac OS X 10.5 (Bluetooth v2.0) or later.

IOBluetoothUserNotificationUnregister

Unregisters the target notification.

void IOBluetoothUserNotificationUnregister(
    IOBluetoothUserNotificationRef notificationRef );

Parameters

notificationRef: The target IOBluetoothUserNotificationRef to be unregistered.

Return Value

None.

Discussion

This function will unregister the notification. Once the notification has been unregistered, it will no longer call the callback. Additionally, once this function has been called the target IOBluetoothUserNotificationRef is no longer valid.

Typedefs

IOBluetoothCreateConnectionCallback

Callback function definition for a create connection call.

typedef void ( *IOBluetoothCreateConnectionCallback) (
    void *userRefCon,
    IOBluetoothDeviceRef deviceRef,
    IOReturn status );

Parameters

userRefCon: (void *) This user defined parameter was provided during the original call to IOBluetoothCreateConnection.
deviceRef: (IOBluetoothDeviceRef) The IOBluetoothDevice which the CreateConnection call is completing for.
status: (OSStatus) The status of the call. Could be success, page timeout, host timeout, already exists, etc.

Return Value

None.

Discussion

This callback will be invoked when a create connection command completes.

IOBluetoothDeviceInquiryCompleteCallback

Callback function definition for inquiry messages.

typedef void ( *IOBluetoothDeviceInquiryCompleteCallback)(
    void *userRefCon, 
    IOBluetoothDeviceInquiryRef inquiryRef, 
    IOReturn error, 
    Boolean aborted );

Parameters

inquiryRef: The inquiry object ref responsible for sending the callback.
userRefCon: This user-defined parameter was provided during the original call to register the callback.
error: kIOReturnSuccess if inquiry completed without event. Otherwise, an error code.
aborted: 1 if user called -stop on the inquiry.

Return Value

None.

Discussion

This callback will be invoked when the message for which it was registered is sent.

IOBluetoothDeviceInquiryDeviceFoundCallback

Callback function definition for inquiry messages.

typedef void ( *IOBluetoothDeviceInquiryDeviceFoundCallback)(
    void *userRefCon, 
    IOBluetoothDeviceInquiryRef inquiryRef, 
    IOBluetoothDeviceRef deviceRef );

Parameters

inquiryRef: The inquiry object ref responsible for sending the callback.
userRefCon: This user-defined parameter was provided during the original call to register the callback.

Return Value

None.

Discussion

This callback will be invoked when the message for which it was registered is sent.

IOBluetoothDeviceInquiryDeviceNameUpdatedCallback

Callback function definition for inquiry messages.

typedef void ( *IOBluetoothDeviceInquiryDeviceNameUpdatedCallback)(
    void *userRefCon, 
    IOBluetoothDeviceInquiryRef inquiryRef, 
    IOBluetoothDeviceRef deviceRef, 
    uint32_t devicesRemaining );

Parameters

inquiryRef: The inquiry object ref responsible for sending the callback.
userRefCon: This user-defined parameter was provided during the original call to register the callback.
deviceRemaining: Number of devices remaining to be updated.

Return Value

None.

Discussion

This callback will be invoked when the message for which it was registered is sent.

IOBluetoothDeviceInquiryRef

An opaque object, representing an Inquiry that can be used to get all devices in range of this computer.

typedef struct OpaqueIOBluetoothDeviceInquiryRef * IOBluetoothDeviceInquiryRef;

Discussion

See individual functions for information on usage. Of note: this API is non-functional in OS versions prior to 10.4.3, even though (most) of the API was introduced in 10.4. We strongly recommend using the Objective C API if possible.

IOBluetoothDeviceInquiryStartedCallback

Callback function definition for inquiry messages.

typedef void ( *IOBluetoothDeviceInquiryStartedCallback)(
    void *userRefCon, 
    IOBluetoothDeviceInquiryRef inquiryRef );

Parameters

inquiryRef: The inquiry object ref responsible for sending the callback.
userRefCon: This user-defined parameter was provided during the original call to register the callback.

Return Value

None.

Discussion

This callback will be invoked when the message for which it was registered is sent.

IOBluetoothDeviceInquiryUpdatingNamesStartedCallback

Callback function definition for inquiry messages.

typedef void ( *IOBluetoothDeviceInquiryUpdatingNamesStartedCallback)(
    void *userRefCon, 
    IOBluetoothDeviceInquiryRef inquiryRef, 
    uint32_t devicesRemaining );

Parameters

inquiryRef: The inquiry object ref responsible for sending the callback.
userRefCon: This user-defined parameter was provided during the original call to register the callback.
devicesRemaining: Number of devices remaining to be updated.

Return Value

None.

Discussion

This callback will be invoked when the message for which it was registered is sent.

IOBluetoothDeviceSearchAttributes

See Also:

IOBluetoothDeviceSearchAttributes

typedef struct IOBluetoothDeviceSearchAttributes IOBluetoothDeviceSearchAttributes;

Discussion

You can search for general device classes and service classes, or you can search for a specific device address or name. If you pass NULL as the attribute structure, you will get ALL devices in the vicinity found during a search. Note that passing a zeroed-out block of attributes is NOT equivalent to passing in NULL!

IOBluetoothDeviceSearchDeviceAttributes

Structure used to search for particular devices.

See Also:

IOBluetoothDeviceSearchDeviceAttributes

typedef struct IOBluetoothDeviceSearchDeviceAttributes IOBluetoothDeviceSearchDeviceAttributes;

Discussion

Make sure you specify all fields! If you do not set deviceClassMajor for example, and the value is 0, that is mapped to kBluetoothDeviceClassMajorMiscellaneous, which is probably not what you want. To search for all device types, you must pass kBluetoothDeviceClassMajorAny and its relatives.

IOBluetoothDeviceSearchOptions

typedef UInt32 IOBluetoothDeviceSearchOptions;

IOBluetoothL2CAPChannelDataBlock

typedef struct IOBluetoothL2CAPChannelDataBlock { 
    void *dataPtr; 
    size_t dataSize; 
} IOBluetoothL2CAPChannelDataBlock;

Discussion

Associated to the kIOBluetoothL2CAPChannelEventTypeData, it carries a pointer and a size of the new incoming data.

IOBluetoothL2CAPChannelEvent

typedef struct IOBluetoothL2CAPChannelEvent { 
    IOBluetoothL2CAPChannelEventType eventType; 
    // Caution:  You cannot add any more values here for binary compatibility reasons 
    union { 
        // Caution:  An element of this union cannot grow beyond 32 bytes in size for binary compatibility reasons. 
        IOBluetoothL2CAPChannelDataBlock data; 
        void* writeRefCon; 
        UInt8 padding[32]; 
        } u; 
    IOReturn status; 
    // Add new items above this comment. 
} IOBluetoothL2CAPChannelEvent;

Discussion

Structure that holds an L2CAP event. Developers that wish to pass events along are to copy the event (or its fields) one by one and not with memory copy methods (as bcopy or memcopy). We do not ensure the size of an event to be constant between releases (it is actually likely that it will change).

IOBluetoothL2CAPChannelEventType

See Also:

IOBluetoothL2CAPEvent

typedef enum IOBluetoothL2CAPChannelEventType { 
    kIOBluetoothL2CAPChannelEventTypeData = 0x0001, 
    kIOBluetoothL2CAPChannelEventTypeOpenComplete = 0x0002, 
    kIOBluetoothL2CAPChannelEventTypeClosed = 0x0003, 
    kIOBluetoothL2CAPChannelEventTypeReconfigured = 0x0004, 
    kIOBluetoothL2CAPChannelEventTypeWriteComplete = 0x0005, 
    kIOBluetoothL2CAPChannelEventTypeQueueSpaceAvailable = 0x0006 
} IOBluetoothL2CAPChannelEventType;

Discussion

The events generated by an L2CAP channel:
kIOBluetoothL2CAPChannelEventTypeData: new data.
kIOBluetoothL2CAPChannelEventTypeClosed: channel closed.
kIOBluetoothL2CAPChannelEventTypeReconfigured: channel was reconfigured (check if the MTU changed)
kIOBluetoothL2CAPChannelEventTypeOpenCompete: channel is open.
kIOBluetoothL2CAPChannelEventTypeWriteComplete: write opetation is completed
kIOBluetoothL2CAPChannelEventTypeQueueSpaceAvailable: the internal l2cap queue has some room

See the description of IOBluetoothL2CAPDataBlock this event.

IOBluetoothL2CAPChannelIncomingDataListener

Callback for listening to L2CAP data.

typedef void ( *IOBluetoothL2CAPChannelIncomingDataListener)(
    IOBluetoothL2CAPChannelRef l2capChannel,
    void *data,
    UInt16 length,
    void *refCon);

Fields

l2capChannel: (IOBluetoothL2CAPChannelRef) The L2CAP channel which received the data.
data: (void *) A pointer to the data received.
length: (UInt16) The length of the data received.
refCon: (void *) The refCon provided to the framework when you registered for data on this channel.

Discussion

This callback will be called when data comes in on an L2CAP channel.

IOBluetoothL2CAPChannelIncomingEventListener

Typedef for the L2CAP channel event listener.

typedef void ( *IOBluetoothL2CAPChannelIncomingEventListener)(
    IOBluetoothL2CAPChannelRef l2capChannel,
    void *refCon,
    IOBluetoothL2CAPChannelEvent *event);

Fields

l2capChannel: The L2CAP channel which received the events.
refCon: User-defined refCon provided upon registration.
event: The type of event for this notification.

Discussion

This is the definition for the callback which will be invoked upon receiving data on a L2CAP channel.

For example an event listener function:


    void l2capEventListener (IOBluetoothL2CAPChannelRef l2capChannel, void *refCon, IOBluetoothL2CAPChannelEvent *event)
    {
        switch (event->eventType)
        {
                case kIOBluetoothL2CAPNewDataEvent:
                    // In thise case:
                    // event->u.newData.dataPtr  is a pointer to the block of data received.
                    // event->u.newData.dataSize is the size of the block of data.
                break;
                
					......
					
                case kIOBluetoothL2CAPChannelTerminatedEvent:
                    // In this case:
                    // event->u.terminatedChannel is the channel that was terminated. It can be converted in an IOBluetoothL2CAPChannel
                    // object with [IOBluetoothL2CAPChannel withL2CAPChannelRef:]. (see below).
                break;
        }
    }



IOBluetoothL2CAPEvent
See Also:
IOBluetoothL2CAPChannelEventType

typedef enum IOBluetoothL2CAPChannelEventType { 
    kIOBluetoothL2CAPChannelEventTypeData = 0x0001, 
    kIOBluetoothL2CAPChannelEventTypeOpenComplete = 0x0002, 
    kIOBluetoothL2CAPChannelEventTypeClosed = 0x0003, 
    kIOBluetoothL2CAPChannelEventTypeReconfigured = 0x0004, 
    kIOBluetoothL2CAPChannelEventTypeWriteComplete = 0x0005, 
    kIOBluetoothL2CAPChannelEventTypeQueueSpaceAvailable = 0x0006 
} IOBluetoothL2CAPChannelEventType;  
Discussion
The events generated by an L2CAP channel:


kIOBluetoothL2CAPChannelEventTypeData:	new data.


kIOBluetoothL2CAPChannelEventTypeClosed: channel closed.


kIOBluetoothL2CAPChannelEventTypeReconfigured: channel was reconfigured (check if the MTU changed)


kIOBluetoothL2CAPChannelEventTypeOpenCompete: channel is open.


kIOBluetoothL2CAPChannelEventTypeWriteComplete: write opetation is completed


kIOBluetoothL2CAPChannelEventTypeQueueSpaceAvailable: the internal l2cap queue has some room

See the description of IOBluetoothL2CAPDataBlock this event.



IOBluetoothRemoteNameRequestCallback
Callback function definition for a remote name request.

typedef void ( *IOBluetoothRemoteNameRequestCallback) (
    void *userRefCon,
    IOBluetoothDeviceRef deviceRef,
    IOReturn status );  
Parameters

userRefCon
(void *) This user defined parameter was provided during the original call to initiate
the remote name request.
deviceRef
(IOBluetoothDeviceRef) The IOBluetoothDevice which the ReadRemoteName call is completing for.
status
(BluetoothHCIStatus) The status of the call.  Could be success, page timeout, host timeout.

Return Value
None.

Discussion
This callback will be invoked when a remote name request command completes.



IOBluetoothRFCOMMChannelEvent
typedef struct IOBluetoothRFCOMMChannelEvent { 
    // Caution:  You cannot add any more values here for binary compatibility reasons 
    IOBluetoothRFCOMMChannelEventType eventType; 
    union { 
        // Caution:  An element of this union cannot grow beyond 32 bytes in size for binary compatibility reasons. 
        IOBluetoothRFCOMMDataBlock data; 
        IOBluetoothRFCOMMFlowControlStatus flowStatus; 
        IOBluetoothRFCOMMChannelRef terminatedChannel; 
        void* writeRefCon;  
        UInt8 padding[32];  
        // Old name, is going to be deprecated, use data instead 
        IOBluetoothRFCOMMDataBlock newData; 
        } u; 
    IOReturn status; 
    // Add new items above this comment. 
} IOBluetoothRFCOMMChannelEvent;  
Discussion
Structure that holds an RFCOMM event.



IOBluetoothRFCOMMChannelEventType
See Also:
IOBluetoothRFCOMMEvent

typedef enum IOBluetoothRFCOMMChannelEventType { 
    // New event types added in 1.2 (Mac OS X 10.2.5) 
    kIOBluetoothRFCOMMChannelEventTypeData = 0x0000, 
    kIOBluetoothRFCOMMChannelEventTypeFlowControlChanged = 0x0001, 
    kIOBluetoothRFCOMMChannelEventTypeClosed = 0x0002, 
    kIOBluetoothRFCOMMChannelEventTypeOpenComplete = 0x0003, 
    kIOBluetoothRFCOMMChannelEventTypeControlSignalsChanged = 0x0004, 
    kIOBluetoothRFCOMMChannelEventTypeWriteComplete = 0x0005, 
    kIOBluetoothRFCOMMChannelEventTypeQueueSpaceAvailable = 0x0006,  
    // Obsolete Event names: 
    kIOBluetoothRFCOMMNewDataEvent = 0x0000, 
    kIOBluetoothRFCOMMFlowControlChangedEvent = 0x0001, 
    kIOBluetoothRFCOMMChannelTerminatedEvent = 0x0002 
} IOBluetoothRFCOMMChannelEventType;  
Discussion
The events generated by an RFCOMM channel:



kIOBluetoothRFCOMMChannelEventTypeData:	new data.


kIOBluetoothRFCOMMChannelEventTypeFlowControlChanged: flow control changed.


kIOBluetoothRFCOMMChannelEventTypeClosed: channel terminated.


kIOBluetoothRFCOMMChannelEventTypeControlSignalsChanged: signals (like DTR, CTR) changed. (not yet supported)


kIOBluetoothRFCOMMChannelEventTypeWriteComplete:	write operation completed


kIOBluetoothRFCOMMChannelEventTypeQueueSpaceAvailable: more room in the RFCOMM channel output queue

Obsolete Event types:



kIOBluetoothRFCOMMNewDataEvent:	new data.


kIOBluetoothRFCOMMFlowControlChangedEvent: flow control changed.


kIOBluetoothRFCOMMChannelTerminatedEvent: channel terminated.


kIOBluetoothRFCOMMControlSignalsChangedEvent: signals (like DTR, CTR) changed. (not yet supported)



See the description of kIOBluetoothRFCOMMChannelEventTypeDataType and  kIOBluetoothRFCOMMChannelEventTypeFlowControlChangedType for more
information on these events.



IOBluetoothRFCOMMChannelIncomingDataListener
Typedef for the RFCOMM channel data listener.

typedef void ( *IOBluetoothRFCOMMChannelIncomingDataListener)(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    void *data,
    UInt16 length,
    void *refCon);  
Fields

rfcommChannel
RFCOMM channel which received the data.
data
Pointer to the data received.
length
Length of the data received.
refCon
User-defined refCon provided upon registration.

Discussion
This is the definition for the callback which will be invoked upon receiving data on a RFCOMM channel. This is a
simplified version of IOBluetoothRFCOMMChannelIncomingEventListener. See IOBluetoothRFCOMMChannelIncomingEventListener for more
information on the rfcommChannel parameter.



IOBluetoothRFCOMMChannelIncomingEventListener
Typedef for the RFCOMM channel event listener.

typedef void ( *IOBluetoothRFCOMMChannelIncomingEventListener)(
    IOBluetoothRFCOMMChannelRef rfcommChannel,
    void *refCon,
    IOBluetoothRFCOMMChannelEvent *event);  
Fields

rfcommChannel
RFCOMM channel which received the events.
refCon
User-defined refCon provided upon registration.
event
The type of event for this notification.

Discussion
This is the definition for the callback which will be invoked upon receiving data on a RFCOMM channel.

For example an event listener function:

        
    void rfcommEventListener (IOBluetoothRFCOMMChannelRef rfcommChannel, void *refCon, IOBluetoothRFCOMMChannelEvent *event)
    {
        switch (event->eventType)
        {
                case kIOBluetoothRFCOMMNewDataEvent:
                    // In thise case:
                    // event->u.newData.dataPtr  is a pointer to the block of data received.
                    // event->u.newData.dataSize is the size of the block of data.
                break;
                
                case kIOBluetoothRFCOMMFlowControlChangedEvent:
                    // In thise case:
                    // event->u.flowStatus       is the status of flow control (see IOBluetoothRFCOMMFlowControlStatus for current restrictions)
                break;
                
                case kIOBluetoothRFCOMMChannelTerminatedEvent:
                    // In this case:
                    // event->u.terminatedChannel is the channel that was terminated. It can be converted in an IOBluetoothRFCOMMChannel
                    // object with [IOBluetoothRFCOMMChannel withRFCOMMChannelRef:]. (see below).
                break;
        }
    }

        

rfcommChannel is the channel that generated the event and it is the channel where the callback was generated. 
rfcommChannel is a  IOBluetoothRFCOMMChannelRef reference, it can be converted in an Objective C IOBluetoothRFCOMMChannel
object with:

                
    IOBluetoothRFCOMMChannel *myOBJCChannel = [IOBluetoothRFCOMMChannel withRFCOMMChannelRef:rfcommChannel];
        
        



IOBluetoothRFCOMMDataBlock
typedef struct IOBluetoothRFCOMMDataBlock { 
    void *dataPtr; 
    size_t dataSize; 
} IOBluetoothRFCOMMDataBlock;  
Discussion
Associated to the kIOBluetoothRFCOMMNewDataEvent, it carries a pointer and a size of the new incoming data.




IOBluetoothRFCOMMEvent
See Also:
IOBluetoothRFCOMMChannelEventType

typedef enum IOBluetoothRFCOMMChannelEventType { 
    // New event types added in 1.2 (Mac OS X 10.2.5) 
    kIOBluetoothRFCOMMChannelEventTypeData = 0x0000, 
    kIOBluetoothRFCOMMChannelEventTypeFlowControlChanged = 0x0001, 
    kIOBluetoothRFCOMMChannelEventTypeClosed = 0x0002, 
    kIOBluetoothRFCOMMChannelEventTypeOpenComplete = 0x0003, 
    kIOBluetoothRFCOMMChannelEventTypeControlSignalsChanged = 0x0004, 
    kIOBluetoothRFCOMMChannelEventTypeWriteComplete = 0x0005, 
    kIOBluetoothRFCOMMChannelEventTypeQueueSpaceAvailable = 0x0006,  
    // Obsolete Event names: 
    kIOBluetoothRFCOMMNewDataEvent = 0x0000, 
    kIOBluetoothRFCOMMFlowControlChangedEvent = 0x0001, 
    kIOBluetoothRFCOMMChannelTerminatedEvent = 0x0002 
} IOBluetoothRFCOMMChannelEventType;  
Discussion
The events generated by an RFCOMM channel:



kIOBluetoothRFCOMMChannelEventTypeData:	new data.


kIOBluetoothRFCOMMChannelEventTypeFlowControlChanged: flow control changed.


kIOBluetoothRFCOMMChannelEventTypeClosed: channel terminated.


kIOBluetoothRFCOMMChannelEventTypeControlSignalsChanged: signals (like DTR, CTR) changed. (not yet supported)


kIOBluetoothRFCOMMChannelEventTypeWriteComplete:	write operation completed


kIOBluetoothRFCOMMChannelEventTypeQueueSpaceAvailable: more room in the RFCOMM channel output queue

Obsolete Event types:



kIOBluetoothRFCOMMNewDataEvent:	new data.


kIOBluetoothRFCOMMFlowControlChangedEvent: flow control changed.


kIOBluetoothRFCOMMChannelTerminatedEvent: channel terminated.


kIOBluetoothRFCOMMControlSignalsChangedEvent: signals (like DTR, CTR) changed. (not yet supported)



See the description of kIOBluetoothRFCOMMChannelEventTypeDataType and  kIOBluetoothRFCOMMChannelEventTypeFlowControlChangedType for more
information on these events.



IOBluetoothRFCOMMFlowControlStatus
typedef enum IOBluetoothRFCOMMFlowControlStatus { 
    kIOBluetoothRFCOMMChannelFlowControlStatusIsOff = 0x0000, 
    kIOBluetoothRFCOMMChannelFlowControlStatusIsOn = 0x0001 
} IOBluetoothRFCOMMFlowControlStatus;  
Discussion
Related to the kIOBluetoothRFCOMMFlowControlChangedEvent it carries the status of the flow control.
For the first release of the APIs this event is generated only when flow control switches from OFF
to ON. Future releases will support the switch from ON to OFF as well.



IOBluetoothSDPQueryCallback
Callback function definition for a perform SDP query call.

typedef void ( *IOBluetoothSDPQueryCallback) (
    void *userRefCon,
    IOBluetoothDeviceRef deviceRef,
    IOReturn status );  
Parameters

userRefCon
(void *) This user defined parameter was provided during the original call to perform the query.
deviceRef
(IOBluetoothDeviceRef) The IOBluetoothDevice on which the SDP query will be performed.
status
(OSStatus) The status of the call.  Could be success, page timeout, host timeout, etc.

Return Value
None.

Discussion
This callback will be invoked when an SDP query completes (or an error is encountered performing the query).



IOBluetoothUserNotificationCallback
Callback function definition for user notifications.

typedef void ( *IOBluetoothUserNotificationCallback)(
    void *userRefCon, 
    IOBluetoothUserNotificationRef inRef, 
    IOBluetoothObjectRef objectRef );  
Parameters

userRefCon
This user-defined parameter was provided during the original call to register
the notification.
inRef
The notification responsible for sending the notification.
status
The object that originated the notification.

Return Value
None.

Discussion
This callback will be invoked when the notification for which it was registered is sent.

Structs and Unions


IOBluetoothDeviceSearchAttributes
See Also:
IOBluetoothDeviceSearchAttributes

struct IOBluetoothDeviceSearchAttributes { 
    IOBluetoothDeviceSearchOptions options; // Options. 
    IOItemCount maxResults; // Maximum number of results you desire. 0 means infinite. 
    IOItemCount deviceAttributeCount;  
    IOBluetoothDeviceSearchDeviceAttributes *attributeList; 
};  
Discussion
You can search for general device classes and service classes, or you can search for a 
specific device address or name. If you pass NULL as the attribute structure,
you will get ALL devices in the vicinity found during a search. Note that passing a zeroed-out block of 
attributes is NOT equivalent to passing in NULL!	



IOBluetoothDeviceSearchDeviceAttributes
Structure used to search for particular devices.

See Also:
IOBluetoothDeviceSearchDeviceAttributes

struct IOBluetoothDeviceSearchDeviceAttributes { 
    BluetoothDeviceAddress address; // 00 08 22 44 AB 56, etc. 
    BluetoothDeviceName name; // "Al Yankovic's Phone", etc. 
    BluetoothServiceClassMajor serviceClassMajor; // Networking, Rendering, etc. 
    BluetoothDeviceClassMajor deviceClassMajor; // Computer, Phone, Audio, etc. 
    BluetoothDeviceClassMinor deviceClassMinor; // Desktop, cordless, headset, etc. 
};  
Discussion
Make sure you specify all fields! If you do not set deviceClassMajor for example, and the value is
0, that is mapped to kBluetoothDeviceClassMajorMiscellaneous, which is probably not what you want. To
search for all device types, you must pass kBluetoothDeviceClassMajorAny and its relatives. 

Enumerations


IOBluetoothDeviceSearchOptionsBits
enum IOBluetoothDeviceSearchOptionsBits { 
    kSearchOptionsNone = 0L, 
    kSearchOptionsAlwaysStartInquiry = (
        1L << 0), 
    kSearchOptionsDiscardCachedResults = (
        1L << 1), 
};  


 
	
		
			
		
		
			

				
					
						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.
						
					
				
			
		
	

 





Last Updated: 2008-08-07