(68K) Bluetooth Library: Management | Palm OS® Programmer's API Reference

The management API of the Bluetooth library supports the lower levels of the Bluetooth specification, specifically the radio, baseband, and Link Manager Protocol specifications. This chapter presents reference material for the management API:

Bluetooth Management Data Structures: This section lists some of the more important types used by the Bluetooth library management functions.
Management Callback Events: This section lists the management callback events. Most of the management functions are asynchronous. In other words, they start operations and return before the operations complete. To signal the application that management operations have completed, the Bluetooth library generates management callback events by calling a callback function.
Management Event Status Codes: When a management event is generated, the status field of the associated BtLibManagementEventType provides information about why the event occurred. This section explains what these codes mean.
Library Management Functions: This section describes the functions that open and close the shared library.
Management Functions: The management functions handle the lower levels of the Bluetooth specification, specifically the radio, baseband, and Link Manager Protocol specifications. These functions perform tasks that include discovering devices, working with Asynchronous Connectionless (ACL) links and piconets, and maintaining global settings for the Bluetooth library.
Application-Defined Functions: This section describes the callback functions that handle management events.

The header file BtLib.h declares the Bluetooth library functions and macros. The header file BtLibTypes.h declares the data structures that you use with those functions and macros. For more information about using the Bluetooth library, see the Palm OS Programmer's Companion Supplement: Bluetooth.

Bluetooth Management Data Structures ^TOP^

This section lists some of the more important types used by the Bluetooth library management functions.

BtLibAccessibleModeEnum Enum ^TOP^

Purpose

The BtLibAccessibleModeEnum enum specifies a device's accessibility modes. See the "Generic Access Profile" chapter of the Specification of the Bluetooth System for more information about accessibility.

Prototype

typedef enum {
  btLibNotAccessible = 0x00,
  btLibConnectableOnly = 0x02,
  btLibDiscoverableAndConnectable = 0x03
} BtLibAccessibleModeEnum;

Constants

btLibConnectableOnly: The device responds to a page but not an inquiry.
btLibDiscoverableAndConnectable: The device responds to both a page and an inquiry.
btLibNotAccessible: The device does not respond to a page or an inquiry.

BtLibClassOfDeviceType Typedef ^TOP^

Purpose

The BtLibClassOfDeviceType type represents the class of the device and the services it supports.

Prototype

typedef UInt32 BtLibClassOfDeviceType;

A device can support multiple services but only belongs to a single class. The class is specified in two parts: the major class, which broadly classifies the type of device, and the minor class, which together with the major class specifies the type of device in more detail.

An example is a simple cellular telephone. It provides Telephony services. Its major device class is Phone, and its minor device class is Cellular.

The Bluetooth Assigned Numbers specification defines a device class as having three bit fields. One field specifies the major service classes supported by the device. Another field specifies the major device class. The third field specifies the minor device class.

The constants provided here allow you to construct a device class that conforms to the Bluetooth specification. You simply perform a logical OR of the constants representing the service classes the device supports, the constant representing the device's major class, and the constant representing the device's minor class.

For example, device class of the simple cellular telephone can be computed as follows:

cellPhoneCOD = btLibCOD_Telephony | 
  btLibCOD_Major_Phone | 
  BtLibCOD_Minor_Phone_Cellular;

Constants are also provided to mask the individual bit fields in a device class.

Major Service Classes

These constants define the Bluetooth major service classes. The service classes are described in the Specification of the Bluetooth System.

Constants

btLibCOD_LimitedDiscoverableMode
btLibCOD_Networking
btLibCOD_Rendering
btLibCOD_Capturing
btLibCOD_ObjectTransfer
btLibCOD_Audio
btLibCOD_Telephony
btLibCOD_Information

Major Device Classes

These constants define the Bluetooth major device classes. The major device classes are described in the Specification of the Bluetooth System.

Constants

btLibCOD_Major_Misc
btLibCOD_Major_Computer
btLibCOD_Major_Phone
btLibCOD_Major_Lan_Access_Point
btLibCOD_Major_Audio
btLibCOD_Major_Peripheral
btLibCOD_Major_Imaging
btLibCOD_Major_Unclassified

Computer Minor Device Classes

These constants define the minor device classes associated with the computer major class. They are described in the Bluetooth Assigned Numbers specification.

Constants

btLibCOD_Minor_Comp_Unclassified
btLibCOD_Minor_Comp_Desktop
btLibCOD_Minor_Comp_Server
btLibCOD_Minor_Comp_Laptop
btLibCOD_Minor_Comp_Handheld
btLibCOD_Minor_Comp_Palm

Phone Minor Device Classes

These constants define the minor device classes are associated with the computer major class. They are described in the Bluetooth Assigned Numbers specification.

Constants

btLibCOD_Minor_Phone_Unclassified
btLibCOD_Minor_Phone_Cellular
btLibCOD_Minor_Phone_ISDN
btLibCOD_Minor_Phone_Cordless
btLibCOD_Minor_Phone_Smart
btLibCOD_Minor_Phone_Modem

LAN Access Point Minor Device Classes

These constants define load factors for the LAN access point major device class. LAN access point load factors are described in more detail in the Bluetooth Assigned Numbers specification.

Constants

btLibCOD_Minor_Lan_0: Fully available
btLibCOD_Minor_Lan_17: 1-17% utilized
btLibCOD_Minor_Lan_33: 17-33% utilized
btLibCOD_Minor_Lan_50: 33-50% utilized
btLibCOD_Minor_Lan_67: 50-67% utilized
btLibCOD_Minor_Lan_83: 67-83% utilized
btLibCOD_Minor_Lan_99: 83-99% utilized
btLibCOD_Minor_Lan_NoService: Fully utilized

Audio Minor Device Classes

These constants define the minor classes associated with the audio major class. They are described in more detail in the Bluetooth Assigned Numbers specification.

Constants

btLibCOD_Minor_Audio_Unclassified
btLibCOD_Minor_Audio_Headset
btLibCOD_Minor_Audio_HandFree
btLibCOD_Minor_Audio_MicroPhone
btLibCOD_Minor_Audio_LoudSpeaker
btLibCOD_Minor_Audio_HeadPhone
btLibCOD_Minor_Audio_PortableAudio
btLibCOD_Minor_Audio_CarAudio
btLibCOD_Minor_Audio_SetTopBox
btLibCOD_Minor_Audio_HifiAudio
btLibCOD_Minor_Audio_VCR
btLibCOD_Minor_Audio_VideoCamera
btLibCOD_Minor_Audio_CamCorder
btLibCOD_Minor_Audio_VideoMonitor
btLibCOD_Minor_Audio_VideoDisplayAndLoudSpeaker
btLibCOD_Minor_Audio_VideoConf
btLibCOD_Minor_Audio_GameToy

