Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

82    Bluetooth Library: Management

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

Part IV: Libraries

82 Bluetooth Library: Management

Bluetooth Management Data Structures

BtLibAccessibleModeEnum

BtLibClassOfDeviceType

BtLibConnectionRoleEnum

BtLibDeviceAddressType

BtLibFriendlyNameType

BtLibManagementEventType

Management Callback Events

btLibManagementEventAccessibilityChange

btLibManagementEventAclConnectInbound

btLibManagementEventAclConnectOutbound

btLibManagementEventAclDisconnect

btLibManagementEventAuthentication
Complete

btLibManagementEventEncryptionChange

btLibManagementEventInquiryCanceled

btLibManagementEventInquiryComplete

btLibManagementEventInquiryResult

btLibManagementEventLocalNameChange

btLibManagementEventModeChange

btLibManagementEventNameResult

btLibManagementEventPairingComplete

btLibManagementEventPasskeyRequest

btLibManagementEventPasskeyRequestComplete

btLibManagementEventPiconetCreated

btLibManagementEventPiconetDestroyed

btLibManagementEventRadioState

btLibManagementEventRoleChange

Management Event Status Codes

Library Management Functions

BtLibClose

BtLibOpen

Management Functions

BtLibCancelInquiry

BtLibDiscoverMultipleDevices

BtLibDiscoverSingleDevice

BtLibGetGeneralPreference

BtLibGetRemoteDeviceName

BtLibGetSelectedDevices

BtLibLinkConnect

BtLibLinkDisconnect

BtLibLinkGetState

BtLibLinkSetState

BtLibPiconetCreate

BtLibPiconetDestroy

BtLibPiconetLockInbound

BtLibPiconetUnlockInbound

BtLibRegisterManagementNotification

BtLibSetGeneralPreference

BtLibStartInquiry

BtLibUnregisterManagementNotification

Application-Defined Functions

BtLibManagementCallback

     

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 (
   UInt16btLibRefNum
)

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.

See Also

BtLibOpen()

BtLibOpen Function ^TOP^

Purpose

Open and initialize the Bluetooth library.

Declared In

BtLib.h

Prototype

Err BtLibOpen (
   UInt16btLibRefNum,
   BooleanallowStackToFail
)

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.

See Also

BtLibClose()

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 (
   UInt16btLibRefNum
)

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.

See Also

BtLibStartInquiry()

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 (
   UInt16btLibRefNum,
   Char*instructionTxt,
   Char*buttonTxt,
   BtLibClassOfDeviceType*deviceFilterList,
   UInt8deviceFilterListLen,
   UInt8*numDevicesSelected,
   BooleanaddressAsName,
   BooleanshowLastList
)

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.

See Also

BtLibGetSelectedDevices(), BtLibDiscoverSingleDevice()

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 (
   UInt16btLibRefNum,
   Char*instructionTxt,
   BtLibClassOfDeviceType*deviceFilterList,
   UInt8deviceFilterListLen,
   BtLibDeviceAddressType*selectedDeviceP,
   BooleanaddressAsName,
   BooleanshowLastList
)

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.

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

See Also

BtLibDiscoverMultipleDevices()

BtLibGetGeneralPreference Function ^TOP^

Purpose

Get one of the general management preferences.

Declared In

BtLib.h

Prototype

Err BtLibGetGeneralPreference (
   UInt16btLibRefNum,
   BtLibGeneralPrefEnumpref,
   void*prefValue,
   UInt16prefValueSize
)

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.

See Also

BtLibSetGeneralPreference()

