IOBluetoothDevice

Overview

An instance of IOBluetoothDevice represents a single remote Bluetooth device.

Discussion

An IOBluetoothDevice object may exist independent of the existence of a baseband connection with the target device. Using this object, a client can request creation and destruction of baseband connections, and request the opening of L2CAP and RFCOMM channels on the remote device. Many of the other APIs in the IOBluetooth framework will return this object, or its C counterpart (IOBluetoothDeviceRef).

Methods

-addToFavorites

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

-closeConnection

Close down the baseband connection to the device.

+favoriteDevices

Gets an array of the user's favorite devices.

-getAddress

Get the Bluetooth device address for the target device.

-getAddressString

Get a string representation of the Bluetooth device address for the target device. The format of the string is the same as returned by IOBluetoothNSStringFromDeviceAddress().

-getClassOfDevice

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

-getClockOffset

Get the clock offset value of the device.

-getConnectionHandle

Get the connection handle for the baseband connection.

-getDeviceClassMajor

Get the major device class of the device.

-getDeviceClassMinor

Get the minor service class of the device.

-getDeviceRef

Returns an IOBluetoothDeviceRef representation of the target IOBluetoothDevice object.

-getEncryptionMode

Get the encryption mode for the baseband connection.

-getLastInquiryUpdate

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

-getLastNameUpdate

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

-getLastServicesUpdate

Get the date/time of the last SDP query.

-getLinkType

Get the link type for the baseband connection.

-getName

Get the human readable name of the remote device.

-getNameOrAddress

Get the human readable name of the remote device. If the name is not present, it will return a string containing the device's address.

-getPageScanMode

Get the page scan mode for the device.

-getPageScanPeriodMode

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

-getPageScanRepetitionMode

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

-getServiceClassMajor

Get the major service class of the device.

-getServiceRecordForUUID:

Search for a service record containing the given UUID.

-getServices

Gets an array of service records for the device.

-isConnected

Indicates whether a baseband connection to the device exists.

-isEqual:

Compares two IOBluetoothDevice objects.

-isFavorite

Reports whether the target device is a favorite for the user.

-isIncoming

Returns TRUE if the device connection was generated by the remote host.

-isPaired

Returns whether the target device is paired.

-openConnection

Create a baseband connection to the device.

-openConnection:

Create a baseband connection to the device.

-openConnection:withPageTimeout:authenticationRequired:

Create a baseband connection to the device.

-openL2CAPChannel:findExisting:newChannel:

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

-openL2CAPChannelAsync:withPSM:delegate:

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

-openL2CAPChannelAsync:withPSM:withConfiguration:delegate:

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

-openL2CAPChannelSync:withPSM:delegate:

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

-openL2CAPChannelSync:withPSM:withConfiguration:delegate:

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

-openRFCOMMChannel:channel:

Opens a new RFCOMM channel to the target device. Returns only once the channel is open or failed to open.

-openRFCOMMChannelAsync:withChannelID:delegate:

Opens a new RFCOMM channel to the target device. Returns immediately.

-openRFCOMMChannelSync:withChannelID:delegate:

Opens a new RFCOMM channel to the target device. Returns only once the channel is open or failed to open.

+pairedDevices

Gets an array of all of the paired devices on the system.

-performSDPQuery:

Performs an SDP query on the target device.

-recentAccessDate

Returns the date/time of the most recent access of the target device.

+recentDevices:

Gets an array of recently used Bluetooth devices.

+registerForConnectNotifications:selector:

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

-registerForDisconnectNotification:selector:

Allows a client to register for device disconnect notification.

-remoteNameRequest:

Issues a remote name request to the target device.

-remoteNameRequest:withPageTimeout:

Issues a remote name request to the target device.

-removeFromFavorites

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

-requestAuthentication

Requests that the existing baseband connection be authenticated.

-sendL2CAPEchoRequest:length:

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

-setSupervisionTimeout:

Sets the connection supervision timeout.

+withAddress:

Returns the IOBluetoothDevice object for the given BluetoothDeviceAddress

+withDeviceRef:

Method call to convert an IOBluetoothDeviceRef into an IOBluetoothDevice *.

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

- (IOReturn)addToFavorites; 

Return Value

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

Discussion

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

Close down the baseband connection to the device.

- (IOReturn)closeConnection; 

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.

Gets an array of the user's favorite devices.

+ (NSArray *)favoriteDevices; 

Return Value

Returns an array of device objects representing the user's favorite devices. If the user has no favorites, nil is returned.

Discussion

The resulting array contains IOBluetoothDevice objects.

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