Peripheral Minor Device Classes

These constants define the minor classes associated with the peripheral major class. They are described in more detail in the Bluetooth Assigned Numbers specification.

Constants

btLibCOD_Minor_Peripheral_Unclassified
btLibCOD_Minor_Peripheral_Keyboard
btLibCOD_Minor_Peripheral_Pointing
btLibCOD_Minor_Peripheral_Combo

Peripheral Minor Device Subclasses

These constants define further subclasses associated with the peripheral minor classes. They are described in more detail in the Bluetooth Assigned Numbers specification.

Constants

btLibCOD_Minor_Peripheral_Joystick
btLibCOD_Minor_Peripheral_GamePad
btLibCOD_Minor_Peripheral_RemoteControl
btLibCOD_Minor_Peripheral_Sensing
btLibCOD_Minor_Peripheral_DigitizerTablet
btLibCOD_Minor_Peripheral_CardReader

Imaging Minor Device Classes

These constants define the minor classes associated with the imaging major class. They are described in more detail in the Bluetooth Assigned Numbers specification.

Constants

btLibCOD_Minor_Imaging_Unclassified
btLibCOD_Minor_Imaging_Display
btLibCOD_Minor_Imaging_Camera
btLibCOD_Minor_Imaging_Scanner
btLibCOD_Minor_Imaging_Printer

Masks

These constants define bit masks to isolate certain fields of the device class.

Constants

btLibCOD_Service_Mask: A mask to isolate the major service class field from the other fields of the device class.
btLibCOD_Major_Mask: A mask to isolate the major device class field from the other fields of the device class.
btLibCOD_Minor_Mask: A mask to isolate the minor device class field from the other fields of the device class.
btLibCOD_ServiceAny: Used as a device filter for the BtLibDiscoverMultipleDevices() and BtLibDiscoverSingleDevice() functions. With this filter, devices providing any service appear in the device list. Same as btLibCOD_Service_Mask.
btLibCOD_Major_Any: Used as a device filter for the BtLibDiscoverMultipleDevices() and BtLibDiscoverSingleDevice() functions. With this filter, devices in any major device class appear in the device list. Same as btLibCOD_Major_Mask.
btLibCOD_Minor_Any: Used as a device filter for the BtLibDiscoverMultipleDevices() and BtLibDiscoverSingleDevice() functions. With this filter, devices in any minor device class appear in the device list. Same as btLibCOD_Minor_Mask.
btLibCOD_Minor_Comp_Any: Used as a device filter for the BtLibDiscoverMultipleDevices() and BtLibDiscoverSingleDevice() functions. When this filter is used in conjunction with btLibCOD_Major_Computer, all devices broadcasting themselves as computers appear in the device list. Same as btLibCOD_Minor_Any.
btLibCOD_Minor_Phone_Any: Used as a device filter for the BtLibDiscoverMultipleDevices() and BtLibDiscoverSingleDevice() functions. When this filter is used in conjunction with btLibCOD_Major_Phone, all devices broadcasting themselves as phones appear in the device list. Same as btLibCOD_Minor_Any.
btLibCOD_Minor_LAN_Any: Used as a device filter for the BtLibDiscoverMultipleDevices() and BtLibDiscoverSingleDevice() functions. When this filter is used in conjunction with btLibCOD_Major_Lan_Access_Point, all devices broadcasting themselves as LAN access points appear in the device list. Same as btLibCOD_Minor_Any.
btLibCOD_Minor_Audio_Any: Used as a device filter for the BtLibDiscoverMultipleDevices() and BtLibDiscoverSingleDevice() functions. When this filter is used in conjunction with btLibCOD_Major_Audio, all devices broadcasting themselves as audio devices appear in the device list. Same as btLibCOD_Minor_Any.

BtLibConnectionRoleEnum Enum ^TOP^

Purpose

The BtLibConnectionRoleEnum enum specifies all the connection roles a device can have. A device can either be a master or a slave.

Prototype

typedef enum {
  btLibMasterRole,
  btLibSlaveRole
} BtLibConnectionRoleEnum;

Constants

btLibMasterRole: The device is a master.
btLibSlaveRole: The device is a slave.

BtLibDeviceAddressType Struct ^TOP^

Purpose

The BtLibDeviceAddressType structure represents a 48-bit Bluetooth device address.

Prototype

#define btLibDeviceAddressSize 6

typedef struct BtLibDeviceAddressType {
    UInt8 address[btLibDeviceAddressSize];
} BtLibDeviceAddressType;

BtLibFriendlyNameType Struct ^TOP^

Purpose

The BtLibFriendlyNameType structure contains the user-friendly name of a device.

Prototype

typedef struct BtLibFriendlyNameType {
  UInt8  *name;
  UInt8  nameLength;
} BtLibFriendlyNameType,

  *BtLibFriendlyNameTypePtr;

Fields

name: Array of characters, encoded according to the UTF-8 standard, containing the user-friendly name of the device. This array is not null-terminated.
nameLength: The number of characters in the user-friendly name. The maximum size is 249 characters.

BtLibManagementEventType Struct ^TOP^

Purpose

The BtLibManagementEventType structure contains detailed information regarding a management callback event. All management events have some common data. Most management events have data specific to those events. The specific data uses a union that is part of the BtLibManagementEvent data structure.

Prototype

typedef struct _BtLibManagementEventType {
  BtLibManagementEventEnum event;
  Err status;
  union {
    ...
  } eventData;
} BtLibManagementEventType;

Fields

event: A BtLibManagementEventEnum enum member that indicates which management event has occurred. See Management Callback Events.
status: Status of the event. The Management Callback Events section gives more details about how to interpret this field for specific events.
eventData: Data associated with the event. The member of this union that is valid depends on the event. See Management Callback Events for more information.

A BtLibManagementEventType object is passed as the first argument of the BtLibManagementCallback() callback function.

Management Callback Events ^TOP^

The management functions of the Bluetooth library support the lower levels of the Bluetooth specification, specifically the radio, baseband, and Link Manager Protocol specifications. Most of the management functions are asynchronous. In other words, they start operations and return before the operations complete. To signal the application that management operations have completed, the Bluetooth library generates management callback events by calling a callback function.

You specify the callback function using the BtLibRegisterManagementNotification() function. When an event occurs, the callback function is called with two parameters: a pointer to a BtLibManagementEventType structure and a pointer to a user-defined structure.

The BtLibManagementEventType structure contains an event field, which indicates the reason the callback is called, a status field, which contains status information associated with the event, and a union of several structures. The member of the union that is valid depends on the event. The meaning of the events is described in the following sections.

For more information about the status field, see Management Event Status Codes.

