IOBluetoothUtilities.h

Overview

This header defines various functions for working with Bluetooth devices and data.

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

Functions

IOBluetoothFindNumberOfRegistryEntriesOfClassName

Returns total number of registry entries with the provided device classname. e.g. "IOHIPointing"

IOBluetoothGetUniqueFileNameAndPath

IOBluetoothIsFileAppleDesignatedPIMData

Apple designated PIM data is classified as: .vcard, .vcal, .vcf, .vnote, .vmsg, .vcs

IOBluetoothNSStringFromDeviceAddress

Convenience routine to take a device address structure and create an NSString.

IOBluetoothNSStringToDeviceAddress

Convenience routine to take an NSString and turn it into a BluetoothDeviceAddress structure.

IOBluetoothNumberOfAvailableHIDDevices

Returns total number of HID devices on the system (Bluetooth + USB)

IOBluetoothNumberOfKeyboardHIDDevices

Returns number of keyboard HID devices on the system (Bluetooth + USB)

IOBluetoothNumberOfPointingHIDDevices

Returns number of "pointing" HID devices on the system (Bluetooth + USB)

IOBluetoothNumberOfTabletHIDDevices

Returns number of "Tablet" HID devices on the system (Bluetooth + USB)

IOBluetoothPackData

Packs a variable amount of parameters into a buffer according to a printf-style format string.

IOBluetoothUnpackData

Unpacks a variable amount of data from a buffer into a variable number of parameters according to a printf-style format string.

Returns total number of registry entries with the provided device classname. e.g. "IOHIPointing"

extern long IOBluetoothFindNumberOfRegistryEntriesOfClassName(
    const char *deviceType ) AVAILABLE_BLUETOOTH_VERSION_1_3_AND_LATER;  

Return Value

Number of HID devices.

extern NSString* IOBluetoothGetUniqueFileNameAndPath(
    NSString *inName,
    NSString *inPath );  

Parameters

inName

Name of file that needs unique name in the specified path.

inPath

Path you are trying to put file into.

Return Value

String with a unique name appended on it for the provided path.

Discussion

When passed a VALID filename and a VALID path, this routine will return you a the path with the name appended onto it. If it already exist, it will insert a #1, #2, etc. Example: If you pass @"TestFile.txt" and @"~/Documents", you will get @"~Documents/TestFile.txt". If one already exists, you will be returned: @"~Documents/TestFile #1.txt".

Apple designated PIM data is classified as: .vcard, .vcal, .vcf, .vnote, .vmsg, .vcs

extern Boolean IOBluetoothIsFileAppleDesignatedPIMData(
    NSString *inFileName );  

Parameters

inFileName

Name of file - should include extension!

Return Value

Yes or no, is it Apple-designated PIM data?

Discussion

Not much to talk about.

Convenience routine to take a device address structure and create an NSString.

extern NSString * IOBluetoothNSStringFromDeviceAddress(
    const BluetoothDeviceAddress *deviceAddress );  

Parameters

deviceAddress

A valid bluetooth device structure.

Return Value

Returns the created address string.

Discussion

The resultant string will be in this format: "00-11-22-33-44-55"

Convenience routine to take an NSString and turn it into a BluetoothDeviceAddress structure.

extern IOReturn IOBluetoothNSStringToDeviceAddress(
    NSString *inNameString,
    BluetoothDeviceAddress *outDeviceAddress );  

Parameters

inNameString

Ptr to an NSString that contains the data to turn into the device address.

outDeviceAddress

Ptr to an address structure that will be returned.

Return Value

Returns success (0) or failure code.

Discussion

Pass in most types of strings, such as "001122334455" or "00-11-22-33-44-55" and the conversion should be successful. Also, you should have 2 characters per byte for the conversion to work properly.

Returns total number of HID devices on the system (Bluetooth + USB)

extern long IOBluetoothNumberOfAvailableHIDDevices() AVAILABLE_BLUETOOTH_VERSION_1_3_AND_LATER;  

Return Value

Number of HID devices.

Returns number of keyboard HID devices on the system (Bluetooth + USB)

extern long IOBluetoothNumberOfKeyboardHIDDevices() AVAILABLE_BLUETOOTH_VERSION_1_3_AND_LATER;  

Return Value

Number of HID devices.

Returns number of "pointing" HID devices on the system (Bluetooth + USB)

extern long IOBluetoothNumberOfPointingHIDDevices() AVAILABLE_BLUETOOTH_VERSION_1_3_AND_LATER;  

Return Value

Number of HID devices.

Returns number of "Tablet" HID devices on the system (Bluetooth + USB)

extern long IOBluetoothNumberOfTabletHIDDevices() AVAILABLE_BLUETOOTH_VERSION_1_3_AND_LATER;  

Return Value

Number of HID devices.

Packs a variable amount of parameters into a buffer according to a printf-style format string.

extern long IOBluetoothPackData(
    void *ioBuffer,
    const char *inFormat,
    ... );  

Parameters

ioBuffer

Ptr to buffer to receive packed data.

inFormat

printf-style format string controlling how the data is packed.

varArg

Variable number parameters controlled by the printf-style format string (only PackData).

inArgs

Variable argument list containing data controlled by format string (only PackDataList).

Return Value

Number of bytes packed or -1 if an error occurred.