Get the Bluetooth device address for the target device.

- (const BluetoothDeviceAddress *)getAddress; 

Return Value

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

Get a string representation of the Bluetooth device address for the target device. The format of the string is the same as returned by IOBluetoothNSStringFromDeviceAddress().

- (NSString *)getAddressString; 

Return Value

Returns an NSString containing the Bluetooth device address of the target device.

Discussion

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

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

- (BluetoothClassOfDevice)getClassOfDevice; 

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 -getLastInquiryUpdate. If nil is returned, then the device hasn't been seen.

Get the clock offset value of the device.

- (BluetoothClockOffset)getClockOffset; 

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 -getLastInquiryUpdate. If nil is returned, then the device hasn't been seen.

Get the connection handle for the baseband connection.

- (BluetoothConnectionHandle)getConnectionHandle; 

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 (-isConnected returns TRUE).

Get the major device class of the device.

- (BluetoothDeviceClassMajor)getDeviceClassMajor; 

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 -getLastInquiryUpdate. If nil is returned, then the device hasn't been seen.

Get the minor service class of the device.

- (BluetoothDeviceClassMinor)getDeviceClassMinor; 

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 -getLastInquiryUpdate. If nil is returned, then the device hasn't been seen.

Returns an IOBluetoothDeviceRef representation of the target IOBluetoothDevice object.

- (IOBluetoothDeviceRef)getDeviceRef; 

Return Value

Returns an IOBluetoothDeviceRef representation of the target IOBluetoothDevice object.

Get the encryption mode for the baseband connection.

- (BluetoothHCIEncryptionMode)getEncryptionMode; 

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 (-isConnected returns TRUE).

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

- (NSDate *)getLastInquiryUpdate; 

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, nil is returned.

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

- (NSDate *)getLastNameUpdate; 

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, nil is returned.

Get the date/time of the last SDP query.

- (NSDate *)getLastServicesUpdate; 

Return Value

Returns the date/time of the last SDP query. If an SDP query has never been performed on the device, nil is returned.

Get the link type for the baseband connection.

- (BluetoothLinkType)getLinkType; 

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 (-isConnected returns TRUE).

Get the human readable name of the remote device.

- (NSString *)getName; 

Return Value

Returns the name of the remote device name. This value is an NSString generated from the UTF-8 format of the most recent remote name request.

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, nil is returned. To perform a remote name request, call -remoteNameRequest. If a remote name request has been successfully completed, the method -getLastNameUpdate will return the date/time of the last successful request.

Get the human readable name of the remote device. If the name is not present, it will return a string containing the device's address.

- (NSString *)getNameOrAddress; 

Return Value

Returns the device's name or a string containing the device's address.

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.

Get the page scan mode for the device.

- (BluetoothPageScanMode)getPageScanMode; 

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 -getLastInquiryUpdate. If nil is returned, then the device hasn't been seen.

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

- (BluetoothPageScanPeriodMode)getPageScanPeriodMode; 

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 -getLastInquiryUpdate. If nil is returned, then the device hasn't been seen.

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

- (BluetoothPageScanRepetitionMode)getPageScanRepetitionMode; 

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 -getLastInquiryUpdate. If nil is returned, then the device hasn't been seen.

Get the major service class of the device.

- (BluetoothServiceClassMajor)getServiceClassMajor; 

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 -getLastInquiryUpdate. If nil is returned, then the device hasn't been seen.

Search for a service record containing the given UUID.

- (IOBluetoothSDPServiceRecord *)getServiceRecordForUUID:(IOBluetoothSDPUUID *)sdpUUID; 

Parameters

sdpUUID

UUID value to search for.

Return Value

Returns the first service record that contains the given uuid. If no service record is found, nil is returned.

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.

- (NSArray *)getServices; 

Return Value

Returns an array of service records for the device if an SDP query has been performed. If no SDP query has been performed, nil is returned.

Discussion

The resulting array contains IOBluetoothSDPServiceRecord objects. The service records are only present if an SDP query has been done on the target object. This can be determined by calling -getLastServicesUpdate. It will return the last date/time of the SDP query. To initiate an SDP query on a device, use -performSDPQuery: as defined above.

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.

Indicates whether a baseband connection to the device exists.

- (BOOL)isConnected; 

Return Value

Returns YES if a baseband connection to the device exists.

Compares two IOBluetoothDevice objects.

- (BOOL)isEqual:(id)cmpObject; 

Parameters

cmpObject

The object to compare to the target IOBluetoothDevice object

Return Value

