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

IOBluetoothUtilities.h

Include Path:	<IOBluetooth/IOBluetoothUtilities.h>
Path:	/System/Library/Frameworks/IOBluetooth.framework/Versions/A/Headers/IOBluetoothUtilities.h
Includes:	<stdio.h> <stdlib.h> <string.h> <sysexits.h> <sys/errno.h> <unistd.h> <IOBluetooth/Bluetooth.h> <IOKit/IOReturn.h> <IOBluetooth/IOBluetoothUserLib.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.

IOBluetoothFindNumberOfRegistryEntriesOfClassName

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.

IOBluetoothGetUniqueFileNameAndPath

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

IOBluetoothIsFileAppleDesignatedPIMData

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.

IOBluetoothNSStringFromDeviceAddress

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"

IOBluetoothNSStringToDeviceAddress

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.

IOBluetoothNumberOfAvailableHIDDevices

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.

IOBluetoothNumberOfKeyboardHIDDevices

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.

IOBluetoothNumberOfPointingHIDDevices

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.

IOBluetoothNumberOfTabletHIDDevices

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.

IOBluetoothPackData

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.

IOBluetoothUnpackData

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.

Last Updated: 2008-03-11