BtLibGetRemoteDeviceName Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibGetRemoteDeviceName (
   UInt16btLibRefNum,
   BtLibDeviceAddressTypePtrremoteDeviceP,
   BtLibFriendlyNameType*nameP,
   BtLibGetNameEnumretrievalMethod
)

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 (
   UInt16btLibRefNum,
   BtLibDeviceAddressType*selectedDeviceArray,
   UInt8arraySize,
   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.

See Also

BtLibDiscoverMultipleDevices()

BtLibLinkConnect Function ^TOP^

Purpose

Create a Bluetooth Asynchronous Connectionless (ACL) link.

Declared In

BtLib.h

Prototype

Err BtLibLinkConnect (
   UInt16btLibRefNum,
   BtLibDeviceAddressTypePtrremoteDeviceP
)

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.

See Also

BtLibLinkDisconnect()

BtLibLinkDisconnect Function ^TOP^

Purpose

Disconnect an existing ACL Link.

Declared In

BtLib.h

Prototype

Err BtLibLinkDisconnect (
   UInt16btLibRefNum,
   BtLibDeviceAddressTypePtrremoteDeviceP
)

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.

See Also

BtLibLinkConnect()

BtLibLinkGetState Function ^TOP^

Purpose

Get the state of an ACL link.

Declared In

BtLib.h

Prototype

Err BtLibLinkGetState(
   UInt16btLibRefNum,
   BtLibDeviceAddressTypePtrremoteDeviceP,
   BtLibLinkPrefsEnumpref,
   void*linkState,
   UInt16linkStateSize
)

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.

See Also

BtLibLinkSetState()

BtLibLinkSetState Function ^TOP^

Purpose

Set the state of an ACL link

Declared In

BtLib.h

Prototype

Err BtLibLinkSetState (
   UInt16btLibRefNum,
   BtLibDeviceAddressTypePtrremoteDeviceP,
   BtLibLinkPrefsEnumpref,
   void*linkState,
   UInt16linkStateSize
)

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.

See Also

BtLibLinkGetState()

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 (
   UInt16btLibRefNum,
   BooleanunlockInbound,
   Booleandiscoverable
)

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.

See Also

BtLibPiconetDestroy(), BtLibPiconetUnlockInbound(), BtLibPiconetLockInbound()

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 (
   UInt16btLibRefNum
)

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.

See Also

BtLibPiconetCreate()

BtLibPiconetLockInbound Function ^TOP^

Purpose

Prevent remote devices from creating ACL links into the piconet.

Declared In

BtLib.h

Prototype

Err BtLibPiconetLockInbound (
   UInt16btLibRefNum
)

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.

See Also

BtLibPiconetUnlockInbound()

BtLibPiconetUnlockInbound Function ^TOP^

Purpose

Allow remote devices to create ACL links into the piconet.

Declared In

BtLib.h

Prototype

Err BtLibPiconetUnlockInbound (
   UInt16btLibRefNum,
   Booleandiscoverable
)

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.

See Also

BtLibPiconetLockInbound()

BtLibRegisterManagementNotification Function ^TOP^

Purpose

Register a callback function to process events generated by management functions.

Declared In

BtLib.h

Prototype

Err BtLibRegisterManagementNotification (
   UInt16btLibRefNum,
   BtLibManagementProcPtrcallbackP,
   UInt32refCon
)

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.

See Also

BtLibUnregisterManagementNotification()

BtLibSetGeneralPreference Function ^TOP^

Purpose

Set one of the general management preferences.

Declared In

BtLib.h

Prototype

Err BtLibSetGeneralPreference (
   UInt16btLibRefNum,
   BtLibGeneralPrefEnumpref,
   void*prefValue,
   UInt16prefValueSize
)

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.

See Also

BtLibGetGeneralPreference()

BtLibStartInquiry Function ^TOP^

Purpose

Start a Bluetooth inquiry.

Declared In

BtLib.h

Prototype

Err BtLibStartInquiry (
   UInt16btLibRefNum,
   UInt8timeout,
   UInt8maxResp
)

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.

See Also

BtLibCancelInquiry()

BtLibUnregisterManagementNotification Function ^TOP^

Purpose

Unregister a previously registered management callback.

Declared In

BtLib.h

Prototype

Err BtLibUnregisterManagementNotification (
   UInt16btLibRefNum,
   BtLibManagementProcPtrcallbackP
)

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.

See Also

BtLibRegisterManagementNotification()

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,
   UInt32refCon
)

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.