Returns TRUE if the cmpObject represents the same remote device as the target.

Reports whether the target device is a favorite for the user.

- (BOOL)isFavorite; 

Return Value

Returns TRUE if the target device is a favorite for the user, FALSE if not.

Discussion

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

Returns TRUE if the device connection was generated by the remote host.

- (BOOL)isIncoming; 

Return Value

Returns TRUE if the device connection was generated by the remote host.

Discussion

Returns TRUE if the device connection was generated by the remote host. False if the connection was generated by some other device that connected to the local host.

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

Returns whether the target device is paired.

- (BOOL)isPaired; 

Return Value

Returns TRUE if the target device is paired, FALSE if not.

Discussion

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

Create a baseband connection to the device.

- (IOReturn)openConnection; 

Return Value

Returns kIOReturnSuccess if the connection was successfully created.

Discussion

This method is synchronous and will not return until either a connection has been established or the create connection has failed (perhaps timed out). This method does the same thing as calling -openConnection: with a nil target. This call with proceed without authentication required, and using the default page timeout value. If authentication or a non-default page timeout is required the method -openConnection:withPageTimeout:authenticationRequired: should be used instead.

Create a baseband connection to the device.

- (IOReturn)openConnection:(id)target; 

Return Value

Returns kIOReturnSuccess if the connection was successfully created (or if asynchronous, if the CREATE_CONNECTION command was successfully issued).

Discussion

If a target is specified, the open connection call is asynchronous and on completion of the CREATE_CONNECTION command, the method -connectionComplete:status: will be called on the specified target. If no target is specified, the call is synchronous and will not return until the connection is open or the CREATE_CONNECTION call has failed. This call with proceed without authentication required, and using the default page timeout value. If authentication or a non-default page timeout is required the method -openConnection:withPageTimeout:authenticationRequired: should be used instead.

Create a baseband connection to the device.

- (IOReturn)openConnection:(id)target withPageTimeout:(BluetoothHCIPageTimeout)pageTimeoutValue 
        authenticationRequired:(BOOL)authenticationRequired; 

Parameters

target

The target to message when the create connection call is complete

pageTimeoutValue

The page timeout value to use for this call

authenticationRequired

BOOL value to indicate whether authentication should be required for the connection

Return Value

Returns kIOReturnSuccess if the connection was successfully created (or if asynchronous, if the CREATE_CONNECTION command was successfully issued).

Discussion

If a target is specified, the open connection call is asynchronous and on completion of the CREATE_CONNECTION command, the method -connectionComplete:status: will be called on the specified target. If no target is specified, the call is synchronous and will not return until the connection is open or the CREATE_CONNECTION call has failed.

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

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

- (IOReturn)openL2CAPChannel:(BluetoothL2CAPPSM)psm 
        findExisting:(BOOL)findExisting newChannel:(IOBluetoothL2CAPChannel **)newChannel DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER; 

Parameters

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 IOBluetoothL2CAPChannel object 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 method 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.

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

- (IOReturn)openL2CAPChannelAsync:(IOBluetoothL2CAPChannel **)newChannel 
        withPSM:(BluetoothL2CAPPSM)psm delegate:(id)channelDelegate; 

Parameters

newChannel

A pointer to an IOBluetoothL2CAPChannel object 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.

channelDelegate

The object that will play the role of delegate for the channel. A channel delegate is the object the L2CAP uses as target for data and events. The developer will implement only the the methods he/she is interested in. A list of the possible methods is at the end of the file "IOBluetoothL2CAPChannel.h" in the definition of the protocol IOBluetoothL2CAPChannelDelegate.

Return Value

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

Discussion

This method 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.

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

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

- (IOReturn)openL2CAPChannelAsync:(IOBluetoothL2CAPChannel **)newChannel 
        withPSM:(BluetoothL2CAPPSM)psm withConfiguration:(NSDictionary*)channelConfiguration 
        delegate:(id)channelDelegate; 

Parameters

newChannel

A pointer to an IOBluetoothL2CAPChannel object 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.

channelConfiguration

the dictionary that describes the initial configuration for the channel.

delegate

the object that will play the role of delegate for the channel. A channel delegate is the object the l2cap uses as target for data and events. The developer will implement only the the methods he/she is interested in. A list of the possible methods is at the end of the file "IOBluetoothL2CAPChannel.h in the definition of the protocol IOBluetoothL2CAPChannelDelegate.

Return Value

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

Discussion

This method 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.

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

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