btLibManagementEventAccessibilityChange ^TOP^

The accessibility mode of the local device has changed.

For this event, the eventData field contains the following field:

BtLibAccessibleModeEnum accessible;

This BtLibAccessibleModeEnum represents the new accessibility mode of the local device.

This event can result from calling BtLibOpen(), BtLibPiconetCreate(), or BtLibSetGeneralPreference().

btLibManagementEventAclConnectInbound ^TOP^

A remote device has established an ACL link to the local device.

For this event, the eventData field contains the following field:

BtLibDeviceAddressType bdAddr;

This BtLibDeviceAddressType contains the address of the remote device.

btLibManagementEventAclConnectOutbound ^TOP^

An ACL link has been established with a remote device.

If the status field contains btLibErrNoError, the ACL link is connected, and the remote device address can be found in the eventData field. Otherwise the connection failed and the status field indicates the reason for the failure. See Management Event Status Codes for more information.

For this event, the eventData field contains the following field:

BtLibDeviceAddressType bdAddr;

This BtLibDeviceAddressType contains the address of the remote device.

This event can result from calling BtLibLinkConnect().

btLibManagementEventAclDisconnect ^TOP^

An ACL link has been disconnected. The status field indicates the reason the link was disconnected. See Management Event Status Codes.

For this event, the eventData field contains the following field:

BtLibDeviceAddressType bdAddr;

This BtLibDeviceAddressType contain the address of the disconnected device.

This event can result from calling BtLibLinkDisconnect() or BtLibPiconetDestroy().

btLibManagementEventAuthentication
Complete ^TOP^

The authentication of a remote device has completed.

For this event, the eventData field contains the following field:

BtLibDeviceAddressType bdAddr;

This BtLibDeviceAddressType contains the address of the remote device.

If the authentication is successful, the status field contains btLibErrNoError. If the user cancels the passkey request, the status field contains btLibErrCanceled. Otherwise, the status field indicates the reason the authentication failed. See Management Event Status Codes.

This event can result from calling BtLibLinkSetState().

btLibManagementEventEncryptionChange ^TOP^

Purpose

Encryption for a link has been enabled or disabled.

For this event, the eventData field contains the following structure:

Prototype

struct {
  BtLibDeviceAddressType bdAddr;
  Boolean enabled;
} encryptionChange;

Fields

bdAddr: A BtLibDeviceAddressType containing the address of the remote device.
enabled: true when encryption for the link has been enabled; false otherwise.

This event can result from calling BtLibLinkSetState().

btLibManagementEventInquiryCanceled ^TOP^

The device inquiry has been canceled because the application called BtLibCancelInquiry().

btLibManagementEventInquiryComplete ^TOP^

The device inquiry started with the BtLibStartInquiry() function has completed.

btLibManagementEventInquiryResult ^TOP^

Purpose

A remote device has responded to an inquiry that was started with the BtLibStartInquiry() function.

For this event, the eventData field contains the following structure:

Prototype

struct {
  BtLibDeviceAddressType bdAddr;
  BtLibClassOfDeviceType classOfDevice;
} inquiryResult;

Fields

bdAddr: A BtLibDeviceAddressType containing the address of the remote device.
classOfDevice: A BtLibClassOfDeviceType representing the class of the remote device.

btLibManagementEventLocalNameChange ^TOP^

Purpose

The user-friendly name of the local device has changed.

For this event, the eventData field contains the following structure:

Prototype

struct {
  BtLibDeviceAddressType bdAddr;
  BtLibFriendlyNameType name;
} nameResult;

Fields

bdAddr: A BtLibDeviceAddressType containing the address of the local device.
name: A BtLibFriendlyNameType containing the new name.

This event can result from calling BtLibOpen().

btLibManagementEventModeChange ^TOP^

Purpose

A slave has changed its mode. A slave can be in active, sniff, hold, or park mode.

For this event, the eventData field contains the following structure:

Prototype

struct {
  BtLibDeviceAddressType bdAddr;
  BtLibLinkModeEnum curMode;
  UInt16 interval;
} modeChange;

Fields

bdAddr: A BtLibDeviceAddressType containing the address of the remote device.
curMode: A BtLibLinkModeEnum indicating the new mode of remote device
interval: The time in units of 0.625 ms the remote device will stay in the new mode, if applicable. The time period is a standard time period in the Bluetooth specification.

BtLibLinkModeEnum

Purpose

The BtLibLinkModeEnum enum specifies the modes a slave can have. According to the Specification of the Bluetooth System, a slave can be in active, sniff, hold, or park mode. However, the Bluetooth library only supports the hold and active modes.

Prototype

typedef enum {
  btLibSniffMode,
  btLibHoldMode,
  btLibParkMode,
  btLibActiveMode
} BtLibLinkModeEnum;

Constants

btLibActiveMode: The slave is active.
btLibHoldMode: The slave is in hold mode.
btLibParkMode: The slave is in park mode. This mode is not currently supported.
btLibSniffMode: The slave is in sniff mode. This mode is not currently supported.

btLibManagementEventNameResult ^TOP^

Purpose

A remote device name request has completed. If the status field is btLibErrNoError, the name is available. Otherwise, the name request failed, and the status field indicates the reason for the failure. See Management Event Status Codes.

For this event, the eventData field contains the following structure:

Prototype

struct {
  BtLibDeviceAddressType bdAddr;
  BtLibFriendlyNameType name;
} nameResult;

Fields

bdAddr: A BtLibDeviceAddressType containing the address of the remote device.
name: A BtLibFriendlyNameType containing the name of the remote device.

The BtLibGetRemoteDeviceName() function is used to start a remote device name request.

btLibManagementEventPairingComplete ^TOP^

Pairing has successfully completed and the link is authenticated. The status code for this event is set to btLibErrNoError, indicating that the link key was stored successfully.

If pairing fails, no event is sent (there is no event sent by the radio module indicating failure).

btLibManagementEventPasskeyRequest ^TOP^

A remote device has requested a passkey. Your application does not have to respond to this request—the Bluetooth library automatically handles it.

For this event, the eventData field contains the following field:

BtLibDeviceAddressType bdAddr;

This BtLibDeviceAddressType contains the address of the remote device.

Because a passkey can be requested during or after a link is established, consider disabling any failure timers while the passkey dialog is up. The btLibManagementEventPasskeyRequestComplete event signals the completion of the passkey entry.

btLibManagementEventPasskeyRequestComplete ^TOP^

A passkey request has been processed. The status code for this event is set to btLibErrNoError if the passkey was entered or btLibErrCanceled if passkey entry was cancelled. Note that this event does not tell you that the authentication completed.

btLibManagementEventPiconetCreated ^TOP^

The piconet has been created. This event can result from calling BtLibPiconetCreate().

