IOBluetoothDeviceInquiry

Overview

Object representing a device inquiry that finds Bluetooth devices in-range of the computer, and (optionally) retrieves name information for them.

Discussion

You should only use this object if your application needs to know about in-range devices and cannot use the GUI provided by the IOBluetoothUI framework. It will not let you perform unlimited back-to-back inquiries, but will instead throttle the number of attempted inquiries if too many are attempted within a small window of time. Important Note: DO NOT perform remote name requests on devices from delegate methods or while this object is in use. If you wish to do your own remote name requests on devices, do them after you have stopped this object. If you do not heed this warning, you could potentially deadlock your process.

Methods

-clearFoundDevices

Removes all found devices from the inquiry object.

-delegate

Returns the current delegate, if any.

-foundDevices

Returns found IOBluetoothDevice objects as an array.

-initWithDelegate:

Initializes an alloc'd inquiry object, and sets the delegate object, as if -setDelegate: were called on it.

-inquiryLength

Returns the number of seconds the search will be performed.

+inquiryWithDelegate:

Class method to create an inquiry object.

-setDelegate:

Set the delegate that will receive delegate messages, as defined below.

-setInquiryLength:

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

-setSearchCriteria

Use this method to set the criteria for the device search.

-setSearchCriteria:majorDeviceClass:minorDeviceClass:

Use this method to set the criteria for the device search.

-setUpdateNewDeviceNames:

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

-start

Tells inquiry object to begin the inquiry and name updating process, if specified.

-stop

Halts the inquiry object. Could either stop the search for new devices, or the updating of found device names.

-updateNewDeviceNames

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

Removes all found devices from the inquiry object.

- (void)clearFoundDevices; 

Returns the current delegate, if any.

- (id)delegate; 

Return Value

Returns delegate object, otherwise returns nil.

Returns found IOBluetoothDevice objects as an array.

- (NSArray*)foundDevices; 

Return Value

Returns an NSArray of IOBluetoothDevice objects.

Discussion

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

Initializes an alloc'd inquiry object, and sets the delegate object, as if -setDelegate: were called on it.

- (id)initWithDelegate:(id)delegate; 

Parameters

delegate

A delegate object that wishes to receive messages from the inquiry object. Delegate methods are listed below, under IOBluetoothDeviceInquiryDelegate.

Return Value

A pointer to the initialized IOBluetoothDeviceInquiry object.

Returns the number of seconds the search will be performed.

- (uint8_t)inquiryLength; 

Return Value

Number of seconds the search will be performed.

Class method to create an inquiry object.

+ (IOBluetoothDeviceInquiry *)inquiryWithDelegate:(id)delegate; 

Parameters

delegate

A delegate object that wishes to receive messages from the inquiry object. Delegate methods are listed below, under IOBluetoothDeviceInquiryDelegate.

Return Value

A pointer to the created IOBluetoothDeviceInquiry object.

Discussion

The inquiry is NOT automatically started. You musts call -start on it to start the search for in-range devices.

Set the delegate that will receive delegate messages, as defined below.

- (void)setDelegate:(id)delegate; 

Parameters

delegate

The object that should receive delegate messages.

Discussion

All delegate methods are optional, although it would be a good idea to implement them all. The passed object will be retained.

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

- (uint8_t)setInquiryLength:(uint8_t)seconds; 

Parameters

seconds

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

Return Value

Number of seconds the search will be performed.

Discussion

A default of 10 seconds is used, unless a different value is specified using this method. Note that if you have called -start again too quickly, your inquiry may actually take much longer than what length you specify, as inquiries are throttled in the system. Also note that if you have the inquiry object updating device names for you, the whole inquiry process could be much longer than the specified length, depending on the number of devices found and how responsive to name requests they are. If you -must- have a strict inquiry length, disable name updates. In other words, this "length" only refers to the actual device discovery portion of the whole inquiry process.

Use this method to set the criteria for the device search.

setSearchCriteria:majorDeviceClass:minorDeviceClass:

- (void)setSearchCriteria:(BluetoothServiceClassMajor)inServiceClassMajor majorDeviceClass:(BluetoothDeviceClassMajor)inMajorDeviceClass minorDeviceClass:(BluetoothDeviceClassMinor)inMinorDeviceClass; 

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 will search for all types of devices. If you wish to find only keyboards, for example, you might use this method like this:

[myInquiryObject setSearchCriteria:kBluetoothServiceClassMajorAny majorDeviceClass:kBluetoothDeviceClassMajorPeripheral minorDeviceClass: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.

Use this method to set the criteria for the device search.

setSearchCriteria

- (void)setSearchCriteria:(BluetoothServiceClassMajor)inServiceClassMajor majorDeviceClass:(BluetoothDeviceClassMajor)inMajorDeviceClass minorDeviceClass:(BluetoothDeviceClassMinor)inMinorDeviceClass; 

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 will search for all types of devices. If you wish to find only keyboards, for example, you might use this method like this:

[myInquiryObject setSearchCriteria:kBluetoothServiceClassMajorAny majorDeviceClass:kBluetoothDeviceClassMajorPeripheral minorDeviceClass: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 whether or not the inquiry object will retrieve the names of devices found during the search.

- (void)setUpdateNewDeviceNames:(BOOL)inValue; 

Parameters

inValue

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.

Tells inquiry object to begin the inquiry and name updating process, if specified.

- (IOReturn)start; 

Return Value

Returns kIOReturnSuccess if start was successful. Returns kIOReturnBusy if the object is already in process. May return other IOReturn values, as appropriate.

Discussion

Calling start multiple times in rapid succession or back-to-back will probably not produce the intended results. Inquiries are throttled if they are called too quickly in succession.

Halts the inquiry object. Could either stop the search for new devices, or the updating of found device names.

- (IOReturn)stop; 

Return Value

Returns kIOReturnSuccess if the inquiry is successfully stopped. Returns kIOReturnNotPermitted if the inquiry object is already stopped. May return other IOReturn values, as appropriate.

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

- (BOOL)updateNewDeviceNames; 

Return Value

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

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.