- (IOReturn)openL2CAPChannelSync:(IOBluetoothL2CAPChannel **)newChannel 
        withPSM:(BluetoothL2CAPPSM)psm delegate:(id)channelDelegate; 

Parameters

newChannel

A pointer to an IOBluetoothL2CAPChannel object 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.

channelDelegate

The object that will play the role of delegate for the channel. A channel delegate is the object the L2CAP uses as target for data and events. The developer will implement only the the methods he/she is interested in. A list of the possible methods is at the end of the file "IOBluetoothL2CAPChannel.h" in the definition of the protocol IOBluetoothL2CAPChannelDelegate.

Return Value

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

Discussion

This method 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.

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

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

- (IOReturn)openL2CAPChannelSync:(IOBluetoothL2CAPChannel **)newChannel 
        withPSM:(BluetoothL2CAPPSM)psm withConfiguration:(NSDictionary*)channelConfiguration 
        delegate:(id)channelDelegate; 

Parameters

newChannel

A pointer to an IOBluetoothL2CAPChannel object to receive the L2CAP channel requested to be opened. The newChannel pointer will only be set if kIOReturnSuccess is returned.

withPSM

The L2CAP PSM value for the new channel.

channelConfiguration

the dictionary that describes the initial configuration for the channel.

delegate

the object that will play the role of delegate for the channel. A channel delegate is the object the l2cap uses as target for data and events. The developer will implement only the the methods he/she is interested in. A list of the possible methods is at the end of the file "IOBluetoothL2CAPChannel.h in the definition of the protocol IOBluetoothL2CAPChannelDelegate.

Return Value

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

Discussion

This method 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.

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

Opens a new RFCOMM channel to the target device. Returns only once the channel is open or failed to open.

- (IOReturn)openRFCOMMChannel:(BluetoothRFCOMMChannelID)channelID 
        channel:(IOBluetoothRFCOMMChannel **)rfcommChannel DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER; 

Parameters

channelID

The RFCOMM channel ID for the new channel.

rfcommChannel

A pointer to an IOBluetoothRFCOMMChannel object 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 method 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.

Opens a new RFCOMM channel to the target device. Returns immediately.

- (IOReturn)openRFCOMMChannelAsync:(IOBluetoothRFCOMMChannel **)rfcommChannel 
        withChannelID:(BluetoothRFCOMMChannelID)channelID delegate:(id)channelDelegate; 

Parameters

rfcommChannel

A pointer to an IOBluetoothRFCOMMChannel object 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.

channelDelegate

The object that will play the role of delegate for the channel. A channel delegate is the object the RFCOMM uses as target for data and events. The developer will implement only the the methods he/she is interested in. A list of the possible methods is at the end of the file "IObluetoothRFCOMMChannel.h in the definition of the protocol IOBluetoothRFCOMMChannelDelegate.

Return Value

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

Discussion

This method 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.

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

Opens a new RFCOMM channel to the target device. Returns only once the channel is open or failed to open.

- (IOReturn)openRFCOMMChannelSync:(IOBluetoothRFCOMMChannel **)rfcommChannel 
        withChannelID:(BluetoothRFCOMMChannelID)channelID delegate:(id)channelDelegate; 

Parameters

rfcommChannel

A pointer to an IOBluetoothRFCOMMChannel object 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.

channelDelegate

The object that will play the role of delegate for the channel. A channel delegate is the object the RFCOMM uses as target for data and events. The developer will implement only the the methods he/she is interested in. A list of the possible methods is at the end of the file "IObluetoothRFCOMMChannel.h in the definition of the protocol IOBluetoothRFCOMMChannelDelegate.

Return Value

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

Discussion

This method 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.

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

Gets an array of all of the paired devices on the system.

+ (NSArray *)pairedDevices; 

Return Value

Returns an array of device objects for all of the paired devices on the system. If there are no paired devices, nil is returned.

Discussion

The resulting array contains IOBluetoothDevice objects. The paired devices are currently NOT stored per user, so this is all devices paired by any user.

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

Performs an SDP query on the target device.

- (IOReturn)performSDPQuery:(id)target; 

Parameters

target

The target to message when the SDP query is complete

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 target is specified, when the SDP query is complete (or an error is encountered), the method -sdpQueryComplete:status: will be called on the given target. If no target is specified, the request is still synchronous, but no callback will be made. That can be useful if the client has registered for SDP service changed notifications.

Returns the date/time of the most recent access of the target device.

- (NSDate *)recentAccessDate; 

Return Value

Returns the date/time of the most recent access of the target device. If the device has not been accessed, nil is returned.

Discussion