btLibManagementEventPiconetDestroyed ^TOP^

The piconet has been destroyed. This event can result from calling BtLibPiconetDestroy().

btLibManagementEventRadioState ^TOP^

This event is generated when the Bluetooth radio changes state. The radio changes state when the radio is disconnected, the power is turned on or off, the radio resets, or the radio fails to initialize. The status code for this event explains why the event gets generated.

Status Codes

btLibErrRadioInitialized: The Bluetooth radio has initialized successfully. You can now call management functions.
btLibErrRadioInitFailed: The Bluetooth radio failed to initialize. The application can assume all pending Bluetooth operations have failed. However, some pending operations will still generate events and modify memory supplied by the application.; To try to initialize the radio again, you need to close the library and reopen it.
btLibErrRadioFatal: A fatal radio error occurred. This usually signifies that the host has lost contact with the radio, for example, when the user disconnects the radio, or the device turns off. The application can assume that all pending operations have failed. However, some pending operations will still generate events and modify memory supplied by the application.; When a fatal radio error occurs, the Bluetooth stack resets the radio and tries once to reinitialize it, which generates another btLibManagementEventRadioState event with a status code of btLibErrRadioInitialized, or btLibErrRadioInitFailed depending on whether or not the initialization succeeded.
btLibErrRadioSleepWake: The radio was reset because the device went to sleep. The application can assume all pending operations have failed. However, some pending operations will still generate events and modify memory supplied by the application.; The Bluetooth stack resets the radio and tries once to reinitialize it, which generates another btLibManagementEventRadioState event with a status code of btLibErrRadioInitialized, or btLibErrRadioInitFailed depending on whether or not the initialization succeeded.

This event can result from calling BtLibOpen().

btLibManagementEventRoleChange ^TOP^

Purpose

The master and slave devices for a link have switched roles.

For this event, the eventData field contains the following structure:

Prototype

struct {
  BtLibDeviceAddressType bdAddr;
  BtLibConnectionRoleEnum newRole;
} roleChange;

Fields

bdAddr: A BtLibDeviceAddressType containing the address of the remote device.
newRole: A BtLibConnectionRoleEnum representing the new role of the local device.

Management Event Status Codes ^TOP^

When a management event is generated, the status field of the associated BtLibManagementEventType provides information about why the event occurred. The following status codes can occur with a management event.

btLibErrNoError: Success.
btLibMeStatusAuthenticateFailure: Authentication failure
btLibMeStatusCommandDisallowed: Command disallowed
btLibMeStatusConnnectionTimeout: Connection timeout
btLibMeStatusHardwareFailure: Hardware Failure
btLibMeStatusHostTimeout: Host timeout
btLibMeStatusInvalidHciParam: Invalid HCI command parameters
btLibMeStatusInvalidLmpParam: Invalid LMP Parameters
btLibMeStatusLimitedResources: Host rejected due to limited resources
btLibMeStatusLmpResponseTimeout
btLibMeStatusLmpTransdCollision
btLibMeStatusLmpPduNotAllowed
btLibMeStatusLocalTerminated: Terminated by local host
btLibMeStatusLowResources: Other end terminated due to low resources
btLibMeStatusMaxAclConnections: Max number of ACL connections to a device
btLibMeStatusMaxConnections: Max number of connections
btLibMeStatusMaxScoConnections: Max number of SCO connections to a device
btLibMeStatusMemoryFull: Memory full
btLibMeStatusMissingKey: Missing key
btLibMeStatusNoConnection: No connection
btLibMeStatusPageTimeout: Page timeout
btLibMeStatusPairingNotAllowed: Pairing not allowed
btLibMeStatusPersonalDevice: Host rejected (remote is personal device)
btLibMeStatusPowerOff: Other end terminated (about to power off)
btLibMeStatusRepeatedAttempts: Repeated attempts
btLibMeStatusRoleChangeNotAllowed: Change not allowed
btLibMeStatusScoAirModeRejected: SCO Air Mode Rejected
btLibMeStatusScoIntervalRejected: SCO Interval Rejected
btLibMeStatusScoOffsetRejected: SCO Offset Rejected
btLibMeStatusSecurityError: Host rejected due to security reasons
btLibMeStatusUnknownHciCommand: Unknown HCI Command
btLibMeStatusUnknownLmpPDU: Unknown LMP PDU
btLibMeStatusUnspecifiedError: Unspecified Error
btLibMeStatusUnsupportedFeature: Unsupported feature or parameter value
btLibMeStatusUnsupportedLmpParam: Unsupported LMP Parameter Value
btLibMeStatusUnsupportedRemote: Unsupported Remote Feature
btLibMeStatusUserTerminated: Other end terminated (user)

Library Management Functions ^TOP^

This section describes the general Bluetooth library management functions.

BtLibClose Function ^TOP^

Purpose

Close the Bluetooth library.

Declared In

BtLib.h

Prototype

