Advanced Search

Log In | Not a Member?

Contact ADC

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.

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.

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.

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.

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.

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()).

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.

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.

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.

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

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.

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).

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

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.

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

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.

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).

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.

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.

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.

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).

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.

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()).

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

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.

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

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.

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

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.

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.

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

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.

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.

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.

Removes all found devices from the inquiry object.

extern IOReturn IOBluetoothDeviceInquiryClearFoundDevices(
    IOBluetoothDeviceInquiryRef inInquiryRef ) AVAILABLE_BLUETOOTH_VERSION_1_6_3_AND_LATER;  

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Creates a baseband connection to the device.

extern IOReturn IOBluetoothDeviceOpenConnection(
    IOBluetoothDeviceRef btDevice,
    IOBluetoothCreateConnectionCallback callback,