This is the date that -recentDevices uses to sort its list of the most recently accessed devices.

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

Gets an array of recently used Bluetooth devices.

+ (NSArray *)recentDevices:(unsigned long)numDevices; 

Parameters

numDevices

The number of devices to return.

Return Value

Returns an array of device objects recently used by the system. If no devices have been accessed, nil is returned.

Discussion

The resulting array contains IOBluetoothDevice objects sorted in reverse chronological order. The most recently accessed devices are first. If the numDevices parameter is 0, all devices accessed by the system are returned. If numDevices is non-zero, only the most recent devices are returned.

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

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

+ (IOBluetoothUserNotification *)
        registerForConnectNotifications:(id)observer selector:(SEL)inSelector; 

Parameters

observer

Target observer object

inSelector

Selector to be sent to the observer when a new connection is made

Return Value

Returns an IOBluetoothUserNotification representing the outstanding device connect notification. To unregister the notification, call -unregister on the returned IOBluetoothUserNotification object. If an error is encountered creating the notification, nil is returned. The returned IOBluetoothUserNotification object will be valid for as long as the notification is registered. It is not necessary to retain the result. Once -unregister is called on it, it will no longer be valid.

Discussion

The given selector will be called on the target observer whenever any device connection is made. The selector should accept two arguments. The first is the user notification object. The second is the device that was connected.

Allows a client to register for device disconnect notification.

- (IOBluetoothUserNotification *)
        registerForDisconnectNotification:(id)observer selector:(SEL)inSelector; 

Parameters

observer

Target observer object

inSelector

Selector to be sent to the observer when the connection is destroyed

Return Value

Returns an IOBluetoothUserNotification representing the outstanding device disconnect notification. To unregister the notification, call -unregister of the returned IOBluetoothUserNotification object. If an error is encountered creating the notification, nil is returned.

Discussion

The given selector will be called on the target observer when the target device's connection is closed. The selector should contain two arguments. The first is the user notification object. The second is the IOBluetoothDevice that was disconnected.

Issues a remote name request to the target device.

- (IOReturn)remoteNameRequest:(id)target; 

Parameters

target

The target to message when the remote name request is complete

Return Value

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

Discussion

If a target is specified, the request is asynchronous and on completion of the REMOTE_NAME_REQUEST command, the method -remoteNameRequestComplete:status:name: will be called on the specified target. If no target is specified, the request is made synchronously and won't return until the request is complete. This call with operate with the default page timeout value. If a different page timeout value is desired, the method -remoteNameRequest:withPageTimeout: should be used instead.

Issues a remote name request to the target device.

- (IOReturn)remoteNameRequest:(id)target withPageTimeout:(BluetoothHCIPageTimeout)pageTimeoutValue; 

Parameters

target

The target to message when the remote name request is complete

pageTimeoutValue

The page timeout value to use for this call

Return Value

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

Discussion

If a target is specified, the request is asynchronous and on completion of the REMOTE_NAME_REQUEST command, the method -remoteNameRequestComplete:status:name: will be called on the specified target. If no target is specified, the request is made synchronously and won't return until the request is complete.

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

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

- (IOReturn)removeFromFavorites; 

Return Value

Returns kIOReturnSuccess if the device was successfully removed from the user's list of favorite devices.

Discussion

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

Requests that the existing baseband connection be authenticated.

- (IOReturn)requestAuthentication; 

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.

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

- (IOReturn)sendL2CAPEchoRequest:(void *)data length:(UInt16)length; 

Parameters

data

(void *) - Pointer to buffer to send.

length

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

Sets the connection supervision timeout.

- (IOReturn)setSupervisionTimeout:(UInt16)timeout; 

Parameters

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.

Returns the IOBluetoothDevice object for the given BluetoothDeviceAddress

+ (IOBluetoothDevice *)withAddress:(const BluetoothDeviceAddress *)address; 

Parameters

address

Pointer to a BluetoothDeviceAddress for which an IOBluetoothDevice instance is desired

Return Value

Returns the IOBluetoothDevice object for the given BluetoothDeviceAddress

Discussion

Within a single application, there will be only one instance of IOBluetoothDevice for a given remote device address.

Method call to convert an IOBluetoothDeviceRef into an IOBluetoothDevice *.

+ (IOBluetoothDevice *)withDeviceRef:(IOBluetoothDeviceRef)deviceRef; 

Parameters

deviceRef

IOBluetoothDeviceRef for which an IOBluetoothDevice * is desired.

Return Value

Returns the IOBluetoothDevice * for the given IOBluetoothDeviceRef.

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.