Err BtLibClose (
   UInt16 btLibRefNum
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.

Returns

Returns btLibErrNoError if the library successfully closes. Returns btLibErrNotOpen if the referenced Bluetooth library was not open.

Comments

Applications must call this function when they no longer need the Bluetooth library. If the Bluetooth library open count is one, this function closes existing connections, saves the current accessibility mode, sets the accessible mode according to the preferences panel, and shuts down the library. If the Bluetooth library open count is greater than one, this function decrements the open count.

BtLibOpen Function ^TOP^

Purpose

Open and initialize the Bluetooth library.

Declared In

BtLib.h

Prototype

Err BtLibOpen (
   UInt16 btLibRefNum,
   Boolean allowStackToFail
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ allowStackToFail: If true, opens the library even if the stack or radio fails to initialize. Otherwise, does not open the library if the stack or radio fails to initialize.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrAlreadyOpen: This status code is not really an error. It is returned if the library was already open. In this case, the open count is incremented.
btLibErrInUseByService: The library is currently in use by a Bluetooth service.
btLibErrOutOfMemory: Not enough memory available to open the library.
btLibErrRadioInitFailed: The Bluetooth stack or radio could not be initialized. If allowStackToFail is true, the library still opens after this error occurs.

Applications must call this function before using the Bluetooth library. If the Bluetooth library is not already open, BtLibOpen() opens the library, initializes it, and starts up the protocol stack component of the library. Otherwise it increments its open count.

The allowStackToFail parameter allows the library to be opened even if the Bluetooth stack or radio fails to initialize. It is useful for applications that only want to use the Bluetooth library's utility functions but not the radio. However, any application that needs to communicate with the radio must set allowStackToFail to false.

Once you've opened the Bluetooth library, you can then register your Bluetooth event handler by calling BtLibRegisterManagementNotification(). Once you've done that, your application will begin receiving events.

This function generates three events: a btLibManagementEventRadioState event with a status of btLibErrRadioInitialized, a btLibManagementEventLocalNameChange event indicating the local name of the device, and a btLibManagementEventAccessibilityChange event indicating the accessibility of the device.

Your application will not miss these events between calling BtLibOpen() and your call to the BtLibRegisterManagementNotification() function because the Bluetooth stack is driven by the application's event loop; events are only sent to your application during the event loop.

Management Functions ^TOP^

The management functions handle the lower levels of the Bluetooth specification, specifically the radio, baseband, and Link Manager Protocol specifications. These functions perform tasks that include discovering devices, working with Asynchronous Connectionless (ACL) links and piconets, and maintaining global settings for the Bluetooth library.

BtLibCancelInquiry Function ^TOP^

Purpose

Cancel a Bluetooth inquiry in process.

Declared In

BtLib.h

Prototype

Err BtLibCancelInquiry (
   UInt16 btLibRefNum
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.

Returns

Returns one of the following values:

btLibErrNoError: The inquiry process was canceled before it started.
btLibErrPending: The cancellation is pending. When it succeeds, notification will be provided through a management callback event.
btLibErrInProgress: The inquiry is already being canceled.
btLibErrNotInProgress: No inquiry is in progress to be canceled.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

The function cancels inquiries initiated by BtLibStartInquiry(). The btLibManagementEventInquiryCanceled callback event indicates that the cancellation has completed.

A Bluetooth discovery initiated using either BtLibDiscoverSingleDevice() or BtLibDiscoverMultipleDevices() cannot be canceled with this function. Only the user can cancel these inquiries by tapping the Cancel button.

BtLibDiscoverMultipleDevices Function ^TOP^

Purpose

Discover all available devices, present them in the user interface, and allow the user to select one or more of these devices.

Declared In

BtLib.h

Prototype

Err BtLibDiscoverMultipleDevices (
   UInt16 btLibRefNum,
   Char *instructionTxt,
   Char *buttonTxt,
   BtLibClassOfDeviceType *deviceFilterList,
   UInt8 deviceFilterListLen,
   UInt8 *numDevicesSelected,
   Boolean addressAsName,
   Boolean showLastList
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ instructionTxt: Text displayed at the top of the selection box. Pass NULL to display the default text. The default text is "Select one or more devices:"
→ buttonTxt: Text for the OK button. Pass NULL to display the default text. The default button text is "OK"
→ deviceFilterList: Array of BtLibClassOfDeviceTypes. This function presents to the user only the remote devices whose class matches a class in this list. If deviceFilterList is NULL, this function presents to the user all discovered devices.
→ deviceFilterListLen: Number of elements in deviceFilterList.
← numDevicesSelected: Number of selected devices. To obtain the actual device list, use the BtLibGetSelectedDevices function.
→ addressAsName: If true, display the Bluetooth addresses of the remote devices instead of their names. This option is available for debugging purposes.
→ showLastList: If true, causes all other parameters to be ignored and displays the same list as the previous call to BtLibDiscoverMultipleDevices.

Returns

Returns one of the following values:

btLibErrNoError: Success
btLibErrCanceled: User canceled discovery.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

This blocking call performs a full discovery for an application, including name and feature retrieval and testing. This function takes over the UI and presents a choice box to the user, allowing the user to select multiple devices from the list of devices that were discovered. This function does not return until the user chooses one or more devices, or cancels.

Setting the showLastList parameter to true allows you to present to the user the list of devices displayed in the previous call to BtLibDiscoverMultipleDevices or BtLibDiscoverSingleDevice(). This feature can be useful because a full discovery process takes approximately ten seconds. The cached device list remains valid even after you close the library, allowing other Bluetooth applications to use it.

Note that BtLibStartInquiry() overwrites the cached device list. If you are using the showLastList feature, you should avoid calling BtLibStartInquiry between calls to BtLibDiscoverMultipleDevices or BtLibDiscoverSingleDevice.

Use BtLibGetSelectedDevices() to retrieve the list of devices that the user selected.

BtLibDiscoverSingleDevice Function ^TOP^

Purpose

Discover all available devices, present them in the user interface, and allow the user to select one of these devices.

Declared In

BtLib.h

Prototype

Err BtLibDiscoverSingleDevice (
   UInt16 btLibRefNum,
   Char *instructionTxt,
   BtLibClassOfDeviceType *deviceFilterList,
   UInt8 deviceFilterListLen,
   BtLibDeviceAddressType *selectedDeviceP,
   Boolean addressAsName,
   Boolean showLastList
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ instructionTxt: Text displayed at the top of the selection box. Pass NULL to display the default text. The default text is "Select a device:"
→ deviceFilterList: Array of BtLibClassOfDeviceTypes. This function displays only the remote devices whose class matches a class in this list. If deviceFilterList is NULL, this function displays all discovered devices.
→ deviceFilterListLen: Number of elements in deviceFilterList.
← selectedDeviceP: Pointer to a BtLibDeviceAddressType where this function stores the address of the device the user selects. You need to allocate this space before calling this function.
→ addressAsName: If true, display the Bluetooth addresses of the remote devices instead of their names. This option is available for debugging purposes.
→ showLastList: If true, causes all other parameters to be ignored and displays the same list as the previous call to BtLibDiscoverSingleDevice.

Returns

Returns one of the following values:

btLibErrNoError: Success
btLibErrCanceled: User canceled the discovery.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

This blocking call performs a full discovery for an application, including name and feature retrieval and testing. This function takes over the UI and presents a choice box to the user, allowing the user to select a device from the list of devices that were discovered. This function does not return until the user chooses a device or cancels.

Setting the showLastList parameter to true allows you to present to the user the list of devices displayed in the previous call to BtLibDiscoverSingleDevice or BtLibDiscoverMultipleDevices(). This feature can be useful because a full discovery process takes approximately ten seconds. The cached device list remains valid even after you close the library, allowing other Bluetooth applications to use it.

BtLibGetGeneralPreference Function ^TOP^

Purpose

Get one of the general management preferences.

Declared In

BtLib.h

Prototype

Err BtLibGetGeneralPreference (
   UInt16 btLibRefNum,
   BtLibGeneralPrefEnum pref,
   void *prefValue,
   UInt16 prefValueSize
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ pref: General preference to get.
← prefValue: Pointer to a buffer to hold the value of the preference. You must allocate this buffer. This parameter must not be NULL.
→ prefValueSize: Size, in bytes, of the prefValue buffer. You must set this size so it matches the size of the retrieved preference.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: One or more parameters is invalid. Be sure that the prefValueSize parameter matches the size of the preference value.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

Specify the preference with a member of the BtLibGeneralPreferenceEnum.

BtLibGeneralPreferenceEnum

The BtLibGeneralPreferenceEnum enum specifies the general preferences that can be accessed using the BtLibSetGeneralPreference() and BtLibGetGeneralPreference() functions.

Prototype

typedef enum {
  btLibPref_Name,
  btLibPref_UnconnectedAccessible,
  btLibPref_CurrentAccessible,
  btLibPref_LocalClassOfDevice,
  btLibPref_LocalDeviceAddress
} BtLibGeneralPrefEnum;

Constants

btLibPref_CurrentAccessible: This preference is a BtLibAccessibleModeEnum indicating the current accessibility mode of the local device.
btLibPref_LocalClassOfDevice: This preference is a BtLibClassOfDeviceType indicating the class of the local device. You should never set this preference.
btLibPref_Name: This preference is a BtLibFriendlyNameType containing the user-friendly name of the local device. If you retrieve this preference, you also need to allocate a buffer and set the BtLibFriendlyNameType's name and nameLength fields to the buffer pointer and buffer length, respectively.; You should never set this preference.
btLibPref_UnconnectedAccessible: This preference is a BtLibAccessibleModeEnum indicating the accessibility mode of the local device when it is unconnected. You should never set this preference.

BtLibGetRemoteDeviceName Function ^TOP^

Purpose

Get the name of the remote device with the specified address.

Declared In

BtLib.h

Prototype

Err BtLibGetRemoteDeviceName (
   UInt16 btLibRefNum,
   BtLibDeviceAddressTypePtr remoteDeviceP,
   BtLibFriendlyNameType *nameP,
   BtLibGetNameEnum retrievalMethod
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ remoteDeviceP: Pointer to a BtLibDeviceAddressType containing the address of the device whose name is desired.
↔ nameP: Pointer to a BtLibFriendlyNameType structure in which to store the results of the lookup. You must allocate this structure and the name buffer it points to. You also must specify the size of the buffer in the nameLength field of the structure. When the function returns, ignore the nameLength field and use StrLen to obtain the actual length of the name. This parameter must not be NULL.
→ retrievalMethod: Method used to retrieve the user-friendly remote device name. See BtLibGetNameEnum.

Returns

Returns one of the following values:

btLibErrNoError: The name structure was successfully retrieved from the cache. No notification event will be generated.
btLibErrBusy: There is already a name request pending.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrPending: The results will be returned through a notification.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

The Bluetooth library maintains a cache of 50 device names. If the retrievalMethod parameter is btLibCachedThenRemote, this function first checks the cache for a name. If the name is in the cache, the value is returned immediately in the nameP parameter. If the name is not in the cache, the function queries the remote device for its name, forming a temporary ACL connection if one is not already in place. In this case, the function returns btLibErrPending and generates a btLibManagementEventNameResult event when the name is available.

Other values of the retrievalMethod parameter can instruct this function to look for the name only in the cache or only on the remote device. See BtLibGetNameEnum for more information.

BtLibGetNameEnum

The BtLibGetNameEnum enum specifies whether to retrieve a device name from the cache, the remote device, or both.

Prototype

typedef enum {
  btLibCachedThenRemote,
  btLibCachedOnly,
  btLibRemoteOnly
} BtLibGetNameEnum;

Constants

btLibCachedOnly: Look for a name in the cache. If the name is not in the cache, fail.
btLibCachedThenRemote: Look for a name in the cache. If the name is not in the cache, ask the remote device.
btLibRemoteOnly: Ignore any cached names and ask the remote device for its name.

BtLibGetSelectedDevices Function ^TOP^

Purpose

Get the list of devices selected during the last call to BtLibDiscoverMultipleDevices().

Declared In

BtLib.h

Prototype

Err BtLibGetSelectedDevices (
   UInt16 btLibRefNum,
   BtLibDeviceAddressType *selectedDeviceArray,
   UInt8 arraySize,
   UInt8 *numDevicesReturned
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
selectedDeviceArray: Array into which the results of the BtLibDiscoverMultipleDevices() function should be placed. You must allocate this array of BtLibDeviceAddressTypes.
→ arraySize: Number of elements in the selectedDeviceArray you allocated.
← numDevicesReturned: Number of results placed in selectedDeviceArray.

Returns

Returns btLibErrNoError if the query is successful. Returns btLibErrNotOpen if the referenced Bluetooth library is not open or btLibErrStackNotOpen if the Bluetooth stack failed to initialize when the library was opened.

Comments

No callback events.

BtLibLinkConnect Function ^TOP^

Purpose

Create a Bluetooth Asynchronous Connectionless (ACL) link.

Declared In

BtLib.h

Prototype

Err BtLibLinkConnect (
   UInt16 btLibRefNum,
   BtLibDeviceAddressTypePtr remoteDeviceP
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ remoteDeviceP: Pointer to the a BtLibDeviceAddressType containing the address of the remote device.

Returns

Returns one of the following values:

btLibErrPending: The results will be returned through a callback event.
btLibErrAlreadyConnected: The device is already in a pre-existing connection and cannot create a new connection.
btLibErrBluetoothOff: The Bluetooth radio is off. The user can turn the radio on and off with a setting in the preferences panel.
btLibErrBusy: A piconet is currently being created or destroyed.
btlibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.
btLibErrTooMany: Cannot create another ACL link because the maximum allowed number has already been reached.

Comments

An ACL link is a packet-switched physical level connection between two devices that is needed before the devices can form a RFCOMM or L2CAP connection.

When the connection is established or if it fails to be established, the btLibManagementEventAclConnectOutbound event is generated.

BtLibLinkDisconnect Function ^TOP^

Purpose

Disconnect an existing ACL Link.

Declared In

BtLib.h

Prototype

Err BtLibLinkDisconnect (
   UInt16 btLibRefNum,
   BtLibDeviceAddressTypePtr remoteDeviceP
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ remoteDeviceP: Pointer to a BtLibDeviceAddressType containing the address of the remote device.

Returns

Returns one of the following values:

btLibErrNoError: The connection attempt was canceled before it started. No event is generated.
btLibErrPending: When the link actually disconnects, a btLibManagementEventAclDisconnect callback event is generated.
btLibErrBusy: Can't disconnect the link because the piconet is being destroyed.
btLibErrNoConnection: No link to the specified device exists.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

When the link disconnects, a btLibManagementEventAclDisconnect event is generated.

BtLibLinkGetState Function ^TOP^

Purpose

Get the state of an ACL link.

Declared In

BtLib.h

Prototype

Err BtLibLinkGetState(
   UInt16 btLibRefNum,
   BtLibDeviceAddressTypePtr remoteDeviceP,
   BtLibLinkPrefsEnum pref,
   void *linkState,
   UInt16 linkStateSize
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ remoteDeviceP: Pointer to a BtLibDeviceAddressType containing the address of the remote device. This address identifies the ACL link.
→ pref: Link preference to retrieve. See BtLibLinkPrefsEnum.
← linkState: Pointer to a buffer to store the value of the preference. You must allocate this buffer. This parameter must not be NULL. See BtLibLinkPrefsEnum for more information.
→ linkStateSize: Size, in bytes, of linkState buffer. This size must match the size of the retrieved preference.

Returns

Returns one of the following values:

btLibErrNoError: Success. The linkState variable has been filled in.
btLibErrNoAclLink: No link to the specified remote device exists.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: The linkStateSize parameter is not same as the size of the preference value.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

See the BtLibLinkSetState() function description for a list of the link states preferences.

BtLibLinkSetState Function ^TOP^

Purpose

Set the state of an ACL link

Declared In

BtLib.h

Prototype

Err BtLibLinkSetState (
   UInt16 btLibRefNum,
   BtLibDeviceAddressTypePtr remoteDeviceP,
   BtLibLinkPrefsEnum pref,
   void *linkState,
   UInt16 linkStateSize
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ remoteDeviceP: The address of the remote device. This address identifies the ACL link.
→ pref: Link preference to set. See BtLibLinkPrefsEnum.
→ linkState: Pointer to the value of the preference. See BtLibLinkPrefsEnum.
→ linkStateSize: Size, in bytes, of the linkState value.

Returns

Returns one of the following values:

btLibErrPending: The results will be returned through a callback event.
btLibErrFailed: An attempt was made to encrypt a link before authenticating it.
btLibErrNoAclLink: No link to the specified remote device exists.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: The preference cannot be set or linkStateSize is invalid.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

Applications use this function to set the state of an ACL link. This function may generate events depending on the preference you change. The btLibManagementEventAuthentication Complete event indicates the link authentication has completed. The btLibManagementEventEncryptionChange indicates that the encryption has been enabled or disabled.

BtLibLinkPrefsEnum

The BtLibLinkPrefsEnum enum specifies the link state preferences that can be accessed with the BtLibLinkSetState() and BtLibLinkGetState() functions.

Prototype

typedef enum {
  btLibLinkPref_Authenticated,
  btLibLinkPref_Encrypted,
  btLibLinkPref_LinkRole
} BtLibLinkPrefsEnum;

Constants

btLibLinkPref_Authenticated: This preference is a Boolean and indicates whether the link has been authenticated or not. The linkState and linkStateSize parameters are ignored.
btLibLinkPref_Encrypted: This preference is a Boolean and indicates whether the link is encrypted or not.
btLibLinkPref_LinkRole: This preference is a BtLibConnectionRoleEnum and indicates whether the remote device is a master or a slave. You cannot set this preference but you can get its value.

BtLibPiconetCreate Function ^TOP^

Purpose

Create a piconet or reconfigure an existing piconet so the local device is the master.

Declared In

BtLib.h

Prototype

Err BtLibPiconetCreate (
   UInt16 btLibRefNum,
   Boolean unlockInbound,
   Boolean discoverable
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ unlockInbound: If true, the piconet accepts inbound connections. Otherwise, the piconet only allows outbound connections.
→ discoverable: If true, configures the radio to be discoverable. In other words, the radio responds to inquiries. If false, configures the radio to be only connectable. In other words, only devices that know the radio's Bluetooth device address can connect to it. This parameter is ignored if unlockInbound is false.

Returns

Returns one of the following values:

btLibErrNoError: Successfully created the piconet with the local device as the master. No callback event is generated.
btLibErrPending: An existing ACL link needs to switch roles before this operation can complete.
btLibErrFailed: A piconet already exists.
btLibErrInProgress: Another piconet is currently being created.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

If the accessibility of the radio changes due to this operation, a btLibManagementEventAccessibilityChange event is generated. When the piconet is created, or if the piconet fails to be created, a btLibManagementEventPiconetCreated event is generated. The status field of the BtLibManagementEventType structure accompanying the event indicates whether the piconet was created or not.

BtLibPiconetDestroy Function ^TOP^

Purpose

Destroy the piconet by disconnecting links to all devices and removing all restrictions on whether the local device is a master or a slave.

Declared In

BtLib.h

Prototype

Err BtLibPiconetDestroy (
   UInt16 btLibRefNum
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.

Returns

Returns one of the following values:

btLibErrNoError: Successfully destroyed the piconet. A btLibManagementEventPiconetDestroyed event is not generated.
btLibErrPending: The piconet is being destroyed, and a btLibManagementEventPiconetDestroyed event will be generated when the operation succeeds or fails.
btLibErrBusy: The piconet is already in the process of being destroyed.
btLibErrNoPiconet: No piconet exists to be destroyed.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

A btLibManagementEventAclDisconnect event is generated for each ACL link that is disconnected. When the piconet is successfully destroyed or fails to be destroyed, a btLibManagementEventPiconetDestroyed is generated. The status field of the BtLibManagementEventType structure accompanying the event indicates whether the piconet was destroyed or not.

BtLibPiconetLockInbound Function ^TOP^

Purpose

Prevent remote devices from creating ACL links into the piconet.

Declared In

BtLib.h

Prototype

Err BtLibPiconetLockInbound (
   UInt16 btLibRefNum
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrBusy: The piconet is in the process of being destroyed.
btLibErrNoPiconet: No piconet exists.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

After locking inbound connections, outbound connections are still allowed. Locking inbound connections maximizes the bandwidth for members of the piconet to transmit data to each other.

BtLibPiconetUnlockInbound Function ^TOP^

Purpose

Allow remote devices to create ACL links into the piconet.

Declared In

BtLib.h

Prototype

Err BtLibPiconetUnlockInbound (
   UInt16 btLibRefNum,
   Boolean discoverable
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ discoverable: If true, configures the radio to be discoverable. In other words, the radio responds to inquiries. If false, configures the radio to be only connectable. In other words, only devices that know the radio's Bluetooth device address can connect to it.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrBusy: The piconet is in the process of being destroyed.
btLibErrNoPiconet: No piconet exists.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

Allowing inbound connections lowers the bandwidth available to transmit data between members of the piconet because the radio must periodically scan for incoming links.

BtLibRegisterManagementNotification Function ^TOP^

Purpose

Declared In

BtLib.h

Prototype

Err BtLibRegisterManagementNotification (
   UInt16 btLibRefNum,
   BtLibManagementProcPtr callbackP,
   UInt32 refCon
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ callbackP: Pointer to a callback procedure to register. This pointer must not be NULL. See BtLibManagementCallback() for more information.
→ refCon: Application-defined data to pass to the event handler.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrAlreadyRegistered: The callback has already been registered with the management entity.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: One or more parameters is invalid.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.
btLibErrTooMany: There is no space available to store the callback. The management entity allows a maximum of 16 callbacks to be registered at a time.

Comments

The management functions are asynchronous. That is, they return immediately and generate events when the task actually completes at a later time. To handle these events, you need to define a callback function with the same prototype as BtLibManagementCallback(). Then you need to register your callback function using BtLibRegisterManagementNotification. For examples of the callback events your callback function needs to handle, see the Management Callback Events section.

Applications should unregister their management callbacks before closing the Bluetooth library to prevent the callback table from overflowing. The callback table holds a maximum of 16 entries.

BtLibSetGeneralPreference Function ^TOP^

Purpose

Set one of the general management preferences.

Declared In

BtLib.h

Prototype

Err BtLibSetGeneralPreference (
   UInt16 btLibRefNum,
   BtLibGeneralPrefEnum pref,
   void *prefValue,
   UInt16 prefValueSize
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ pref: General preference to set. See BtLibGeneralPreferenceEnum.
→ prefValue: Pointer to the value of the preference. This parameter must not be NULL. See BtLibGeneralPreferenceEnum.
→ prefValueSize: Size, in bytes, of prefValue.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrPending: The results will be returned through a notification.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: One or more parameters is invalid. Be sure that prefValueSize matches the size of the preference value.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

See the BtLibGetGeneralPreference() function description for a list of the preferences.

This function may generate events depending on the preference you change. The btLibManagementEventAccessibilityChange event indicates that the accessibility of the local device has changed.

BtLibStartInquiry Function ^TOP^

Purpose

Start a Bluetooth inquiry.

Declared In

BtLib.h

Prototype

Err BtLibStartInquiry (
   UInt16 btLibRefNum,
   UInt8 timeout,
   UInt8 maxResp
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ timeout: Time, in seconds, this inquiry is allowed to take. If the inquiry does not complete within this time, it is canceled. The actual time is rounded to the nearest multiple of 1.28 seconds. If you specify a timeout period larger than 60 seconds, this function acts as if you specified a timeout period of 60 seconds. If this parameter is 0, the timeout period defaults to 10.24 seconds as specified in the Generic Access Profile.
→ maxResp: Maximum number of responses the inquiry accepts. Responses are not guaranteed to be unique.

Returns

Returns one of the following values:

btLibErrPending: The results will be returned through callback events.
btLibErrBluetoothOff: The Bluetooth radio is off. The user can turn the radio on and off with a setting in the preferences panel.
btLibErrInProgress: Another inquiry is already in progress.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

The function performs a low-level Bluetooth inquiry, as opposed to a full device discovery. Specifically, inquiries started with this function only return the Bluetooth address and the class of the discovered device. This function does not have a user interface.

Every time a device is discovered, a btLibManagementEventInquiryResult callback event is generated. When the inquiry is complete, a btLibManagementEventInquiryComplete callback event is generated. If the application calls BtLibCancelInquiry(), a btLibManagementEventInquiryCanceled callback event is generated.

BtLibUnregisterManagementNotification Function ^TOP^

Purpose

Unregister a previously registered management callback.

Declared In

BtLib.h

Prototype

Err BtLibUnregisterManagementNotification (
   UInt16 btLibRefNum,
   BtLibManagementProcPtr callbackP
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ callbackP: Pointer to the callback procedure to unregister. This pointer must not be NULL.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrError: The callback referenced by callbackP has not been registered.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: One or more parameters are invalid.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

Applications should unregister their management callbacks before closing the library to prevent the callback table from overflowing. The callback table holds a maximum of 16 entries.

Application-Defined Functions ^TOP^

This section describes the callback functions that handle management events. These functions are supplied by the developer and can be named anything.

BtLibManagementCallback Function ^TOP^

Purpose

Signal the result of a Bluetooth management event. When the event takes place, this callback function is called.

Declared In

BtLibTypes.h

Prototype

void (
   *BtLibManagementProcPtr
) (
   BtLibManagementEventType *mEvent,
   UInt32 refCon
)

Parameters

→ mEvent: BtLibManagementEventType structure containing the event parameters.
→ refCon: General purpose integer which you can use to hold application-specific information. When you register the callback with the BtLibRegisterManagementNotification() function, you can specify a value to pass to this parameter.

Returns

Returns nothing.

Comments

The event and status of the event are in the mEvent structure. See Management Callback Events for more information.

You must register this function using the BtLibRegisterManagementNotification() function before it starts receiving events.

82 Bluetooth Library: Management

Bluetooth Management Data Structures ^TOP^

BtLibAccessibleModeEnum Enum ^TOP^

Purpose

Prototype

Constants

BtLibClassOfDeviceType Typedef ^TOP^

Purpose

Prototype

Major Service Classes

Constants

Major Device Classes

Constants

Computer Minor Device Classes

Constants

Phone Minor Device Classes

Constants

LAN Access Point Minor Device Classes

Constants

Audio Minor Device Classes

Constants

Peripheral Minor Device Classes

Constants

Peripheral Minor Device Subclasses

Constants

Imaging Minor Device Classes

Constants

Masks

Constants

BtLibConnectionRoleEnum Enum ^TOP^

Purpose

Prototype

Constants

BtLibDeviceAddressType Struct ^TOP^

Purpose

Prototype

BtLibFriendlyNameType Struct ^TOP^

Purpose

Prototype

Fields

BtLibManagementEventType Struct ^TOP^

Purpose

Prototype

Fields

Management Callback Events ^TOP^

btLibManagementEventAccessibilityChange ^TOP^

btLibManagementEventAclConnectInbound ^TOP^

btLibManagementEventAclConnectOutbound ^TOP^

btLibManagementEventAclDisconnect ^TOP^

btLibManagementEventAuthenticationComplete ^TOP^

btLibManagementEventEncryptionChange ^TOP^

Purpose

Prototype

Fields

btLibManagementEventInquiryCanceled ^TOP^

btLibManagementEventInquiryComplete ^TOP^

btLibManagementEventInquiryResult ^TOP^

Purpose

Prototype

Fields

btLibManagementEventLocalNameChange ^TOP^

Purpose

Prototype

Fields

btLibManagementEventModeChange ^TOP^

Purpose

Prototype

Fields

BtLibLinkModeEnum

Purpose

Prototype

Constants

btLibManagementEventNameResult ^TOP^

Purpose

Prototype

Fields

btLibManagementEventPairingComplete ^TOP^

btLibManagementEventPasskeyRequest ^TOP^

btLibManagementEventPasskeyRequestComplete ^TOP^

btLibManagementEventPiconetCreated ^TOP^

btLibManagementEventAuthentication
Complete ^TOP^