Discussion

Supported format characters:

		'b' 1 byte of data ('b'yte)
		'h' 2 bytes of data ('h'alf-word)
		'H' 2 bytes of data ('h'alf-word) to byte reverse.
		't' 3 bytes of data ('t'riple byte, least significant 24-bits).
		'T' 3 bytes of data ('t'riple byte, least significant 24-bits) to byte reverse.
		'w' 4 bytes of data ('w'ord).
		'W' 4 bytes of data ('w'ord) to byte reverse.
		'1'	Ptr to 1 byte of data.
		'2' Ptr to 2 bytes of data.
		'@'	(shift-2) Ptr to 2 bytes of data to byte reverse.
		'3' Ptr to 3 bytes of data.
		'#'	(shift-3) Ptr to 3 bytes of data to byte reverse.
		'4' Ptr to 4 bytes of data.
		'$'	(shift-4) Ptr to 4 bytes of data to byte reverse.
		'5' Ptr to 5 bytes of data.
		'%'	(shift-5) Ptr to 5 bytes of data to byte reverse.
		'6' Ptr to 6 bytes of data.
		'^'	(shift-6) Ptr to 6 bytes of data to byte reverse.
		'7' Ptr to 6 bytes of data.
		'&'	(shift-7) Ptr to 7 bytes of data to byte reverse.
		'8' Ptr to 6 bytes of data.
		'*'	(shift-8) Ptr to 8 bytes of data to byte reverse.
		'9' Ptr to 6 bytes of data.
		'('	(shift-9) Ptr to 9 bytes of data to byte reverse.
		'n' Ptr to n bytes of data (first param is size, second is ptr).
		'N' Ptr to n bytes of data to byte reverse (first param is size, second is ptr).
		's' Ptr to C-string (includes null terminator)
		'p' Ptr to Pascal-string (includes length byte).
	

Example usage:

		bytesPacked = PackData( buffer, "bts", 'U', 'XYZ', "This is a C-style string" );
	

Warning: Raw values packed with 'b', 'h', 't', and 'w' have their bytes packed into the buffer from left to right even on little-endian systems. For example, the value 0x12345678 would be sent out as 0x12 0x34 0x56 0x78. This needs to be taken into consideration if the value is expected to be in little-endian format in the buffer. This case requires you byte swap the value on all systems before sending it to this routine.

Unpacks a variable amount of data from a buffer into a variable number of parameters according to a printf-style format string.

extern long IOBluetoothUnpackData(
    ByteCount inBufferSize,
    const void *inBuffer,
    const char *inFormat,
    ... );  

Parameters

inBufferSize

Size of buffer to unpack data from.

inBuffer

Ptr to buffer to unpack data from.

inFormat

printf-style format string controlling how the data is unpacked.

varArg

Variable number parameters to receive data, controlled by the format string (only UnpackData).

inArgs

Variable argument list containing data controlled by format string (only UnpackDataList).

Return Value

Number of bytes unpacked or -1 if an error occurred.

Discussion

Supported format characters:

		'b' Ptr to receive 1 byte of data ('b'yte).
		'h' Ptr to receive 2 bytes of data ('h'alf-word).
		'H' Ptr to receive 2 bytes of byte-reversed data ('h'alf-word).
		't' Ptr to receive 3 bytes of data ('t'riple byte, least significant 24-bits).
		'T' Ptr to receive 3 bytes of byte-reversed data ('t'riple byte, least significant 24-bits).
		'w' Ptr to receive 4 bytes of data ('w'ord).
		'W' Ptr to receive 4 bytes of byte-reversed data ('w'ord).
		'1' Ptr to receive 1 byte of data.
		'2' Ptr to receive 2 bytes of data.
		'@'	(shift-2) Ptr to 2 bytes of data, byte reversed.
		'3' Ptr to receive 3 bytes of data.
		'#'	(shift-3) Ptr to receive 3 bytes of data, byte reversed.
		'4' Ptr to receive 4 bytes of data.
		'$'	(shift-4) Ptr to receive 4 bytes of data, byte reversed.
		'5' Ptr to receive 5 bytes of data.
		'%'	(shift-5) Ptr to receive 5 bytes of data, byte reversed.
		'6' Ptr to receive 6 bytes of data.
		'^'	(shift-6) Ptr to receive 6 bytes of data, byte reversed.
		'7' Ptr to receive 7 bytes of data.
		'&'	(shift-7) Ptr to receive 7 bytes of data, byte reversed.
		'8' Ptr to receive 8 bytes of data.
		'*'	(shift-8) Ptr to receive 8 bytes of data, byte reversed.
		'9' Ptr to receive 9 bytes of data.
		'('	(shift-9) Ptr to receive 9 bytes of data, byte reversed.
		'n' Ptr to receive n bytes of data (first param is size, second is ptr to receive data).
		'N' Ptr to receive n bytes of data to byte reverse (first param is size, second is ptr to receive data).
		's' Ptr to receive C-string (first param is max size, second is ptr to receive data).
		'p' Ptr to receive Pascal-string (first param is max size including length-byte, second is ptr to receive data).
	

Example usage:

		bytesUnpacked = UnpackData( 100, buffer, "bwnsp", &myByte1, &myWord, 50, buffer1, 128, buffer2, 255, pString );
	

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.