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

13    Bluetooth Reference

Low-Level Communications

Exploring Palm OS®

This chapter provides complete reference material to the Palm OS® Bluetooth Library, BtLib.

Bluetooth Structures and Types
Bluetooth Constants
Bluetooth Application Launch Codes
Bluetooth Functions and Macros

The header file BtLibTypes.h declares the types and constants that this chapter describes, while the file BtLib.h declares the functions and macros.

Bluetooth Structures and Types ^TOP^

BtLibClassOfDeviceType Typedef ^TOP^

Purpose

A bit pattern representing the class of device and the services it supports.

Declared In

BtLibTypes.h

Prototype

typedef uint32_t BtLibClassOfDeviceType

Comments

A device may 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 and Object Exchange services. Its major device class is Phone, and its minor device class is Cellular.

The Bluetooth Assigned Numbers specification defines a "Class of Device/Service" (CoD) value 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 CoD 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_ObjectTransfer |
   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.

Table 13.1  Major service classes

Constant

btLibCOD_Audio

btLibCOD_Capturing

btLibCOD_Information

btLibCOD_LimitedDiscoverableMode

btLibCOD_Networking

btLibCOD_ObjectTransfer

btLibCOD_Positioning

btLibCOD_Rendering

btLibCOD_Telephony

Major Device Classes

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

Table 13.2  Major device classes

Constant

btLibCOD_Major_Audio

btLibCOD_Major_Computer

btLibCOD_Major_Imaging

btLibCOD_Major_Lan_Access_Point

btLibCOD_Major_Misc

btLibCOD_Major_Peripheral

btLibCOD_Major_Phone

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.

Table 13.3  Computer minor device classes

Constant

btLibCOD_Minor_Comp_Desktop

btLibCOD_Minor_Comp_Handheld

btLibCOD_Minor_Comp_Laptop

btLibCOD_Minor_Comp_Palm

btLibCOD_Minor_Comp_Server

btLibCOD_Minor_Comp_Unclassified

Phone Minor Device Classes

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

Table 13.4  Phone minor device classes

Constant

btLibCOD_Minor_Phone_Unclassified

btLibCOD_Minor_Phone_Cellular

btLibCOD_Minor_Phone_Cordless

btLibCOD_Minor_Phone_ISDN

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.

Table 13.5  LAN access point minor device classes

Constant

Meaning

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.

Table 13.6  Audio minor device classes

Constant

btLibCOD_Minor_Audio_Unclassified

btLibCOD_Minor_Audio_Headset

btLibCOD_Minor_Audio_CamCorder

btLibCOD_Minor_Audio_CarAudio

btLibCOD_Minor_Audio_GameToy

btLibCOD_Minor_Audio_HandFree

btLibCOD_Minor_Audio_HeadPhone

btLibCOD_Minor_Audio_HifiAudio

btLibCOD_Minor_Audio_LoudSpeaker

btLibCOD_Minor_Audio_MicroPhone

btLibCOD_Minor_Audio_PortableAudio

btLibCOD_Minor_Audio_SetTopBox

btLibCOD_Minor_Audio_VCR

btLibCOD_Minor_Audio_VideoCamera

btLibCOD_Minor_Audio_VideoConf

btLibCOD_Minor_Audio_VideoDisplayAndLoudSpeaker

btLibCOD_Minor_Audio_VideoMonitor

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.

Table 13.7  Peripheral minor device classes

Constant

btLibCOD_Minor_Peripheral_CardReader

btLibCOD_Minor_Peripheral_Combo

btLibCOD_Minor_Peripheral_DigitizerTablet

btLibCOD_Minor_Peripheral_GamePad

btLibCOD_Minor_Peripheral_Joystick

btLibCOD_Minor_Peripheral_Keyboard

btLibCOD_Minor_Peripheral_Pointing

btLibCOD_Minor_Peripheral_RemoteControl

btLibCOD_Minor_Peripheral_Sensing

btLibCOD_Minor_Peripheral_Unclassified

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.

Table 13.8  Imaging minor device classes

Constant

btLibCOD_Minor_Imaging_Camera

btLibCOD_Minor_Imaging_Display

btLibCOD_Minor_Imaging_Printer

btLibCOD_Minor_Imaging_Scanner

btLibCOD_Minor_Imaging_Unclassified

Masks

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

Table 13.9  Masks

Constant

Meaning

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 BtLibDiscoverDevices() function. 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 BtLibDiscoverDevices() function. 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 BtLibDiscoverDevices() function. 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 BtLibDiscoverDevices() function. 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 BtLibDiscoverDevices() function. 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 BtLibDiscoverDevices() function. 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 BtLibDiscoverDevices() function. 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.

BtLibDeviceAddressType Struct ^TOP^

Purpose

Defines the address of a Bluetooth device.

Declared In

BtLibTypes.h

Prototype

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

Fields

address
btLibDeviceAddressSize byte long Bluetooth device address.

BtLibDeviceAddressTypePtr Typedef ^TOP^

Purpose

A pointer to a Bluetooth address.

Declared In

BtLibTypes.h

Prototype

typedef BtLibDeviceAddressType
      *BtLibDeviceAddressTypePtr

BtLibFriendlyNameType Struct ^TOP^

Purpose

Contains the user-friendly name of a device.

Declared In

BtLibTypes.h

Prototype

typedef struct BtLibFriendlyNameType {
   uint8_t nameLength;
   uint8_t name[btLibMaxDeviceNameLength];
} BtLibFriendlyNameType

Fields

nameLength
The length of the name, including the null terminator.
name
Buffer for the null-terminated device name.

Comments

The BtLibFriendlyNameType structure is used to get and set a device's friendly name.


NOTE: The nameLength field includes the name string's null terminator.

BtLibFriendlyNameTypePtr Typedef ^TOP^

Purpose

Defines a pointer to a friendly Bluetooth device name.

Declared In

BtLibTypes.h

Prototype

typedef BtLibFriendlyNameType
      *BtLibFriendlyNameTypePtr

BtLibL2CapChannelIdType Typedef ^TOP^

Purpose

Specifies an L2CAP channel ID.

Declared In

BtLibTypes.h

Prototype

typedef uint16_t BtLibL2CapChannelIdType

Comments

An L2CAP channel ID uniquely identifies the local endpoint of an L2CAP connection on a given device. L2CAP channel IDs are assigned by the system when an L2CAP connectoin is established.

BtLibL2CapPsmType Typedef ^TOP^

Purpose

The BtLibL2CapPsmType type represents a Protocol and Server Multiplexer (PSM) value. See the "Logical Link and Adaptation Protocol Specification" chapter of the Specification of the Bluetooth System for more information about PSM values. The Bluetooth library only supports two-byte PSM values.

Declared In

BtLibTypes.h

Prototype

typedef uint16_t BtLibL2CapPsmType

BtLibLanguageBaseTripletType Struct ^TOP^

Purpose

The BtLibLanguageBaseTripletType structure represents a language base attribute identifier list attribute. See the "Service Discovery Protocol" chapter of the Specification of the Bluetooth System for more information.

Declared In

BtLibTypes.h

Prototype

typedef struct BtLibLanguageBaseTripletType {
   uint16_t naturalLanguageIdentifier;
   uint16_t characterEncoding;
   uint16_t baseAttributeID;
} BtLibLanguageBaseTripletType

Fields

naturalLanguageIdentifier
A uint16_t representing a natural language. See Language ID Constants for a set of constants that can be used in this field.
characterEncoding
A uint16_t representing a character set encoding. See Character Encoding Constants for a set of constants that can be used in this field.
baseAttributeID
Base attribute identifiers for attributes represented in this language. See Attribute Identifier Constants for offsets that are added to this value to get the attribute identifiers for specific attributes represented in this language.

BtLibManagementEventType Struct ^TOP^

Purpose

The BtLibManagementEventType structure contains detailed information regarding a management 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.

Declared In

BtLibTypes.h

Prototype

typedef struct _BtLibManagementEventType {
   BtLibManagementEventEnum event;
   uint8_t padding1;
   uint16_t padding2;
   status_t status;
   union {
      BtLibDeviceAddressType bdAddr;
      BtLibAccessibleModeEnum accessible;
      struct {
         BtLibDeviceAddressType bdAddr;
      } nameResult;
      struct {
         BtLibDeviceAddressType bdAddr;
         uint16_t padding;
         BtLibClassOfDeviceType classOfDevice;
      } inquiryResult;
      struct {
         BtLibDeviceAddressType bdAddr;
         BtLibLinkModeEnum curMode;
         uint8_t padding;
         uint16_t interval;
      } modeChange;
      struct {
         BtLibDeviceAddressType bdAddr;
         Boolean enabled;
      } encryptionChange;
      struct {
         BtLibDeviceAddressType bdAddr;
         BtLibConnectionRoleEnum newRole;
      } roleChange;
      struct {
         BtLibDeviceAddressType bdAddr;
         int8_t rssi;
      } rssi;
   } eventData;
} BtLibManagementEventType

Fields

event
The event opcode.
padding1
Reserved for system use.
padding2
Reserved for system use.
status
The event's error code.
bdAddr
The Bluetooth device address; used by events btLibManagementEventACLConnectInbound, btLibManagementEventACLConnectOutbound, btLibManagementEventACLDisconnect, and btLibManagementEventAuthenticationComplete.
accessible
Indicates the state of the Bluetooth radio's accessibility. Used by the btLibManagementEventAccessibilityChange event.
nameResult
bdAddr contains the Bluetooth device's address. The data part of the message contains a BtLibFriendlyNameType structure. Used by the btLibManagementEventNameResult and btLibManagementEventLocalNameChange events.
inquiryResult
Information about a single device found during an inquiry procedure. bdAddr contains the address of the device found and classOfDevice identifies the device class. padding is reserved for system use. The data part of the message contains a structure of type BtLibFriendlyNameType with the remote device's name according to the local name cache; if the name isn't in the cache, the string is null. Used by the btLibManagementEventInquiryResult
modeChange
Used by the btLibManagementEventModeChange event. bdAddr specifies the address of an ACL link whose mode has changed. curMode indicates the new current mode, and interval indicates the length of time to remain in that mode, if applicable. padding is, as usual, reserved for system use.
encryptionChange
Used by btLibManagementEventEncryptionChange. bdAddr specifies the address of the ACL link whose encryption has changed, and enabled indicates whether encryption is on or off.
roleChange
Used by btLibManagementEventRoleChange. bdAddr indicates the address of the device whose role has changed, and newRole specifies the device's new role.
rssi
The Receiver Signal Strength Indicator indicates whether the signal strength of the receiver is below (negative), within (zero), or above (positive) the "Golden Receive Power Range," in units of one decibel. Not used in Palm OS Cobalt.0.

Comments

Applications obtain Management Entity events by calling IOSGetmsg() on a file descriptor opened to a Management Entity device. The control part of the message obtained this way contains a BtLibManagementEventType object. For some events, there's also a data part containing additional information.

The eventData union lets the structure only include data needed by the particular event message.

BtLibProfileDescriptorListEntryType Struct ^TOP^

Purpose

The BtLibProfileDescriptorListEntryType structure represents an entry in a profile descriptor list attribute. See the "Service Discovery Protocol" chapter of the Specification of the Bluetooth System for more information about profile descriptor list attributes.

Declared In

BtLibTypes.h

Prototype

typedef struct BtLibProfileDescriptorListEntryType 
{
   BtLibSdpUuidType profUUID;
   uint8_t padding1;
   uint16_t version;
   uint16_t padding2;
} BtLibProfileDescriptorListEntryType

Fields

profUUID
The profile's UUID.
padding1
Reserved for system use.
version
The profile version.
padding2
Reserved for system use.

BtLibProtocolDescriptorListEntryType Struct ^TOP^

Purpose

The BtLibProtocolDescriptorListEntryType structure represents an entry in a protocol descriptor list attribute. See the "Service Discovery Protocol" chapter of the Specification of the Bluetooth System for more information.

Declared In

BtLibTypes.h

Prototype

typedef struct 
BtLibProtocolDescriptorListEntryType {
   BtLibSdpUuidType protoUUID;
   uint8_t padding1;
   uint16_t padding2;
   union {
      BtLibL2CapPsmType psm;
      BtLibRfCommServerIdType channel;
   } param;
} BtLibProtocolDescriptorListEntryType

Fields

protoUUID
The protocol's UUID.
padding1
Reserved for system use.
padding2
Reserved for system use.
param
A union containing two members: psm and channel. psm is applicable for a L2Cap protocol descriptor and specifies the Protocol and Service Multiplexor. channel is applicable to a RfComm protocol descriptor and specifies the server channel.

BtLibProtocolEnum Typedef ^TOP^

Purpose

Specifies the protocol being used on a Bluetooth connection.

Declared In

BtLibTypes.h

Prototype

typedef enum {
   btLibL2CapProtocol,
   btLibRfCommProtocol,
   btLibSdpProtocol,
   btLibSCOProtocol,
   btLibBNEPProtocol
} BtLibProtocolEnum

Fields

btLibL2CapProtocol
L2Cap.
btLibRfCommProtocol
RfComm.
btLibSdpProtocol
SDP.
btLibSCOProtocol
SCO.
btLibBNEPProtocol
BNEP.

BtLibRfCommServerIdType Typedef ^TOP^

Purpose

The BtLibRfCommServerIdType type represents a RfComm server channel. See the "RFCOMM with TS 07.10" chapter of the Specification of the Bluetooth System for more information about server channels.

Declared In

BtLibTypes.h

Prototype

typedef uint8_t BtLibRfCommServerIdType

BtLibSdpAttributeDataType Struct ^TOP^

Purpose

The BtLibSdpAttributeDataType union is used to encapsulate an SDP attribute or a list entry in an SDP attribute. The BtLibSdpServiceRecordGetAttribute() function gets an attribute or a list entry and return its contents in a BtLibSdpAttributeDataType. The BtLibSdpServiceRecordSetAttribute() function sets an attribute or list entry according to the contents of a BtLibSdpAttributeDataType. This type supports the universal attributes defined in the Specification of the Bluetooth System.

Declared In

BtLibTypes.h

Prototype

typedef union BtLibSdpAttributeDataType {
   BtLibSdpUuidType serviceClassUuid;
   uint32_t serviceRecordState;
   BtLibSdpUuidType serviceIdUuid;
   BtLibProtocolDescriptorListEntryType 
protocolDescriptorListEntry;
   BtLibSdpUuidType browseGroupUuid;
   BtLibLanguageBaseTripletType 
languageBaseTripletListEntry;
   uint32_t timeToLive;
   uint8_t availability;
   BtLibProfileDescriptorListEntryType 
profileDescriptorListEntry;
   BtLibUrlType documentationUrl;
   BtLibUrlType clientExecutableUrl;
   BtLibUrlType iconUrl;
   BtLibStringType serviceName;
   BtLibStringType serviceDescription;
   BtLibStringType providerName;
} BtLibSdpAttributeDataType

Fields

serviceClassUuid
The service class UUID.
serviceRecordState
Used to cache service attributes. If this attribute is contained in a service record, its value is guaranteed to change each time any other attribute is added to, deleted from, or changed within the service record. This lets a client detect whether or not the record has changed by simply looking at the value of this attribute; if the value is has changed since the last time it was checked, the record has been altered.
serviceIdUuid
The service's UUID.
protocolDescriptorListEntry
See "BtLibProtocolDescriptorListEntryType."
browseGroupUuid
A list of UUIDs, each of which represents a browse group to which the service record belongs. The top level browser group ID, called PublicBrowseRoot, represents the root of the browsing directory. Its value is 00001002-0000-1000-8000-00805F9B34FB (UUID16 0x1002), as specified in the Bluetooth Assigned Numbers document.
languageBaseTripletListEntry
Describes a language triplet. See "BtLibLanguageBaseTripletType."
timeToLive
The number of seconds for which the information in the service record is expected to remain valid and unchanged. This interval is measured from the time that the attribute value is retrieved from the SDP server. It doesn't guarantee that the record will be available or unchanged, but instead recommends a polling interval for monitoring the service record for changes.
availability
Represents the relative ability of the service to accept additional clients. A value of 0xFF indicates that the service is not in use and is fully available to accept clients, while a value of 0x00 means the service is not accepting new clients. For services that support multiple simultaneous clients, intermediate values indicate the relative availability of the service on a linear scale.
For example, a service that can accept up to three clients should provide service availability values of 0xFF, 0xAA, 0x55, and 0x00 when 0, 1, 2, or 3 clients are using the service.
A non-zero value for availability doesn't necessarily guarantee availability; it should be considered a hint as to how likely a connection is to be accepted.
profileDescriptorListEntry
Describes an entry in a profile descriptor list. See "BtLibProfileDescriptorListEntryType."
documentationUrl
A URL to documentation for the service.
clientExecutableUrl
An URL to the program that is executed to run the service.
iconUrl
An URL to an icon to use to represent the service.
serviceName
The name of the service.
serviceDescription
A human-readable description of the service.
providerName
A string containing the name of the person or organization providing the service. The offset 0x0002 must be added to the attribute ID base (contained in the LangugaeBaseAttributeIDList attribute) in order to compute the attribute ID for this attribute.

Comments

Note that if you're retrieving a string or a URL using the BtLibSdpServiceRecordGetAttribute() function, you first need to allocate a buffer in addition to this union. This buffer must be large enough to contain the anticipated size of the string or URL. You must also initialize the string pointer and string length fields of the appropriate BtLibAttributeDataType union member. For example, if you're retrieving an icon URL, you need to set iconURL.url to point to the buffer. You also need to set iconURL.urllen to the length of the buffer.

See Also

BtLibSdpUuidType, BtLibSocketEventType, BtLibProfileDescriptorListEntryType, BtLibLanguageBaseTripletType, BtLibUrlType, BtLibStringType

BtLibSdpAttributeIdType Typedef ^TOP^

Purpose

The BtLibSdpAttributeIdType type represents a SDP attribute identifier.

Declared In

BtLibTypes.h

Prototype

typedef uint16_t BtLibSdpAttributeIdType

BtLibSdpRecordHandle Typedef ^TOP^

Purpose

The BtLibSdpRecordHandle type, also called an SDP memory handle, provides a memory handle to an SDP memory record.

Declared In

BtLibTypes.h

Prototype

typedef MemHandle BtLibSdpRecordHandle

Comments

A SDP memory record can have two roles: it can contain a local SDP service record or it can refer to an SDP service record on a remote device. In the latter role, the SDP memory record is said to be mapped to a service record on the remote device. The BtLibSdpServiceRecordMapRemote() function performs this mapping.

BtLibSdpRemoteServiceRecordHandle Typedef ^TOP^

Purpose

The BtLibSdpRemoteServiceRecordHandle type represents a SDP service record handle on a remote device as defined in the "Service Discovery Protocol" chapter of the Specification of the Bluetooth System. The documentation refers to this type as a remote service record handle.

Declared In

BtLibTypes.h

Prototype

typedef uint32_t
      BtLibSdpRemoteServiceRecordHandle

Comments

Note that this type is different from the BtLibSdpRecordHandle type, which refers to a memory chunk containing an SDP service record.

BtLibSdpUuidSizeEnum Typedef ^TOP^

Purpose

The BtLibSdpUuidSizeEnum enum specifies the sizes that a UUID can have. See BtLibSdpUuidType for more information.

Declared In

BtLibTypes.h

Prototype

typedef Enum8 BtLibSdpUuidSizeEnum

BtLibSdpUuidType Struct ^TOP^

Purpose

The BtLibSdpUuidType structure represents a Universally Unique Identifier (UUID). A UUID is a 128-bit value that is generated in a manner that guarantees (with very high probability) that it is different from every other UUID.

Declared In

BtLibTypes.h

Prototype

typedef struct BtLibSdpUuidType {
   BtLibSdpUuidSizeEnum size;
   uint8_t UUID[16];
} BtLibSdpUuidType

Fields

size
The number of bits used to specify the UUID. See BtLibSdpUuidSizeEnum.
UUID
The value of the UUID. If you're setting the value of this field, use the BtLibSdpUuidInitialize() macro.

Comments

The "Service Discovery Protocol" chapter of the Specification of the Bluetooth System reserves a set of UUIDs for common Bluetooth services and protocols. You can specify these with 32 bits—the remaining 96 bits have a fixed value. A subset of these can be specified with 16 bits zero-extended to 32 bits. Therefore you can specify a UUID using 16, 32, or 128 bits.

You generally don't set this type directly. Instead, you use the BtLibSdpVerifyRawDataElement() macro.

BtLibServiceDescriptionType Struct ^TOP^

Purpose

Parameters returned from a service application's sysBtLaunchCmdDescribeService launch code handler.

Declared In

BtLibTypes.h

Prototype

typedef struct {
   uint32_t flags;
   char *nameP;
   char *descriptionP;
} BtLibServiceDescriptionType

Fields

flags
A bit mask of service description flags. See "Service Description Flags" for possible values.
nameP
A pointer to a brief name of the service, to be displayed in the Bluetooth panel.
descriptionP
A pointer to a verbose description of what the service offers, which is also displayed by the Bluetooth panel.

Comments

The Bluetooth panel sends this launch code to obtain the information it needs to display in its services view.

The nameP and descriptionP must be set to localized strings in buffers allocated using MemPtrNew() or malloc(). nameP should be a short name for display in a menu, while descriptionP should be a longer description that is displayed when the service is selected in the services view.

For example, nameP might be "Personal Area Networking" while descriptionP might be "Allow other devices to connect and form an ad-hoc local network."

BtLibServiceExecutionParamsType Struct ^TOP^

Purpose

Specifies parameters passed to a service application when the sysBtLaunchCmdExecuteService launch code is sent.

Declared In

BtLibTypes.h

Prototype

typedef struct {
   int32_t fdData;
} BtLibServiceExecutionParamsType

Fields

fdData
The connected L2Cap or RfComm socket.

Comments

The fdData parameter is a file descriptor opened to a connected L2Cap or RfComm device instance, with a serial interface module optionally pushed onto that depending on the pushSerialModule registration flag.

On entry, the file descriptor is connected to its remote peer and is ready for data transfer. On exit, the file descriptor must be closed.

BtLibServicePreparationParamsType Struct ^TOP^

Purpose

Parameters passed to a service application's sysBtLaunchCmdPrepareService launch code handler.

Declared In

BtLibTypes.h

Prototype

typedef struct {
   int32_t fdListener;
   BtLibSdpRecordHandle serviceRecH;
} BtLibServicePreparationParamsType

Fields

fdListener
The L2Cap or RfComm listener file descriptor.
serviceRecH
Empty service record to be filled out.

Comments

The fdListener parameter is a file descriptor opened to an L2Cap or RfComm device instance. On entry, it's already been marked as a listener. On return it must be left unchanged; the Bluetooth system will take care of calling BtLibSdpServiceRecordStartAdvertising() to advertise the service, and BtLibSocketClose() after an inbound connection is made.

The serviceRecH parameter is a handle on a local SDP service record. On entry, it's empty. On exit, it must be set up to describe the service the application has to offer.

In most cases, the application can respond to this launch code by simply calling BtLibSdpServiceRecordSetAttributesForSocket(), passing the fdListener and serviceRecH parameters along with a class UUID and a service name.

In more complicated cases, the application may need to use other SDP functions to make needed changes to the service record. In these cases, it's the application's responsibility to open a Management Entity device instance to pass to those functions and to close that instance before returning.

BtLibServiceRegistrationParamsType Struct ^TOP^

Purpose

Service parameters passed to the BtLibRegisterService() function.

Declared In

BtLibTypes.h

Prototype

typedef struct {
   uint32_t stackSize;
   uint32_t appType;
   uint32_t appCreator;
   uint16_t appCodeRscId;
   BtLibProtocolEnum protocol;
   uint8_t execAsNormalApp:1, pushSerialModule:1;
} BtLibServiceRegistrationParamsType

Fields

stackSize
The service thread's stack size in bytes.
appType
The service application's resource database type.
appCreator
The service application's resource database creator.
appCodeRscId
The resource ID of the application's code resource.
protocol
Which protocol the service uses (L2Cap or RfComm).
execAsNormalApp
A bit flag indicating whether the application should run in the Application Process (1) or the System Process (0).
pushSerialModule
A bit flag indicating whether a serial interface module should be pushed onto the protocol device instance (1) or not (0).

Comments

The thread or threads that execute the service's entry points will be created with a stack of at least stackSize bytes.

The service's preparation entry point is always invoked in the System Process, regardless of the setting of the execAsNormalApp flag; this flag only controlls where the execution entry point is invoked.


NOTE: In the current version of Palm OS Cobalt, only execution in the System Process is supported, so execAsNormalApp should always be 0.

BtLibSocketConnectInfoType Struct ^TOP^

Purpose

The BtLibSocketConnectInfoType structure allows you to specify the address of the remote device and data specific to the protocol of the socket. The protocol-specific data is stored as a union; the member of the union that is valid depends on the protocol.

Declared In

BtLibTypes.h

Prototype

typedef struct BtLibSocketConnectInfoType {
   BtLibDeviceAddressTypePtr remoteDeviceP;
   union {
      struct {
         BtLibL2CapPsmType remotePsm;
         uint16_t minRemoteMtu;
         uint16_t localMtu;
      } L2Cap;
      struct {
         BtLibRfCommServerIdType remoteService;
         uint8_t advancedCredit;
         uint16_t maxFrameSize;
      } RfComm;
      struct {
         uint16_t localService;
         uint16_t remoteService;
      } bnep;
   } data;
   uint16_t padding;
} BtLibSocketConnectInfoType

Fields

remoteDeviceP
A pointer to a BtLibDeviceAddressType that contains the address of the remote device.
data
A union containing protocol-specific information. This union has three members: L2Cap, RfComm, and bnep.

L2Cap

For L2Cap, there are three fields:
remotePsm
A BtLibL2CapPsmType representing the protocol and service multiplexer (PSM) identifier of the protocol to which this socket should connect. This identifier is obtained using the Service Discovery Protocol (SDP).
minRemoteMtu
The minimum MTU, or packet size, that your application can support.
localMtu
The MTU, or packet size, of the local device.

RfComm

For RfComm, there are three fields as well:
remoteService
A BtLibRfCommServerIdType representing the RfComm service channel on the remote device to which this socket should connect. This identifier is obtained using the Service Discovery Protocol (SDP).
advancedCredit
An amount of credit the socket advances to the remote device when it successfully connects. Additional credit can be advanced using the BtLibSocketCreate function once the connection has been established.
maxFrameSize
The maximum frame size your application can handle. This value must be between BT_RF_MINFRAMESIZE and BT_RF_MAXFRAMESIZE. If your application can handle any frame size, set this value to BT_RF_DEFAULT_FRAMESIZE.

bnep

There are two fields for BNEP, which indicate which role the local and remove devices should each play. The roles must be one of three 16-bit UUIDs: 0x1115 for PANU, 0x1116 for NAP, and 0x1117 for GN.
localService
The UUID of the local role.
remoteService
The UUID of the remote role.
padding
Reserved for system use.

See Also

BtLibSocketSend(), BtLibSocketClose()

BtLibSocketEventType Struct ^TOP^

Purpose

The BtLibSocketEventType structure contains detailed information regarding a socket event. All socket events have some common data. Most socket events have additional data specific to those events. The specific data is stored in a union that is part of the BtLibSocketEvent data structure.

Declared In

BtLibTypes.h

Prototype

typedef struct _BtLibSocketEventType {
   BtLibSocketEventEnum event;
   uint8_t padding1;
   uint16_t padding2;
   status_t status;
   union {
      BtLibSocketRef newSocket;
      BtLibDeviceAddressType requestingDevice;
      struct {
         BtLibSdpRemoteServiceRecordHandle 
remoteHandle;
         union {
            BtLibL2CapPsmType psm;
            BtLibRfCommServerIdType channel;
         } param;
         uint16_t padding;
      } sdpByUuid;
      struct {
         uint16_t numSrvRec;
      } sdpServiceRecordHandles;
      struct {
         BtLibSdpAttributeIdType attributeID;
         uint16_t padding;
         BtLibSdpRecordHandle recordH;
         union {
            struct {
               BtLibSdpAttributeDataType 
attributeValues;
               uint16_t listNumber;
               uint16_t listEntry;
            } data;
            struct {
               uint16_t valSize;
            } rawData;
            uint16_t valSize;
            uint16_t strLength;
            uint16_t numItems;
         } info;
      } sdpAttribute;
   } eventData;
} BtLibSocketEventType

Fields

event
BtLibSocketEventEnum enum member that indicates which socket event has occurred.
padding1
Reserved for system use.
padding2
Reserved for system use.
status
Status of the event. See "BtLibSocketEventEnum" for more details about how to interpret this field for specific events.
eventData
fieldData associated with the event. The member of this union that is valid depends on the event. See BtLibSocketEventEnum for more information.

BtLibSocketListenInfoType Struct ^TOP^

Purpose

The BtLibSocketListenInfoType structure allows you to specify data specific to the protocol of the listening socket. This data is stored in the data field, which is a union consisting of two members: L2Cap, and RfComm. The member of the union that is valid depends on the protocol of the listening socket.

Declared In

BtLibTypes.h

Prototype

typedef struct BtLibSocketListenInfoType {
   union {
      struct {
         BtLibL2CapPsmType localPsm;
         uint16_t localMtu;
         uint16_t minRemoteMtu;
      } L2Cap;
      struct {
         BtLibRfCommServerIdType serviceID;
         uint8_t advancedCredit;
         uint16_t maxFrameSize;
      } RfComm;
      struct {
         Boolean listenNAP;
         Boolean listenGN;
         Boolean listenPANU;
      } BNEP;
   } data;
   uint16_t padding;
} BtLibSocketListenInfoType

Fields

data
A union which can represent L2Cap, RfComm, or BNEP.

L2Cap

L2Cap has the following fields:
localPsm
A BtLibL2CapPsmType representing the protocol and service multiplexer (PSM) identifier of the protocol to be used with this socket. You can identify your own protocol provided that its PSM value is odd, is within the range of 0x1001 to 0xFFFF, and has the 9th bit (0x0100) set to zero. These limitations are specified by the Specification of the Bluetooth System. If you set this field to BT_L2CAP_RANDOM_PSM, the BtLibSocketListen function automatically creates a suitable PSM for the channel and returns it in this structure.
localMtu
The maximum transmission unit (MTU), or packet size, of the local device.
minRemoteMtu
The minimum packet size that your application can support.

RfComm

RfComm has the following fields:
serviceID
A BtLibRfCommServerIdType representing the socket's RfComm service channel. It is assigned by RfComm and returned in this field when you call BtLibSocketListen.
advancedCredit
An amount of credit the socket advances to the remote device when it successfully connects. Additional credit can be advanced using the BtLibSocketCreate function once the connection has been established.
maxFrameSize
The maximum frame size your application can handle. This value must be between BT_RF_MINFRAMESIZE and BT_RF_MAXFRAMESIZE. If your application can handle any frame size, set this value to BT_RF_DEFAULT_FRAMESIZE.

BNEP

BNEP has the following fields, which specify which of the three PAN profile services it is willing to support:
listenNAP
true if the NAP service is supported.
listenGN
true if the GN service is supported.
listenPANU
true if the PANU service is supported.
padding
Reserved for system use.

See Also

BtLibSocketClose()

BtLibSocketRef Typedef ^TOP^

Purpose

The BtLibSocketRef type identifies a socket.

Declared In

BtLibTypes.h

Prototype

typedef int32_t BtLibSocketRef

Comments

Note that in versions of Palm OS prior to 6.0, the BtLibSocketRef was a 16-bit value.

BtLibStringType Struct ^TOP^

Purpose

The BtLibStringType structure represents a string in an SDP attribute.

Declared In

BtLibTypes.h

Prototype

typedef struct BtLibStringType {
   char *str;
   uint16_t strLen;
   uint16_t padding;
} BtLibStringType

Fields

str
An array of characters representing the string. This array is not null-terminated.
strLen
The length of the string, in bytes.
padding
Reserved for system use.

BtLibUrlType Struct ^TOP^

Purpose

The BtLibUrlType structure represents a uniform resource locator (URL) in an SDP attribute.

Declared In

BtLibTypes.h

Prototype

typedef struct BtLibUrlType {
   char *url;
   uint16_t urlLen;
   uint16_t padding;
} BtLibUrlType

Fields

url
An array of characters representing the URL. This array is not null-terminated.
urlLen
The length of the string, in bytes.
padding
Reserved for system use.

sockaddr_bth Struct ^TOP^

Purpose

A variant of the BSD Sockets sockaddr structure for use with Bluetooth.

Declared In

BtLibTypes.h

Prototype

typedef struct sockaddr_bth {
   sa_family_t sa_family;
   BtLibDeviceAddressType btAddr;
   BtLibSdpUuidType serviceClassId;
   uint8_t padding1;
   uint16_t padding2;
} sockaddr_bth

Fields

sa_family
The socket address family; for Bluetooth, this should be AF_BTH.
btAddr
A BtLibDeviceAddressType indicating the address of the Bluetooth device. This address is used on the client side to specify the remote Bluetooth device to which to connect. A value of all zeros implies that a discovery operation must be performed to allow the user to select the remote device.
serviceClassId
The UUID of the SDP service. On the client side, it specifies the service class to which to connect; on the server side, it specifies the service class to advertise.
padding1
Reserved for system use.
padding2
Reserved for system use.

Bluetooth Constants ^TOP^

Bluetooth Data Element Sizes ^TOP^

Purpose

Define the possible sizes of Bluetooth Data Elements.

Declared In

BtLibTypes.h

Constants

Table 13.10  Bluetooth Data Element sizes

Constant

Meaning

btLibDESD_1BYTE

Specifies a 1-byte element. However, if the element type is btLibDETD_NIL, then the size is actually 0.

btLibDESD_2BYTES

Specifies a 2-byte element.

btLibDESD_4BYTES

Specifies a 4-byte element.

btLibDESD_8BYTES

Specifies an 8-byte element.

btLibDESD_16BYTES

Specifies a 16-byte element.

btLibDESD_ADD_8BITS

The element's actual data size, in bytes, is contained in the next eight bits.

btLibDESD_ADD_16BITS

The element's actual data size, in bytes, is contained in the next 16 bits.

btLibDESD_ADD_32BITS

The element's actual data size, in bytes, is contained in the next 32 bits.

btLibDESD_MASK

AND this value with the first byte of a Data Element to obtain the element's size.

See Also

"Bluetooth Data Element Types"

Bluetooth Data Element Types ^TOP^

Purpose

Define the types of Data Elements supported by the Bluetooth system.

Declared In

BtLibTypes.h

Constants

Constant

Meaning

btLibDETD_ALT

Specifies a Data Element alternative. The data contains a sequence of Data Elements. This type is sometimes used to distinguish between two possible sequences. Must use size btLibDESD_ADD_8BITS, btLibDESD_ADD_16BITS, or btLibDESD_ADD_32BITS.

btLibDETD_BOOL

Specifies a Boolean value. Must use size btLibDESD_1BYTE.

btLibDETD_NIL

Specifies nil, the null type. Requires a size of btLibDESD_1BYTE, which for this type actually means 0 bytes.

btLibDETD_SEQ

Specifies a Data Element sequence. The data contains a sequence of Data Elements. Must use size btLibDESD_ADD_8BITS, btLibDESD_ADD_16BITS, or btLibDESD_ADD_32BITS.

btLibDETD_SINT

Specifies a signed integer. Must use size btLibDESD_1BYTE, btLibDESD_2BYTES, btLibDESD_4BYTES, btLibDESD_8BYTES, or btLibDESD_16BYTES

btLibDETD_TEXT

Specifies a text string. Must use size btLibDESD_ADD_8BITS, btLibDESD_ADD_16BITS, or btLibDESD_ADD_32BITS.

btLibDETD_UINT

Specifies an unsigned integer. Must use size btLibDESD_1BYTE, btLibDESD_2BYTES, btLibDESD_4BYTES, btLibDESD_8BYTES, or btLibDESD_16BYTES.

btLibDETD_URL

Specifies a Uniform Resource Locator (URL). Must use size btLibDESD_ADD_8BITS, btLibDESD_ADD_16BITS, or btLibDESD_ADD_32BITS.

btLibDETD_UUID

Specifies a Universally Unique Identifier (UUID). Must use size btLibDESD_2BYTES, btLibDESD_4BYTES, or btLibDESD_16BYTES.

btLibDETD_MASK

AND this value with the first byte of a Data Element to obtain the element's type.

See Also

"Bluetooth Data Element Sizes"

Bluetooth Device Names ^TOP^

Purpose

Define the names of Bluetooth STREAMS devices.

Declared In

BtLibTypes.h

Constants

Table 13.11  Bluetooth device names

Constant

Meaning

btDevMeName

Management Entity device.

btDevL2cName

L2Cap device.

btDevRfcName

RfComm device.

btDevSdpName

SDP device.

btDevSCOName

SCO device.

btDevBNEPName

BNEP device.

Bluetooth Disconnection Codes ^TOP^

Purpose

Values for the status field of btLibSocketEventDisconnected events, which explain why the disconnect occurred.

Declared In

BtLibTypes.h

Constants

Constant

Meaning

btLibL2DiscReasonUnknown

Unknown reason.

btLibL2DiscUserRequest

Either the local or remote user requested disconnection.

btLibL2DiscRequestTimeout

An L2Cap request timed out.

btLibL2DiscLinkDisc

The underlying ACL link disconnected.

btLibL2DiscQosViolation

Quality of Service violation.

btLibL2DiscSecurityBlock

Local Security Manager refused the connection.

btLibL2DiscConnPsmUnsupported

The remote device does not support the requested PSM.

btLibL2DiscConnSecurityBlock

The remote Security Manager refused the connection.

btLibL2DiscConnNoResources

Remote device is out of resources.

btLibL2DiscConfigUnacceptable

Configuration failed due to invalid parameters.

btLibL2DiscConfigReject

Configuration rejected for unknown reasons.

btLibL2DiscConfigOptions

Configuration failed due to unrecognized configuration options.

Bluetooth Error Codes ^TOP^

Purpose

Error codes that can occur when issuing Bluetooth calls.

Declared In

BtLibTypes.h

Constants

Error

Description

btLibErrNoError

Success.

btLibErrAlreadyConnected

A connection is already in place.

btLibErrAlreadyOpen

The Bluetooth Library is already open (this isn't an error, just a friendly notification).

btLibErrBatteryTooLow

The battery power is too low to perform the requested operation.

btLibErrBluetoothOff

The user has turned off Bluetooth.

btLibErrBusy

A needed resource is busy.

btLibErrCanceled

The operation was canceled.

btLibErrError

Generic error.

btLibErrFailed

Remote operation completed but failed.

btLibErrInProgress

An operation is already in progress.

btLibErrInUseByService

The resource is in use by a service.

btLibErrNoAclLink

No ACL link to the remote device.

btLibErrNoAdminDaemon

The daemon has not opened the admin device.

btLibErrNoConnection

No connection on socket.

btLibErrNoPiconet

A piconet is required for this operation.

btLibErrNoPrefs

The preferences are missing.

btLibErrNotFound

The requested value was not found.

btLibErrNotInProgress

Operation is not in progress.

btLibErrOutOfMemory

Memory allocation failed.

btLibErrParamError

Invalid parameter to function.

btLibErrPending

Operation will complete later; status and results will arrive in an event.

btLibErrRadioFatal

The Bluetooth hardware has failed while in use.

btLibErrRadioInitFailed

Initialization of the Bluetooth radio failed.

btLibErrRadioInitialized

The Bluetooth hardware was initialized successfully. This isn't an error, just a notification.

btLibErrRadioSleepWake

The Bluetooth hareware failed because the device went to sleep.

btLibErrRoleChange

Could not perform master/slave role switch.

btLibErrSdpAdvertised

Invalid operation on an advertised record.

btLibErrSdpAttributeNotSet

Attribute is not set for record.

btLibErrSdpFormat

Service record is improperly formatted.

btLibErrSdpInvalidResponse

Invalid data in SDP response.

btLibErrSdpMapped

Invalid operation on mapped record.

btLibErrSdpNotAdvertised

Invalid operation on an unadvertised record.

btLibErrSdpNotMapped

Invalid operation on an unmapped record.

btLibErrSdpQueryContinuation

Invalid continuation data.

btLibErrSdpQueryDisconnect

SDP disconnected.

btLibErrSdpQueryHandle

Invalid service record handle.

btLibErrSdpQueryPduSize

Invalid Protocol Data Unit (PDU) size.

btLibErrSdpQueryResources

Insufficient resources for request.

btLibErrSdpQuerySyntax

Invalid request syntax.

btLibErrSdpQueryVersion

Invalid or unsupported SDP version.

btLibErrSdpRemoteRecord

Invalid operation on the remote SDP record.

btLibErrSocket

Invalid socket reference.

btLibErrSocketChannelUnavailable

Channel unavailable on remote device.

btLibErrSocketProtocol

Invalid protocol for operation.

btLibErrSocketPsmUnavailable

PSM is already in use.

btLibErrSocketRole

Invalid role (connecor/listener).

btLibErrSocketUserDisconnect

The user terminated the connection.

btLibErrTooMany

Capacity reached (specific meaning varies depending on the function called).

btLibNotYetSupported

Unsupported feature.

Bluetooth Module Names ^TOP^

Purpose

Names of the Bluetooth STREAMS modules.

Declared In

BtLibTypes.h

Constants

Constant

Meaning

btModSerL2cName

Serial-on-L2Cap module.

btModSerRfcName

Serial-on-RfComm module.

btModTPISerRfcName

TPI-on-serial-on-RfComm module.

BSD Sockets Constants ^TOP^

Purpose

Constants used when utilizing the BSD Sockets API.

Declared In

BtLibTypes.h

Constants

Constant

Meaning

BTADDR_ANY

Represents any Bluetooth device address for BSD Sockets API calls.

BTHPROTO_RFCOMM

The protocol to use when creating an RfComm socket using the BSD Sockets API.

Character Encoding Constants ^TOP^

Purpose

Define character encodings for Bluetooth.

Declared In

BtLibTypes.h

Constants

btLibCharSet_Adobe_Standard_Encoding

btLibCharSet_Adobe_Symbol_Encoding

btLibCharSet_ANSI_X3_110_1983

btLibCharSet_ASMO_449

btLibCharSet_Big5

btLibCharSet_Big5_HKSCS

btLibCharSet_BS_4730

btLibCharSet_BS_viewdata

btLibCharSet_CSA_Z243_4_1985_1

btLibCharSet_CSA_Z243_4_1985_2

btLibCharSet_CSA_Z243_4_1985_gr

btLibCharSet_CSN_369103

btLibCharSet_DEC_MCS

btLibCharSet_DIN_66003

btLibCharSet_dk_us

btLibCharSet_DS_2089

btLibCharSet_EBCDIC_AT_DE

btLibCharSet_EBCDIC_AT_DE_A

btLibCharSet_EBCDIC_CA_FR

btLibCharSet_EBCDIC_DK_NO

btLibCharSet_EBCDIC_DK_NO_A

btLibCharSet_EBCDIC_ES

btLibCharSet_EBCDIC_ES_A

btLibCharSet_EBCDIC_ES_S

btLibCharSet_EBCDIC_FI_SE

btLibCharSet_EBCDIC_FI_SE_A

btLibCharSet_EBCDIC_FR

btLibCharSet_EBCDIC_IT

btLibCharSet_EBCDIC_PT

btLibCharSet_EBCDIC_UK

btLibCharSet_EBCDIC_US

btLibCharSet_ECMA_cyrillic

btLibCharSet_ES

btLibCharSet_ES2

btLibCharSet_EUC_JP

btLibCharSet_EUC_KR

btLibCharSet_Extended_UNIX_Code_Fixed_Width_for_Japanese

btLibCharSet_GB2312

btLibCharSet_GB_1988_80

btLibCharSet_GB_2312_80

btLibCharSet_GOST_19768_74

btLibCharSet_greek7

btLibCharSet_greek7_old

btLibCharSet_greek_ccitt

btLibCharSet_HP_DeskTop

btLibCharSet_HP_Legal

btLibCharSet_HP_Math8

btLibCharSet_HP_Pi_font

btLibCharSet_hp_roman8

btLibCharSet_HZ_GB_2312

btLibCharSet_IBM00858

btLibCharSet_IBM00924

btLibCharSet_IBM01140

btLibCharSet_IBM01141

btLibCharSet_IBM01142

btLibCharSet_IBM01143

btLibCharSet_IBM01144

btLibCharSet_IBM01145

btLibCharSet_IBM01146

btLibCharSet_IBM01147

btLibCharSet_IBM01148

btLibCharSet_IBM01149

btLibCharSet_IBM037

btLibCharSet_IBM038

btLibCharSet_IBM1026

btLibCharSet_IBM273

btLibCharSet_IBM274

btLibCharSet_IBM275

btLibCharSet_IBM277

btLibCharSet_IBM278

btLibCharSet_IBM280

btLibCharSet_IBM281

btLibCharSet_IBM284

btLibCharSet_IBM285

btLibCharSet_IBM290

btLibCharSet_IBM297

btLibCharSet_IBM420

btLibCharSet_IBM423

btLibCharSet_IBM424

btLibCharSet_IBM437

btLibCharSet_IBM500

btLibCharSet_IBM775

btLibCharSet_IBM850

btLibCharSet_IBM851

btLibCharSet_IBM852

btLibCharSet_IBM855

btLibCharSet_IBM857

btLibCharSet_IBM860

btLibCharSet_IBM861

btLibCharSet_IBM862

btLibCharSet_IBM863

btLibCharSet_IBM864

btLibCharSet_IBM865

btLibCharSet_IBM866

btLibCharSet_IBM868

btLibCharSet_IBM869

btLibCharSet_IBM870

btLibCharSet_IBM871

btLibCharSet_IBM880

btLibCharSet_IBM891

btLibCharSet_IBM903

btLibCharSet_IBM904

btLibCharSet_IBM905

btLibCharSet_IBM918

btLibCharSet_IBM_Symbols

btLibCharSet_IBM_Thai

btLibCharSet_IEC_P27_1

btLibCharSet_INIS

btLibCharSet_INIS_8

btLibCharSet_INIS_cyrillic

btLibCharSet_INVARIANT

btLibCharSet_ISO_10367_box

btLibCharSet_ISO_10646_UCS_2

btLibCharSet_ISO_10646_UCS_4

btLibCharSet_ISO_10646_UCS_Basic

btLibCharSet_ISO_10646_Unicode_Latin1

btLibCharSet_ISO_10646_UTF_1

btLibCharSet_ISO_2022_CN

btLibCharSet_ISO_2022_CN_EXT

btLibCharSet_ISO_2022_JP

btLibCharSet_ISO_2022_JP_2

btLibCharSet_ISO_2022_KR

btLibCharSet_ISO_2033_1983

btLibCharSet_ISO_5427

btLibCharSet_ISO_5427_1981

btLibCharSet_ISO_5428_1980

btLibCharSet_ISO_646_basic_1983

btLibCharSet_ISO_646_irv_1983

btLibCharSet_ISO_6937_2_25

btLibCharSet_ISO_6937_2_add

btLibCharSet_ISO_8859_1

btLibCharSet_ISO_8859_10

btLibCharSet_iso_8859_13

btLibCharSet_iso_8859_14

btLibCharSet_ISO_8859_15

btLibCharSet_ISO_8859_1_Windows_3_0_Latin_1

btLibCharSet_ISO_8859_1_Windows_3_1_Latin_1

btLibCharSet_ISO_8859_2

btLibCharSet_ISO_8859_2_Windows_Latin_2

btLibCharSet_ISO_8859_3

btLibCharSet_ISO_8859_4

btLibCharSet_ISO_8859_5

btLibCharSet_ISO_8859_6

btLibCharSet_ISO_8859_6_E

btLibCharSet_ISO_8859_6_I

btLibCharSet_ISO_8859_7

btLibCharSet_ISO_8859_8

btLibCharSet_ISO_8859_8_E

btLibCharSet_ISO_8859_8_I

btLibCharSet_ISO_8859_9

btLibCharSet_ISO_8859_9_Windows_Latin_5

btLibCharSet_ISO_8859_supp

btLibCharSet_iso_ir_90

btLibCharSet_ISO_Unicode_IBM_1261

btLibCharSet_ISO_Unicode_IBM_1264

btLibCharSet_ISO_Unicode_IBM_1265

btLibCharSet_ISO_Unicode_IBM_1268

btLibCharSet_ISO_Unicode_IBM_1276

btLibCharSet_IT

btLibCharSet_JIS_C6220_1969_jp

btLibCharSet_JIS_C6220_1969_ro

btLibCharSet_JIS_C6226_1978

btLibCharSet_JIS_C6226_1983

btLibCharSet_JIS_C6229_1984_a

btLibCharSet_JIS_C6229_1984_b

btLibCharSet_JIS_C6229_1984_b_add

btLibCharSet_JIS_C6229_1984_hand

btLibCharSet_JIS_C6229_1984_hand_add

btLibCharSet_JIS_C6229_1984_kana

btLibCharSet_JIS_Encoding

btLibCharSet_JIS_X0201

btLibCharSet_JIS_X0212_1990

btLibCharSet_JUS_I_B1_002

btLibCharSet_JUS_I_B1_003_mac

btLibCharSet_JUS_I_B1_003_serb

btLibCharSet_KOI8_R

btLibCharSet_KOI8_U

btLibCharSet_KSC5636

btLibCharSet_KS_C_5601_1987

btLibCharSet_latin_greek

btLibCharSet_Latin_greek_1

btLibCharSet_latin_lap

btLibCharSet_macintosh

btLibCharSet_Microsoft_Publishing

btLibCharSet_MNEM

btLibCharSet_MNEMONIC

btLibCharSet_MSZ_7795_3

btLibCharSet_NATS_DANO

btLibCharSet_NATS_DANO_ADD

btLibCharSet_NATS_SEFI

btLibCharSet_NATS_SEFI_ADD

btLibCharSet_NC_NC00_10_81

btLibCharSet_NF_Z_62_010

btLibCharSet_NF_Z_62_010__1973_

btLibCharSet_NS_4551_1

btLibCharSet_NS_4551_2

btLibCharSet_PC8_Danish_Norwegian

btLibCharSet_PC8_Turkish

btLibCharSet_PT

btLibCharSet_PT2

btLibCharSet_SCSU

btLibCharSet_SEN_850200_B

btLibCharSet_SEN_850200_C

btLibCharSet_Shift_JIS

btLibCharSet_TIS_620

btLibCharSet_T_101_G2

btLibCharSet_T_61_7bit

btLibCharSet_T_61_8bit

btLibCharSet_UNICODE_1_1

btLibCharSet_UNICODE_1_1_UTF_7

btLibCharSet_UNKNOWN_8BIT

btLibCharSet_US_ASCII

btLibCharSet_us_dk

btLibCharSet_UTF_16

btLibCharSet_UTF_16BE

btLibCharSet_UTF_16LE

btLibCharSet_UTF_7

btLibCharSet_UTF_8

btLibCharSet_Ventura_International

btLibCharSet_Ventura_Math

btLibCharSet_Ventura_US

btLibCharSet_videotex_suppl

btLibCharSet_VIQR

btLibCharSet_VISCII

btLibCharSet_windows_1250

btLibCharSet_windows_1251

btLibCharSet_windows_1252

btLibCharSet_windows_1253

btLibCharSet_windows_1254

btLibCharSet_windows_1255

btLibCharSet_windows_1256

btLibCharSet_windows_1257

btLibCharSet_windows_1258

btLibCharSet_Windows_31J

L2Cap Constants ^TOP^

Purpose

Constants for the L2Cap protocol.

Declared In

BtLibTypes.h

Constants

Constant

Meaning

BT_L2CAP_MTU

The maximum size for L2Cap frames.

BT_L2CAP_RANDOM_PSM

Used when creating a listener socket; instructs the system to select a random, unused PSM.

Comments

The BT_L2CAP_RANDOM_PSM constant lets you ask the system to select an available Protocol Service Multiplexor (PSM) for you when creating an L2Cap listener socket, as seen in Listing 13.1.

Listing 13.1  Creating an L2Cap listener socket


listenInfo.data.L2Cap.localPsm = BT_L2CAP_RANDOM_PSM; 
listenInfo.data.L2Cap.localMtu = MAX_FRAME_SIZE_L2CAP; 
listenInfo.data.L2Cap.minRemoteMtu = MAX_FRAME_SIZE_L2CAP; 
err = BtLibSocketListen(socket, &listenInfo); 

Language ID Constants ^TOP^

Purpose

Define languages supported by the Bluetooth system.

Declared In

BtLibTypes.h

Constants

btLibLangAbkihazian

btLibLangAfar

btLibLangAfrikaans

btLibLangAlbanian

btLibLangAmharic

btLibLangArabic

btLibLangArmenian

btLibLangAssamese

btLibLangAymara

btLibLangAzerbaijani

btLibLangBashkir

btLibLangBasque

btLibLangBengali

btLibLangBhutani

btLibLangBihari

btLibLangBislama

btLibLangBreton

btLibLangBulgarian

btLibLangBurmese

btLibLangByelorussian

btLibLangCambodian

btLibLangCatalan

btLibLangChinese

btLibLangCorsican

btLibLangCroation

btLibLangCzech

btLibLangDanish

btLibLangDutch

btLibLangEnglish

btLibLangEsperanto

btLibLangEstonian

btLibLangFaroese

btLibLangFiji

btLibLangFinnish

btLibLangFrench

btLibLangFrisian

btLibLangGalician

btLibLangGeorgian

btLibLangGerman

btLibLangGreek

btLibLangGreenlandic

btLibLangGuarani

btLibLangGujarati

btLibLangHausa

btLibLangHebrew

btLibLangHindi

btLibLangHungarian

btLibLangIcelandic

btLibLangIndonesian

btLibLangInterlingua

btLibLangInterlingue

btLibLangInupiak

btLibLangIrish

btLibLangItalian

btLibLangJapanese

btLibLangJavanese

btLibLangKannada

btLibLangKashmiri

btLibLangKazakh

btLibLangKinyarwanda

btLibLangKirghiz

btLibLangKirundi

btLibLangKorean

btLibLangKurdish

btLibLangLaothian

btLibLangLatin

btLibLangLatvian

btLibLangLingala

btLibLangLithuanian

btLibLangMacedonian

btLibLangMalagasy

btLibLangMalay

btLibLangMalayalam

btLibLangMaltese

btLibLangMaori

btLibLangMarathi

btLibLangMoldavian

btLibLangMongolian

btLibLangNaura

btLibLangNepali

btLibLangNorwegian

btLibLangOccitan

btLibLangOriya

btLibLangOromo

btLibLangPashto

btLibLangPersian

btLibLangPolish

btLibLangPortuguese

btLibLangPunjabi

btLibLangQuechua

btLibLangRhaeto_Romance

btLibLangRomanian

btLibLangRussian

btLibLangSamoan

btLibLangSangho

btLibLangSanskrit

btLibLangScotsGaelic

btLibLangSerbian

btLibLangSerbo_Croation

btLibLangSesotho

btLibLangSetswanna

btLibLangShona

btLibLangSindhi

btLibLangSinghalese

btLibLangSiswati

btLibLangSlovak

btLibLangSlovenian

btLibLangSomali

btLibLangSpanish

btLibLangSundanese

btLibLangSwahili

btLibLangSwedish

btLibLangTagalog

btLibLangTajik

btLibLangTamil

btLibLangTatar

btLibLangTelugu

btLibLangThai

btLibLangTibetan

btLibLangTigrinya

btLibLangTonga

btLibLangTsonga

btLibLangTurkish

btLibLangTurkmen

btLibLangTwi

btLibLangUkranian

btLibLangUrdu

btLibLangUzbek

btLibLangVietnamese

btLibLangVolapuk

btLibLangWelsh

btLibLangWolof

btLibLangXhosa

btLibLangYiddish

btLibLangYoruba

btLibLangZulu

Management Event Status Codes ^TOP^

Purpose

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

Declared In

BtLibTypes.h

Constants

Constant

Meaning

btLibErrNoError

Success.

btLibMeStatusAuthenticateFailure

Authentication failure.

btLibMeStatusCommandDisallowed

Command disallowed.

btLibMeStatusConnnectionTimeout

Connection timed out.

btLibMeStatusHardwareFailure

Hardware failure.

btLibMeStatusHostTimeout

Host timeout.

btLibMeStatusInvalidHciParam

Invalid HCI command parameters.

btLibMeStatusInvalidLmpParam

Invalid LMP parameters.

btLibMeStatusLimitedResources

Host rejected due to limited resources.

btLibMeStatusLmpPduNotAllowed

LMP PDU not allowed.

btLibMeStatusLmpResponseTimeout

Timeout waiting for LMP response.

btLibMeStatusLmpTransdCollision

LMP error transaction collission.

btLibMeStatusLocalTerminated

Connection terminated by local host.

btLibMeStatusLowResources

Connection terminated by remote device due to low resources.

btLibMeStatusMaxAclConnections

Reached maximum number of ACL connections.

btLibMeStatusMaxConnections

Reached maximum number of connections.

btLibMeStatusMaxScoConnections

Reached maximum number of SCO connections.

btLibMeStatusMemoryFull

Not enough memory.

btLibMeStatusMissingKey

Missing key.

btLibMeStatusNoConnection

No connection.

btLibMeStatusPageTimeout

Page timeout.

btLibMeStatusPairingNotAllowed

Pairing not allowed.

btLibMeStatusPersonalDevice

Host rejected; remote is a personal device.

btLibMeStatusPowerOff

Connection terminated due to remote device powering off.

btLibMeStatusRepeatedAttempts

Repeated attempts.

btLibMeStatusRoleChangeNotAllowed

Can't perform master/slave role switch.

btLibMeStatusScoAirModeRejected

SCO air mode rejected.

btLibMeStatusScoIntervalRejected

SCO interval rejected.

btLibMeStatusScoOffsetRejected

SCO offset rejected.

btLibMeStatusSecurityError

Host rejected for security reasons.

btLibMeStatusUnknownHciCommand

Unknown HCI command.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

Remote user terminated the connection.

Miscellaneous Bluetooth Constants ^TOP^

Purpose

These constants don't fit into other categories, but are important nonetheless.

Declared In

BtLibTypes.h

Constants

Constant

Meaning

btLibDeviceAddressSize

The size, in bytes, of a Bluetooth address.

btLibFeatureCreator

The Bluetooth Library's creator ID, for use when calling the Feature Manager.

btLibFeatureVersion

The feature ID of the Bluetooth Library's version number.

btLibMaxDeviceNameLength

The maximum length of a Bluetooth device's user-friendly name.

btLibMaxSrvRecListLen

The maximum number of entries in a service record list.

Attribute Identifier Constants ^TOP^

Purpose

Define offsets for human-readable attributes that can be provided in multiple languages.

Declared In

BtLibTypes.h

Constants

Constant

Meaning

btLibServiceNameOffset

Offset to the human-readable service name attribute.

btLibServiceDescriptionOffset

Offset to the human-readable service description attribute

btLibProviderNameOffset

Offset to the human-readable provider name attribute.

Comments

In order to support multiple natural languages for human-readable attributes, a service record can contain a btLibLanguageBaseAttributeIdList attribute. This attribute is a list of triplets indicating the language ID, character encoding ID, and base attribute ID for each language for which a language is available.

Then these language support offsets are used in tandem with the language base attribute ID list to locate the actual string for the attribute in the desired language. For example, to locate the French version of the service's name, you would search the service record's btLibLanguageBaseAttributeIdList attribute for a triplet whose language ID is btLibLangFrench, get the base attribute ID from that triplet, and add btLibServiceNameOffset to that.

The resulting value is the ID of the attribute containing the service name in French. Your application can then display the string using the character encoding from the triplet.

Protocol UUIDs ^TOP^

Purpose

Raw values for protocol UUIDs that are predefined by the Bluetooth specification.

Declared In

BtLibTypes.h

Constants

Constant

btLibSdpUUID_PROT_AVCTP

btLibSdpUUID_PROT_AVDTP

btLibSdpUUID_PROT_BNEP

btLibSdpUUID_PROT_CMTP

btLibSdpUUID_PROT_FTP

btLibSdpUUID_PROT_HARDCOPY_CONTROL_CHANNEL

btLibSdpUUID_PROT_HARDCOPY_DATA_CHANNEL

btLibSdpUUID_PROT_HARDCOPY_NOTIFICATION

btLibSdpUUID_PROT_HIDP

btLibSdpUUID_PROT_HTTP

btLibSdpUUID_PROT_IP

btLibSdpUUID_PROT_L2CAP

btLibSdpUUID_PROT_OBEX

btLibSdpUUID_PROT_RFCOMM

btLibSdpUUID_PROT_SDP

btLibSdpUUID_PROT_TCP

btLibSdpUUID_PROT_TCS_AT

btLibSdpUUID_PROT_TCS_BIN

btLibSdpUUID_PROT_UDI_C_PLANE

btLibSdpUUID_PROT_UDP

btLibSdpUUID_PROT_UPNP

btLibSdpUUID_PROT_WSP

RfComm Constants ^TOP^

Purpose

Constants for the RfCommprotocol.

Declared In

BtLibTypes.h

Constants

Constant

Meaning

BT_RF_DEFAULT_FRAMESIZE

The default size of an RFCOMM frame.

BT_RF_MAX_FRAMESIZE

The maximum size of an RFCOMM frame.

BT_RF_MIN_FRAMESIZE

The minimum size of an RFCOMM frame.

Service Class UUIDs ^TOP^

Purpose

Raw values for service class UUIDs predefined by the Bluetooth specification.

Declared In

BtLibTypes.h

Constants

Constant

btLibSdpUUID_SC_ADVANCED_AUDIO_DISTRIBUTION

btLibSdpUUID_SC_AUDIO_SINK

btLibSdpUUID_SC_AUDIO_SOURCE

btLibSdpUUID_SC_AUDIO_VIDEO

btLibSdpUUID_SC_AV_REMOTE_CONTROL

btLibSdpUUID_SC_AV_REMOTE_CONTROL_TARGET

btLibSdpUUID_SC_BASIC_PRINTING

btLibSdpUUID_SC_BROWSE_GROUP_DESC

btLibSdpUUID_SC_COMMON_ISDN_ACCESS

btLibSdpUUID_SC_CORDLESS_TELEPHONY

btLibSdpUUID_SC_DIALUP_NETWORKING

btLibSdpUUID_SC_DIRECT_PRINTING

btLibSdpUUID_SC_DIRECT_PRINTING_REF_OBJ

btLibSdpUUID_SC_ESDP_UPNP_IP_LAP

btLibSdpUUID_SC_ESDP_UPNP_IP_PAN

btLibSdpUUID_SC_ESDP_UPNP_L2CAP

btLibSdpUUID_SC_FAX

btLibSdpUUID_SC_GENERIC_AUDIO

btLibSdpUUID_SC_GENERIC_FILE_TRANSFER

btLibSdpUUID_SC_GENERIC_NETWORKING

btLibSdpUUID_SC_GENERIC_TELEPHONY

btLibSdpUUID_SC_GN

btLibSdpUUID_SC_HANDSFREE

btLibSdpUUID_SC_HANDSFREE_AUDIO_GATEWAY

btLibSdpUUID_SC_HARDCOPY_CABLE_REPLACEMENT

btLibSdpUUID_SC_HCR_PRINT

btLibSdpUUID_SC_HCR_SCAN

btLibSdpUUID_SC_HEADSET

btLibSdpUUID_SC_HEADSET_AUDIO_GATEWAY

btLibSdpUUID_SC_HUMAN_INTERFACE_DEVICE

btLibSdpUUID_SC_IMAGING

btLibSdpUUID_SC_IMAGING_AUTOMATIC_ARCHIVE

btLibSdpUUID_SC_IMAGING_REFERENCED_OBJECTS

btLibSdpUUID_SC_IMAGING_RESPONDER

btLibSdpUUID_SC_INTERCOM

btLibSdpUUID_SC_IRMC_SYNC

btLibSdpUUID_SC_IRMC_SYNC_COMMAND

btLibSdpUUID_SC_IRMC_SYNC_COMMAND

btLibSdpUUID_SC_LAN_ACCESS_PPP

btLibSdpUUID_SC_NAP

btLibSdpUUID_SC_OBEX_FILE_TRANSFER

btLibSdpUUID_SC_OBEX_OBJECT_PUSH

btLibSdpUUID_SC_PANU

btLibSdpUUID_SC_PNP_INFORMATION

btLibSdpUUID_SC_PRINTING_STATUS

btLibSdpUUID_SC_PUBLIC_BROWSE_GROUP

btLibSdpUUID_SC_REFERENCE_PRINTING

btLibSdpUUID_SC_REFLECTED_UI

btLibSdpUUID_SC_SERIAL_PORT

btLibSdpUUID_SC_SERVICE_DISCOVERY_SERVER

btLibSdpUUID_SC_SIM_ACCESS

btLibSdpUUID_SC_UDI_MT

btLibSdpUUID_SC_UDI_TA

btLibSdpUUID_SC_UPNP_IP_SERVICE

btLibSdpUUID_SC_UPNP_SERVICE

btLibSdpUUID_SC_VIDEO_CONFERENCING

btLibSdpUUID_SC_VIDEO_CONFERENCING_GW

btLibSdpUUID_SC_WAP

btLibSdpUUID_SC_WAP_CLIENT

Service Description Flags ^TOP^

Purpose

Flags used by the sysBtLaunchCmdDescribeLaunchService launch code.

Declared In

BtLibTypes.h

Constants

btLibServDescFlag_CAN_DO_UI
If set, indicates that the service application is capable of responding to the sysBtLaunchCmdDoServiceUI launch code. When the service is selected in the services view of the Bluetooth panel, an "Advanced" button will appear, and tapping that button will cause the launch code to be sent to the service, which should do some sort of user interface specific to the service.

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.

Declared In

BtLibTypes.h

Constants

btLibNotAccessible = 0x00
The device does not respond to a page or an inquiry.
btLibConnectableOnly = 0x02
The device responds to a page but not an inquiry.
btLibDiscoverableAndConnectable = 0x03
The device responds to both a page and an inquiry.

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.

Declared In

BtLibTypes.h

Constants

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

BtLibGeneralPrefEnum Enum ^TOP^

Purpose

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

Declared In

BtLibTypes.h

Constants

btLibPref_Name
This preference is a BtLibFriendlyNameType containing the user-friendly name of the local device.
btLibPref_UnconnectedAccessible
preference is a BtLibAccessibleModeEnum indicating the accessibility mode of the local device when it is unconnected.
btLibPref_CurrentAccessible
This preference is a BtLibAccessibleModeEnum indicating the current accessibility mode of the local device. You cannot set this preference.
btLibPref_LocalClassOfDevice
This preference is a BtLibClassOfDeviceType indicating the class of the local device.
btLibPref_LocalDeviceAddress
This preference is a BtLibDeviceAddressType indicating the address of the local device. You cannot set this preference.

See Also

BtLibGetGeneralPreference(), BtLibSetGeneralPreference()

BtLibGetNameEnum Enum ^TOP^

Purpose

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

Declared In

BtLibTypes.h

Constants

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

See Also

BtLibGetRemoteDeviceName(), BtLibGetRemoteDeviceNameSynchronous()

BtLibLinkModeEnum Enum ^TOP^

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.

Declared In

BtLibTypes.h

Constants

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

Comments

btLibManagementEventModeChange

BtLibLinkPrefsEnum Enum ^TOP^

Purpose

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

Declared In

BtLibTypes.h

Constants

btLibLinkPref_Authenticated
This preference is a Boolean and indicates whether the link has been authenticated or not.
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(), BtLibLinkSetState()

BtLibManagementEventEnum Enum ^TOP^

Purpose

These event codes are posted on the Management Entity's file descriptor. Your application can poll the file descriptor to receive notification that they have occurred.

Declared In

BtLibTypes.h

Constants

btLibManagementEventRadioState
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.
btLibManagementEventInquiryResult
A remote device has responded to an inquiry that was started with the BtLibStartInquiry() function.
btLibManagementEventInquiryComplete
The device inquiry started with the BtLibStartInquiry() function has completed.
btLibManagementEventInquiryCanceled
The device inquiry has been canceled because the application called BtLibCancelInquiry().
btLibManagementEventACLDisconnect
An ACL link has been disconnected. The status field indicates the reason the link was disconnected.
btLibManagementEventACLConnectInbound
A remote device has established an ACL link to the local device.
btLibManagementEventACLConnectOutbound
An attempt to establish an ACL link to a remote device has completed; the status field indicates whether or not the attempt was successful.
btLibManagementEventPiconetCreated
The piconet has been created. This event can result from calling BtLibPiconetCreate().
btLibManagementEventPiconetDestroyed
The piconet has been destroyed. This event can result from calling BtLibPiconetDestroy().
btLibManagementEventModeChange
A slave has changed its mode. A slave can be in active, sniff, hold, or park mode.
btLibManagementEventAccessibilityChange
The accessibility mode of the local device has changed.
btLibManagementEventEncryptionChange
Encryption for a link has been enabled or disabled.
btLibManagementEventRoleChange
The master and slave devices for a link have switched roles.
btLibManagementEventNameResult
A remote device name request has completed.
btLibManagementEventLocalNameChange
The user-friendly name of the local device has changed.
btLibManagementEventAuthenticationComplete
The authentication of a remote device has completed.
btLibManagementEventPasskeyRequest
A remote device has requested a passkey. Your application does not have to respond to this request—the Bluetooth library automatically handles it.
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
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.
btLibManagementEventPairingComplete
Pairing has successfully completed and the link is authenticated.
btLibManagementEventRSSI
A radio strength indication event has occurred.

BtLibProtocolEnum Enum ^TOP^

Purpose

Define protocols supported by the Bluetooth system.

Declared In

BtLibTypes.h

Constants

btLibL2CapProtocol
L2CAP.
btLibRfCommProtocol
RFCOMM.
btLibSdpProtocol
SDP.
btLibBNEPProtocol
BNEP.
btLibSCOProtocol
SCO.

BtLibSdpUuidSizeEnum Enum ^TOP^

Purpose

The BtLibSdpUuidSizeEnum enum specifies the sizes that a UUID can have. See BtLibSdpUuidType for more information.

Declared In

BtLibTypes.h

Constants

btLibUuidSize16 = 2
16-bit UUID.
btLibUuidSize32 = 4
32-bit UUID.
btLibUuidSize128 = 16
Full-size 128-bit UUID.

BtLibSocketEventEnum Enum ^TOP^

Purpose

Specify events that can occur in response to socket operations; these are used by the event field in the BtLibSocketEventType structure; see that structure's description for details on the data specific to each event.

Declared In

BtLibTypes.h

Constants

btLibSocketEventConnectRequest
A remote device has requested a connection.
You must respond to this event with a call to BtLibSocketRespondToConnection().
If the remote device requests a L2Cap connection, this event is sent to the L2Cap listener socket with a PSM that matches the PSM of the request.
If the remote device requests an RfComm connection, this event is sent to the RfComm listener socket with a server channel that matches the server channel of the request.
To convert a socket into a listener socket use the BtLibSocketListen() function.
btLibSocketEventConnectedOutbound
An outbound connection initiated by a call to BtLibSocketConnect() has completed. The status field is btLibErrNoError if the connection has completed successfully. Otherwise, the status field indicates why the connection failed.
btLibSocketEventConnectedInbound
A remote connection has been accepted because the application has called BtLibSocketRespondToConnection().
If the remote device requests a L2Cap connection, this event is sent to the L2Cap listener socket with a PSM that matches the PSM of the requested connection. The Bluetooth library creates a new socket that exchanges data with the remote device.
If the remote device requests an RfComm connection, this event is sent to the RfComm listener socket with a server channel that matches the server channel of the requested connection. The Bluetooth library creates a new socket that exchanges data with the remote device.
btLibSocketEventDisconnected
If this event arrives on a data socket, then it means that the data socket has been disconnected, and the status field indicates the reson for hte disconnection.
If this event arrives on a listener socket, then it means that an inbound connection couldn't be established following a call to BtLibSocketRespondToConnection(), and the status field indicates the reason why the inbound connection failed.

IMPORTANT: In the case of failure of an inbound connection attempt, a new data socket is still returned in the eventData.newSocket field of the event. You must call BtLibSocketClose() to close it.
btLibSocketEventSendComplete
A previous send operation has completed. The application initiated this request by calling BtLibSocketSend().

NOTE: This event is only provided to maintain compatibility with previous versions of Palm OS. Applications do not have to wait for this event before reusing the data buffer passed to BtLibSocketSend(), which they had to do in versions of Palm OS prior to Palm OS Cobalt, version 6.0.
btLibSocketEventSdpServiceRecordHandle
A request for remote service records matching a list of service classes has completed. The application initiated this request by calling the BtLibSdpServiceRecordsGetByServiceClass() function.
btLibSocketEventSdpGetAttribute
An attribute request has completed. The application initiated this request by calling the BtLibSdpServiceRecordGetAttribute() function.
btLibSocketEventSdpGetStringLen
A string or URL length request has completed. The application initiated this request by calling BtLibSdpServiceRecordGetStringOrUrlLength().
btLibSocketEventSdpGetNumListEntries
A number of list entries request has completed. The application initiated this request by calling BtLibSdpServiceRecordGetNumListEntries().
btLibSocketEventSdpGetNumLists
A number of lists request has completed. The application initiated this request by calling BtLibSdpServiceRecordGetNumLists().
btLibSocketEventSdpGetRawAttribute
A get raw attribute request has completed. The application initiated the request by calling BtLibSdpServiceRecordGetRawAttribute().
btLibSocketEventSdpGetRawAttributeSize
A get raw attribute size request has completed. The application initiated this request by calling BtLibSdpServiceRecordGetSizeOfRawAttribute().
btLibSocketEventSdpGetServerChannelByUuid
A get server channel request has completed. The application initiated this request by calling BtLibSdpGetServerChannelByUuid().
btLibSocketEventSdpGetPsmByUuid
A get PSM request has completed. The application initiated this request by calling BtLibSdpGetPsmByUuid().

BtLibSocketInfoEnum Enum ^TOP^

Purpose

The BtLibSocketInfoEnum enum allows you to specify which information you want to retrieve using the BtLibSocketGetInfo function.

Declared In

BtLibTypes.h

Constants

btLibSocketInfo_Protocol = 0
BtLibSocketGetInfo() returns a BtLibProtocolEnum representing the socket's protocol.
btLibSocketInfo_RemoteDeviceAddress
BtLibSocketGetInfo() returns a BtLibDeviceAddressType representing the address of the device at the other end of this socket.
btLibSocketInfo_SendPending = 100
BtLibSocketGetInfo() returns a Boolean indicating whether a send is currently in progress.
btLibSocketInfo_MaxTxSize
BtLibSocketGetInfo() returns a uint32_t representing the maximum packet size the local device can transmit.
btLibSocketInfo_MaxRxSize
BtLibSocketGetInfo() returns a uint32_t representing the maximum packet size the local device can receive.
btLibSocketInfo_L2CapPsm = 200
BtLibSocketGetInfo() returns a BtLibL2CapPsmType that represents the Protocol and Service Multiplexer (PSM) this socket is using to route packets. This information is only valid for L2Cap sockets.
btLibSocketInfo_L2CapChannel
BtLibSocketGetInfo() returns a BtLibL2CapChannelIdType that represents the channel identifier for this socket. This information is valid for L2Cap sockets only. See the "Logical Link Control and Adaptation Protocol Specification" chapter of the Specification of the Bluetooth System for more information about channel identifiers.
btLibSocketInfo_RfCommServerId = 300
BtLibSocketGetInfo() returns a BtLibRfCommServerIdType that represents the socket's RfComm server channel. This information is valid for RfComm sockets only.
btLibSocketInfo_RfCommOutstandingCredits
BtLibSocketGetInfo() returns a uint16_t containing the number of remaining credits on this socket. This information is valid for RfComm sockets only.
btLibSocketInfo_SdpServiceRecordHandle = 400
BtLibSocketGetInfo() returns the BtLibSdpRemoteServiceRecordHandle for the service record associated with this socket. This information is valid for SDP sockets only.
btLibSocketInfo_DeviceNum = 1000
Used to get the minor device number of the STREAMS L2Cap or RfComm device instance.

Universal Service Attribute IDs ^TOP^

Purpose

Service attributes whose definitions are common to all service records.

Declared In

BtLibTypes.h

Constants

Constant

Definition

btLibServiceRecordHandle

An SDP service record handle.

btLibServiceClassIdList

A list of class IDs.

btLibServiceRecordState

A service record state.

btLibServiceId

A service ID.

btLibProtocolDescriptorList

A protocol descriptor list.

btLibBrowseGroupList

A browse group list.

btLibLanguageBaseAttributeIdList

A language attribute ID list. See "Attribute Identifier Constants."

btLibTimeToLive

A time-to-live value.

btLibAvailability

Availability information.

btLibProfileDescriptorList

A profile descriptor list.

btLibDocumentationUrl

An URL to documentation.

btLibClientExecutableUrl

The URL to a client executable.

btLibIconUrl

The URL to an icon.

Comments

Universal attributes aren't necessarily all used in every service record; they're simply standard attributes that may be used. If a service record has an attribute with an attribute ID assigned to a universal attribute, the attribute value must conform to the universal attribute's definition.

Only two attributes are required to exist in every service record instance: btLibServiceRecordHandle and btLibServiceClassIdList.

Bluetooth Application Launch Codes ^TOP^

sysBtLaunchCmdDoServiceUI ^TOP^

Purpose

Sent to Bluetooth service applications when the user taps the "Advanced" button in the services view of the Bluetooth panel. This gives the service the opportunity to display and manage custom UI to let the user configure the service.

Declared In

CmnLaunchCodes.h

Prototype

#define sysBtLaunchCmdDoServiceUI 89


Parameters

None.

Comments


NOTE: This launch code is only set if the btLibServDescFlag_CAN_DO_UI flag is set in the response when sysBtLaunchCmdDescribeService is called.

sysBtLaunchCmdDescribeService ^TOP^

Purpose

Sent to Bluetooth service applications to obtain information it needs in order to display its services view.

Declared In

CmnLaunchCodes.h

Prototype

#define sysBtLaunchCmdDescribeService 86


Parameters

The launch code's parameter block pointer references a BtLibServiceDescriptionType structure, in which the service application should return information about the service offered by the application.

sysBtLaunchCmdExecuteService ^TOP^

Purpose

Sent to Bluetooth service applications to let them know that there is an inbound-connected data socket.

Declared In

CmnLaunchCodes.h

Prototype

#define sysBtLaunchCmdExecuteService 77


Parameters

The launch code's parameter block pointer references a BtLibServiceExecutionParamsType structure. This structure identifies the connected L2Cap or RFComm socket.

Comments

Applications register themselves as Bluetooth services by calling BtLibRegisterService(). The service application receives this launch code each time a remote client connects. It receives the launch code in the context of the System process or the Application process, according to the execAsNormalApp registration flag. Bluetooth service applications must respond to this launch code.

The BtLibServiceExecutionParamsType structure contains a file descriptor opened to a connected L2Cap or RFComm device instance, with a serial interface module optionally pushed onto that (depending upon the pushSerialModule registration flag). Upon entry, it is connected to its remote peer and ready for data transfer. Upon exit, it must be closed.

See Also

sysBtLaunchCmdPrepareService

sysBtLaunchCmdPrepareService ^TOP^

Purpose

Sent to Bluetooth service applications to let them know that a listener socket has been created and to request an SDP service record.

CmnLaunchCodes.h

Prototype

#define sysBtLaunchCmdPrepareService 76


Parameters

The launch code's parameter block pointer references a BtLibServicePreparationParamsType structure. This structure identifies both a L2Cap or RFComm listener socket and an SDP service record that the Bluetooth service application fills in to describe the service that it is offering.

Comments

Applications register themselves as Bluetooth services by calling BtLibRegisterService(). The service application receives this launch code once after it registers itself, and then after each service execution session, in the context of the System Process. All Bluetooth service applications must respond to this launch code.

The BtLibServicePreparationParamsType structure contains a file descriptor opened to an L2Cap or RFComm device instance. Upon entry it has already been marked as a listener. Upon return it must be left unchanged; the Bluetooth system will take care of calling BtLibSdpServiceRecordStartAdvertising() to advertise the service, and BtLibSocketClose() after an inbound connection has been made.

The BtLibServicePreparationParamsType structure also contains a handle on a local SDP service record that, upon entry, is empty. Upon exit, it must be set up to describe the service that the application has to offer.

In most cases, the application can respond to this launch code by simply calling BtLibSdpServiceRecordSetAttributesForSocket(), passing the BtLibServicePreparationParamsType structure's fields along with a service class UUID and a service name. In more complex cases, the application will need to use other BtLibSdpxxx() functions to construct the service record. In such cases it is the application's responsibility to open a Management Entity device instance to pass to those functions, and to close it before returning.

See Also

sysBtLaunchCmdExecuteService

Bluetooth Functions and Macros ^TOP^

BtLibAddrAToBtd Function ^TOP^

Purpose

Convert an ASCII string a Bluetooth device address in colon-separated form to a 48-bit BtLibDeviceAddressType.

Declared In

BtLib.h

Prototype

status_t BtLibAddrAToBtd (
   const char *strBuf,
   BtLibDeviceAddressType *devAddrP
)

Parameters

strBuf
String containing ASCII colon-separated Bluetooth device address.
devAddrP

Returns

Pointer to a BtLibDeviceAddressType to store the converted device address.

Returns

Returns btLibErrNoError to indicate that the conversion was successful.

See Also

BtLibAddrBtdToA()

BtLibAddrBtdToA Function ^TOP^

Purpose

Convert 48-bit BtLibDeviceAddressType to an ASCII string in colon-separated form.

Declared In

BtLib.h

Prototype

status_t BtLibAddrBtdToA (
   BtLibDeviceAddressType *devAddrP,
   char *strBuf,
   uint16_t strBufSize
)

Parameters

devAddrP
Address of a Bluetooth device. This parameter must not be NULL.
strBuf
Pointer to a buffer to store the ASCII formatted Bluetooth devices address upon return. This parameter must not be NULL.
strBufSize
Size of the strBuf buffer, in bytes. Must be at least 18.

Returns

Returns btLibErrNoError if successful. Returns btLibErrParamErr if

  • devAddrP is NULL
  • strBuf is NULL
  • strBufSize is less than 18, the number of bytes required to store the ASCII formatted address

BtLibCancelInquiry Function ^TOP^

Purpose

Cancel a Bluetooth inquiry in process.

Declared In

BtLib.h

Prototype

status_t BtLibCancelInquiry (
   int32_t fdME
)

Parameters

fdME
The ME's file descriptor.

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 event.
btLibErrInProgress
The inquiry is already being canceled.
btLibErrNotInProgress
No inquiry is in progress to be canceled.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

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

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

See Also

BtLibStartInquiry()

BtLibClose Function ^TOP^

Purpose

Close the Bluetooth Management Entity.

Declared In

BtLib.h

Prototype

status_t BtLibClose (
   int32_t fdME
)

Parameters

fdME
The Management Entity's file descriptor.

Returns

btLibErrNoError
Success.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

Applications must call this function when they're done using the Management Entity file descriptor they obtained by calling BtLibOpen().

If this function closes the last Management Entity file descriptor, and there are no connected L2CAP, RFCOMM, SCO, or BNEP file descriptors open, then the following steps are taken:

  • If there are any remaining ACL links, they are destroyed.
  • If the radio hardware has been used since the last reinitialization, the stack and radio are shut down and reinitialized.

See Also

BtLibOpen()

BtLibDiscoverDevices Function ^TOP^

Purpose

Perform remote device discovery, presenting a user interface to let the user select remote devices or cancel the operation.

Declared In

BtLib.h

Prototype

status_t BtLibDiscoverDevices (
   int32_t fdME,
   char *instructionTxt,
   char *buttonTxt,
   Boolean addressAsName,
   BtLibClassOfDeviceType *filterTable,
   uint8_t filterTableLen,
   Boolean hideFavorites,
   BtLibDeviceAddressType *deviceTable,
   uint8_t deviceTableLen,
   uint8_t *numSelectedPtr
)

Parameters

fdME
The ME's file descriptor.
instructionTxt
Text to appear at the top of the selection box. Specify NULL to use the default text, which is "Select a device:" or "Select one or more devices:" depending on whether the deviceTableLen parameter is 1 or greater than one.
buttonTxt
Text to appear in the "done" button. Specify NULL to use the default text.
addressAsName
If true, devices' addresses will be displayed instead of their names.
filterTable
Pointer to a list of devices classes that should appear in the list. Specify NULL to list all devices.
filterTableLen
The number of entries in the filterTable list.
hideFavorites
If true, devices that are in the user's favorite devices list are not shown.
deviceTable
Pointer to a table to receive the addresses of the devices the user selects. Must not be NULL.
deviceTableLen
The number of slots in the deviceTable array.
numSelectedPtr
Receives the number of devices returned in the deviceTable list.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrCanceled
The user canceled the discovery process.
iosErrBadFD
The specified file descriptor is invalid.
iosErrNotOpened
The file descriptor specified is not for an opened Management Entity.

Comments

If the addressAsName parameter is true, the user will be presented with the discovered devices' Bluetooth addresses. If it's false, the Bluetooth system will attempt to obtain each device's user-friendly name, either from the cache or by connecting to the remote device and requesting it. If this is successful, the name will be displayed.

The filterTable can be used to restrict the devices that are presented to the user based on class of device; for example, if the application needs to locate a Bluetooth headset, it can specify btLibCOD_Minor_Audio_Headset in the filterTable.

The user will be prevented from selecting more than deviceTableLen devices.

BtLibGetGeneralPreference Function ^TOP^

Purpose

Get one of the general management preferences.

Declared In

BtLib.h

Prototype

status_t BtLibGetGeneralPreference (
   int32_t fdME,
   BtLibGeneralPrefEnum pref,
   void *prefValueP,
   uint16_t prefValueSize
)

Parameters

fdME
The ME's file descriptor.
pref
The general preference to get.
prefValueP
Pointer to a buffer to receive the preference's value. You must allocate this buffer, and this pointer must not be NULL.
prefValueSize
The size, in bytes, of the prefValueP buffer. You must set this size to match the size of the requested preference.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrParamError
One or more parameters is invalid. Be sure that the prefValueSize parameter matches the size of the preference value.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

Specify the preference with a member of the BtLibGeneralPrefEnum.


IMPORTANT: The 68K compatibility version of the Bluetooth library does not include the null terminator in the length of string preferences when you call this function; this is to maintain compatiblity with a bug in previous versions of Palm OS. The ARM-native version of this function, however, correctly includes the null terminator in the length of strings.

See Also

BtLibSetGeneralPreference()

BtLibGetRemoteDeviceName Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

status_t BtLibGetRemoteDeviceName (
   int32_t fdME,
   BtLibDeviceAddressType *remoteDeviceP,
   BtLibGetNameEnum retrievalMethod
)

Parameters

fdME
The ME's file descriptor.
remoteDeviceP
Pointer to a BtLibDeviceAddressType containing the address of the device whose name you wish to retrieve.
retrievalMethod
Method used to retrieve the user-friendly remote device name. See BtLibGetNameEnum.

Returns

Returns one of the following values:

btLibErrBusy
There is already a name request pending.
btLibErrPending
The results will be returned through a notification.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

This function returns btLibErrPending and generates a btLibManagementEventNameResult event when the name is available.

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

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.

BtLibGetRemoteDeviceNameSynchronous Function ^TOP^

Purpose

Return the user-friendly name of the given remote device, blocking until the name is determined.

Declared In

BtLib.h

Prototype

status_t BtLibGetRemoteDeviceNameSynchronous (
   int32_t fdME,
   BtLibDeviceAddressType *remoteDeviceP,
   BtLibGetNameEnum retrievalMethod,
   char *buffer,
   size_t bufferLen
)

Parameters

fdME
The ME's file descriptor.
remoteDeviceP
The address of the remote Bluetooth device.
retrievalMethod
A BtLibGetNameEnum indicating the method to use when obtaining the name.
buffer
A buffer to receive the name of the remote device. This buffer must be at least btLibMaxDeviceNameLength bytes long.
bufferLen
Size, in bytes, of the buffer.

Returns

Returns one of the following values:

btLibErrNoError
The name structure was successfully retrieved from the cache. No event will be generated.
btLibErrBusy
There is already a name request pending.
iosErrBadFD
The file descriptor is not valid.
iosErrNotOpened
The specified file descriptor isn't open.

Comments

This function blocks until the name retrieval attempt is completed. The resulting name is a null-terminated string. If the name is not found, an empty string is returned.

BtLibL2CapHToNL Macro ^TOP^

Purpose

Macro that converts a 32-bit value from host to L2Cap byte order. L2Cap byte order is little endian.

Declared In

BtLib.h

Prototype

#define BtLibL2CapHToNL (
   x
)

Parameters

x
32-bit value to convert.

Returns

Returns x in L2Cap byte order.

See Also

BtLibL2CapHToNS(), BtLibL2CapNToHL(), BtLibL2CapNToHS()

BtLibL2CapHToNS Macro ^TOP^

Purpose

Macro that converts a 16-bit value from host to L2Cap byte order. L2Cap byte order is little endian.

Declared In

BtLib.h

Prototype

#define BtLibL2CapHToNS (
   x
)

Parameters

x
16-bit value to convert.

Returns

Returns x in L2Cap byte order.

See Also

BtLibL2CapHToNL(), BtLibL2CapNToHS(), BtLibL2CapNToHL()

BtLibL2CapNToHL Macro ^TOP^

Purpose

Macro that converts a 32-bit value from L2Cap to host byte order. L2Cap byte order is little endian.

Declared In

BtLib.h

Prototype

#define BtLibL2CapNToHL (
   x
)

Parameters

x
32-bit value to convert.

Returns

Returns x in host byte order.

See Also

BtLibL2CapNToHS(), BtLibL2CapHToNL(), BtLibL2CapHToNS()

BtLibL2CapNToHS Macro ^TOP^

Purpose

Macro that converts a 16-bit value from L2Cap to host byte order. L2Cap byte order is little endian.

Declared In

BtLib.h

Prototype

#define BtLibL2CapNToHS (
   x
)

Parameters

x
16-bit value to convert.

Returns

Returns x in host byte order.

See Also

BtLibL2CapNToHL(), BtLibL2CapHToNS(), BtLibL2CapNToHL()

BtLibLinkConnect Function ^TOP^

Purpose

Create a Bluetooth Asynchronous Connectionless (ACL) link.

Declared In

BtLib.h

Prototype

status_t BtLibLinkConnect (
   int32_t fdME,
   BtLibDeviceAddressType *remoteDeviceP
)

Parameters

fdME
The ME's file descriptor.
remoteDeviceP
Pointer to a BtLibDeviceAddressType containing the address of the remote device.

Returns

Returns one of the following values:

btLibErrPending
The results will be returned through an event.
btLibErrAlreadyConnected
An ACL link already exists between the local device and the specified remote device.
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.
btLibErrTooMany
Cannot create another ACL link because the maximum allowed number has already been reached.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

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

status_t BtLibLinkDisconnect (
   int32_t fdME,
   BtLibDeviceAddressType *remoteDeviceP
)

Parameters

fdME
The ME's file descriptor.
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 event is generated.
btLibErrBusy
Can't disconnect the link because the piconet is being destroyed.
btLibErrNoConnection
No link to the specified device exists.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

When the link disconnects, a btLibManagementEventACLDisconnect event is generated.

See Also

BtLibLinkDisconnect()

BtLibLinkGetState Function ^TOP^

Purpose

Get the state of an ACL link.

Declared In

BtLib.h

Prototype

status_t BtLibLinkGetState (
   int32_t fdME,
   BtLibDeviceAddressType *remoteDeviceP,
   BtLibLinkPrefsEnum pref,
   void *linkStateP,
   uint16_t linkStateSize
)

Parameters

fdME
The ME's file descriptor.
remoteDeviceP
Pointer to a BtLibDeviceAddressType containing the address of the remote device.
pref
The link preference to retrieve. See BtLibLinkPrefsEnum.
linkStateP
Pointer to a buffer to receive the value of the preference. You must allocate this buffer, and this pointer must not be NULL. See BtLibLinkPrefsEnum for more information.
linkStateSize
The size, in bytes, of the linkStateP buffer.

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.
btLibErrParamError
The linkStateSize parameter is not same as the size of the preference value.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

See Also

BtLibLinkPrefsEnum

BtLibLinkSetState Function ^TOP^

Purpose

Set the state of an ACL link.

Declared In

BtLib.h

Prototype

status_t BtLibLinkSetState (
   int32_t fdME,
   BtLibDeviceAddressType *remoteDeviceP,
   BtLibLinkPrefsEnum pref,
   void *linkStateP,
   uint16_t linkStateSize
)

Parameters

fdME
The ME's file descriptor.
remoteDeviceP
Pointer to a BtLibDeviceAddressType containing the address of the remote device.
pref
The link preference to set. See BtLibLinkPrefsEnum.
linkStateP
Pointer to the preference's new value. If this is NULL, the call is ignored and no error occurs. See BtLibLinkPrefsEnum.
linkStateSize
Size, in bytes, of the linkStateP buffer.

Returns

Returns one of the following values:

btLibErrPending
The results will be returned through an event.
btLibErrFailed
An attempt was made to encrypt a link before authenticating it.
btLibErrNoAclLink
No link to the specified remote device exists.
btLibErrParamError
The preference cannot be set or linkStateSize is invalid.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

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 btLibManagementEventAuthenticationComplete event indicates the link authentication has completed. The btLibManagementEventEncryptionChange event indicates that the encryption has been enabled or disabled.

See Also

BtLibLinkGetState()

BtLibMEEventName Function ^TOP^

Purpose

Return the name of the specified Management Entity event code.

Declared In

BtLib.h

Prototype

const char *BtLibMEEventName (
   BtLibManagementEventEnum event
)

Parameters

event
The event whose name should be returned.

Returns

Returns a pointer to a null-terminated string indicating the name of the ME event code.

Comments

This function is provided primarily for debugging purposes.

BtLibOpen Function ^TOP^

Purpose

Open a file descriptor to the Management Entity device, and wait for reinitialization of the stack and radio hardware if necessary.

Declared In

BtLib.h

Prototype

status_t BtLibOpen (
   int32_t *fdME
)

Parameters

fdME
Receives the ME's file descriptor.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrOutOfMemory
Not enough memory available to open the library.
btLibErrRadioInitFailed
The Bluetooth stack or radio could not be initialized.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

Applications must call this function before using the Bluetooth library. If this function is called just after a call to BtLibClose() or BtLibSocketClose() that caused stack and radio reinitialization, then this function will block until reinitialization is complete. If it does block, and it is being executed on the main UI thread, then a progress dialog is displayed.


NOTE: Previous versions of Palm OS would return from this function before actually initializing the radio hardware, and would inform you of success or failure through a series of events including btLibManagementEventRadioState, btLibManagementEventLocalNameChange, and btLibManagementEventAccessibilityChange. Under Palm OS Cobalt, this call simply fails with an error if the hardware cannot be initialized.

See Also

BtLibClose()

BtLibPiconetCreate Function ^TOP^

Purpose

Set up the local device to be the master of a piconet.

Declared In

BtLib.h

Prototype

status_t BtLibPiconetCreate (
   int32_t fdME,
   Boolean unlockInbound,
   Boolean discoverable
)

Parameters

fdME
The ME's file descriptor.
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 event is generated.
btLibErrPending
An ACL link exists, and a role change and/or accessibility change is necessary. The result will be returned in a btLibManagementEventPiconetCreated event.
btLibErrInProgress
A previous call to this function returned btLibErrPending, and the result is still pending.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

Despite its name, this function doesn't really create a piconet; it simply sets the local device's link management policy such that the local device can be the master of a piconet. It's still necessary to create ACL links with other devices to actually form the piconet.

This function may be called when there are no ACL links, or when there is already one ACL link. In the latter case, if the local device isn't already master, a master-slave switch will be initiated. Once the local device has been set up to be piconet master, more ACL links may be established.

If this function returns btLibErrPending, then a btLibManagementEventInquiryResult event is generated, and the status field of that event indicates whether the local device can be set up to be piconet master.

If the accessibility of the radio changes due to this operation, a btLibManagementEventAccessibilityChange event is generated.

See Also

BtLibPiconetDestroy(), BtLibPiconetLockInbound(), BtLibPiconetUnlockInbound()

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

status_t BtLibPiconetDestroy (
   int32_t fdME
)

Parameters

fdME
The ME's file descriptor.

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.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

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 BtLibStringType 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

status_t BtLibPiconetLockInbound (
   int32_t fdME
)

Parameters

fdME
The ME's file descriptor.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrBusy
The piconet is in the process of being destroyed.
btLibErrNoPiconet
No piconet exists.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

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

status_t BtLibPiconetUnlockInbound (
   int32_t fdME,
   Boolean discoverable
)

Parameters

fdME
The ME's file descriptor.
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.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

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

BtLibRegisterService Function ^TOP^

Purpose

Register a persistent Bluetooth service application.

Declared In

BtLib.h

Prototype

status_t BtLibRegisterService (
   BtLibServiceRegistrationParamsType *params
)

Parameters

params
A BtLibServiceRegistrationParamsType structure describing the service the application wishes to register.

Returns

Returns one of the following:

btLibErrNoError
Success.
btLibErrTooMany
The maximum number of services is already registered.

Comments

An application only needs to register a service once after a system boot; subsequent registrations are ignored.

Service applications must respond to the sysBtLaunchCmdPrepareService and sysBtLaunchCmdExecuteService launch codes.

BtLibRfCommHToNL Macro ^TOP^

Purpose

Macro that converts a 32-bit value from host to RfComm byte order. RfComm byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibRfCommHToNL (
   x
)

Parameters

x
32-bit integer to convert.

Returns

Returns x in RfComm byte order.

See Also

BtLibRfCommHToNS(), BtLibRfCommNToHL(), BtLibRfCommNToHS()

BtLibRfCommHToNS Macro ^TOP^

Purpose

Macro that converts a 16-bit value from host to RfComm byte order. RfComm byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibRfCommHToNS (
   x
)

Parameters

x
16-bit integer to convert.

Returns

Returns x in RfComm byte order.

See Also

BtLibRfCommHToNL(), BtLibRfCommNToHL(), BtLibRfCommNToHS()

BtLibRfCommNToHL Macro ^TOP^

Purpose

Macro that converts a 32-bit value from RfComm to host byte order. RfComm byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibRfCommNToHL (
   x
)

Parameters

x
32-bit integer to convert.

Returns

Returns x in host byte order.

See Also

BtLibRfCommNToHS(), BtLibRfCommHToNL(), BtLibRfCommHToNS()

BtLibRfCommNToHS Macro ^TOP^

Purpose

Macro that converts a 16-bit value from RfComm to host byte order. RfComm byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibRfCommNToHS (
   x
)

Parameters

x
16-bit integer to convert.

Returns

Returns x in host byte order.

See Also

BtLibRfCommNToHL(), BtLibRfCommHToNL(), BtLibRfCommHToNS()

BtLibSdpCompareUuids Function ^TOP^

Purpose

Compare two UUIDs.

Declared In

BtLib.h

Prototype

status_t BtLibSdpCompareUuids (
   int32_t fdME,
   BtLibSdpUuidType *uuid1,
   BtLibSdpUuidType *uuid2
)

Parameters

fdME
The ME's file descriptor.
uuid1
The first UUID to compare.
uuid2
The second UUID to compare.

Returns

Returns one of the following values:

btLibErrNoError
UUIDs are the same
btLibErrError
UUIDs are different.
btLibErrParamError
One or both UUIDs are invalid.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

BtLibSdpGetPsmByUuid Function ^TOP^

Purpose

Get an available L2Cap PSM using SDP.

Declared In

BtLib.h

Prototype

status_t BtLibSdpGetPsmByUuid (
   BtLibSocketRef socketRef,
   BtLibDeviceAddressType *rDev,
   BtLibSdpUuidType *serviceUUIDList,
   uint8_t uuidListLen
)

Parameters

socketRef
An SDP socket.
rDev
Device address of a remote device to query. This parameter must not be NULL.
serviceUUIDList
Array of UUIDs that must match those of the service record. This parameter must not be NULL.
uuidListLen
Length of serviceUuidList. A maximum of 12 entries is allowed.

Returns

Returns one of the following values:

btLibErrPending
The PSM value will be returned through an event.
btLibErrOutOfMemory
Not enough memory to complete request.
btLibErrParamError
One or more parameters is invalid.
btLibErrSocket
The specified socket is invalid or not in use.
btLibErrSocketRole
The specified socket is not connected.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

This function returns the L2Cap PSM of the first SDP record on the remote device that contains all the specified UUIDs.

This function generates a btLibSocketEventSdpGetPsmByUuid event when the query completes or fails.

See Also

BtLibSdpGetServerChannelByUuid()

BtLibSdpGetRawDataElementSize Macro ^TOP^

Purpose

Macro that returns a constant representing the data element's size.

Declared In

BtLib.h

Prototype

BtLibSdpGetRawDataElementSize (
   header
)

Parameters

header
First byte of a data element.

Returns

A constant representing the size of the data element.

Comments

The first byte of a SDP data element contains the type and size of the data element.

See Also

BtLibSdpGetRawElementType(), BtLibSdpParseRawDataElement(), BtLibSdpVerifyRawDataElement(), "Bluetooth Data Element Sizes"

BtLibSdpGetRawElementType Macro ^TOP^

Purpose

Macro that returns an SDP data element's type.

Declared In

BtLib.h

Prototype

BtLibSdpGetRawElementType (
   header
)

Parameters

header
The first byte of a data element.

Returns

The type of the data element.

Comments

The first byte of a SDP data element contains the type and size of the data element.

See Also

BtLibSdpGetRawDataElementSize(), BtLibSdpParseRawDataElement(), BtLibSdpVerifyRawDataElement(), "Bluetooth Data Element Types"

BtLibSdpGetServerChannelByUuid Function ^TOP^

Purpose

Get an available RfComm server channel using SDP.

Declared In

BtLib.h

Prototype

status_t BtLibSdpGetServerChannelByUuid (
   BtLibSocketRef socketRef,
   BtLibDeviceAddressType *rDev,
   BtLibSdpUuidType *serviceUUIDList,
   uint8_t uuidListLen
)

Parameters

socketRef
An SDP socket.
rDev
Device address of a remote device to query. This parameter must not be NULL.
serviceUUIDList
Array of UUIDs that must match those of the service record. This parameter must not be NULL.
uuidListLen
Length of serviceUuidList. A maximum of 12 entries is allowed.

Returns

Returns one of the following values:

btLibErrPending
The server channel will be returned through an event.
btLibErrOutOfMemory
Not enough memory to complete request.
btLibErrParamError
One or more parameters is invalid.
btLibErrSocket
The specified socket is invalid or not in use.
btLibErrSocketRole
The specified socket is not connected.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

This function returns the RfComm server channel number of the first SDP record on the remote device that contains all the specified UUIDs.

This function generates a btLibSocketEventSdpGetServerChannelByUuid event when the query completes or fails.

See Also

BtLibSdpGetPsmByUuid()

BtLibSdpHToNL Macro ^TOP^

Purpose

Macro that converts a 32-bit value from host to Service Discovery Protocol (SDP) byte order. SDP byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibSdpHToNL (
   x
)

Parameters

x
32-bit value to convert.

Returns

Returns x in SDP byte order.

See Also

BtLibSdpHToNS(), BtLibSdpNToHL(), BtLibSdpNToHS()

BtLibSdpHToNS Macro ^TOP^

Purpose

Macro that converts a 16-bit value from host to Service Discovery Protocol (SDP) byte order. SDP byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibSdpHToNS (
   x
)

Parameters

x
16-bit value to convert.

Returns

Returns x in SDP byte order.

See Also

BtLibSdpHToNL(), BtLibSdpNToHL(), BtLibSdpNToHS()

BtLibSdpNToHL Macro ^TOP^

Purpose

Macro that converts a 32-bit value from Service Discovery Protocol (SDP) to host byte order. SDP byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibSdpNToHL (
   x
)

Parameters

x
32-bit value to convert.

Returns

Returns x in host byte order.

See Also

BtLibSdpNToHS(), BtLibSdpHToNL(), BtLibSdpHToNS()

BtLibSdpNToHS Macro ^TOP^

Purpose

Macro that converts a 16-bit value from Service Discovery Protocol (SDP) to host byte order. SDP byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibSdpNToHS (
   x
)

Parameters

x
16-bit value to convert.

Returns

Returns x in host byte order.

See Also

BtLibSdpNToHL(), BtLibSdpHToNL(), BtLibSdpHToNS()

BtLibSdpParseRawDataElement Function ^TOP^

Purpose

Parse a raw SDP data element to determine where the data field begins and the size of the data field.

Declared In

BtLib.h

Prototype

status_t BtLibSdpParseRawDataElement (
   int32_t fdME,
   const uint8_t *value,
   uint16_t *offset,
   uint32_t *length
)

Parameters

fdME
The ME's file descriptor.
value
Pointer to a raw SDP data element.
offset
Offset, in bytes, between value and the start of the data field.
length
Length, in bytes, of the data field.

Returns

Returns one of the following values:

btLibErrNoError
Successfully parsed the attribute.
btLibErrNotOpen
The reference Bluetooth Management Entity is not open.
btLibErrParamError
dataElementP, offset, or length is NULL.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

A data element has three fields. The first field, called the header field, identifies the type of value stored in the data element and the size of the element. The second field, called the size field, contains more information about the size of the data if it's not completely specified by the header. Otherwise the size field is omitted. The third field, called the data field, contains the data element's actual value.

The offset this function returns is the offset between the start of the data element and the data field. The size this function returns is the the size of the data field. Note that the sum of the offset and the size is the size of the data element.

This function is especially useful for iterating through entries in a list attribute.

The Specification of the Bluetooth System has more information about the structure of a data element.

See Also

BtLibSdpVerifyRawDataElement(), BtLibSdpGetRawElementType(), BtLibSdpGetRawDataElementSize()

BtLibSdpServiceRecordCreate Function ^TOP^

Purpose

Allocate a memory chunk that represents an SDP service record.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordCreate (
   int32_t fdME,
   BtLibSdpRecordHandle *recordH
)

Parameters

fdME
The ME's file descriptor.
recordH
SDP memory handle for the new SDP memory record.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrOutOfMemory
Not enough memory to allocate the memory chunk.
btLibErrParamError
recordH is NULL.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

See Also

BtLibSdpServiceRecordDestroy(), BtLibSdpServiceRecordStartAdvertising(), BtLibSdpServiceRecordStopAdvertising()

BtLibSdpServiceRecordDestroy Function ^TOP^

Purpose

Free the memory associated with a SDP memory record.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordDestroy (
   int32_t fdME,
   BtLibSdpRecordHandle recordH
)

Parameters

fdME
The ME's file descriptor.
recordH
SDP memory handle associated with the memory chunk to be freed.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrParamError
recordH does not refer to an valid SDP memory record.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

This function stops advertising the record before it frees it.

See Also

BtLibSdpServiceRecordCreate(), BtLibSdpServiceRecordStartAdvertising(), BtLibSdpServiceRecordStopAdvertising()

BtLibSdpServiceRecordGetAttribute Function ^TOP^

Purpose

Retrieve the value of a specific attribute in a SDP memory record. If the attribute is a list or a protocol descriptor list (a list of lists), this function retrieves the value of a specific list entry.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordGetAttribute (
   int32_t fdME,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   BtLibSdpAttributeDataType *attributeValue,
   uint16_t listNumber,
   uint16_t listEntry
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle identifying the SDP memory record.
attributeID
Attribute identifier of the attribute to retrieve.
attributeValue
Buffer into which this function stores the attribute's value. You must allocate this buffer. This pointer must not be NULL.
listNumber
List to query if the attribute is a protocol descriptor list. Otherwise this parameter is ignored.
listEntry
Item to get in the list if the attribute is a list attribute. Otherwise this parameter is ignored.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrPending
The specified SDP memory record refers to a service record on a remote device. The result will be returned through an event.
btLibErrBusy
The connection is parked. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrInProgress
A query is already pending on this socket. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrNoAclLink
An ACL link to the remote device does not exist.
btLibErrOutOfMemory
Not enough memory to perform the query.
btLibErrParamError
recordH is an invalid handle or attributeValues is NULL.
btLibErrSdpAttributeNotSet
The specified attribute does not exist in the specified service record.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

If the specified SDP memory record refers to a service record on a remote device, this function generates a btLibSocketEventSdpGetAttribute event when the result is available or the query fails. In this case, the attribute value is contained within the control and data parts of the event when it is received by a call to IOSGetmsg(). The main part of the event is in the control part, and the string or URL associated with it, if there is one, is in the data part.

If you are retrieving a string or a URL, you need to allocate additional space. See the documentation for BtLibSdpAttributeDataType for more information.

This function supports the universal attributes defined in "Service Discovery Protocol" chapter of the Specification of the Bluetooth System.

See Also

BtLibSdpServiceRecordSetAttribute(), BtLibSdpServiceRecordMapRemote(), BtLibSdpServiceRecordGetNumListEntries(), BtLibSdpServiceRecordGetNumLists(), BtLibSdpServiceRecordGetStringOrUrlLength()

BtLibSdpServiceRecordGetNumListEntries Function ^TOP^

Purpose

Get the number of entries in a list attribute.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordGetNumListEntries (
   int32_t fdME,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   uint16_t listNumber,
   uint16_t *numEntries
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle identifying the SDP memory record.
attributeID
Attribute identifier of the attribute whose number of list entries is retrieved.
listNumber
List to query if the attribute is a ProfileDescriptorListEntry. Otherwise this parameter is ignored.
numEntries
On return, indicates the number of entries in the list.

Returns

Returns one of the following values:

btLibErrNoError
Success
btLibErrPending
The specified SDP memory record refers to a service record on a remote device. The result will be returned through an event.
btLibErrBusy
The connection is parked. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrInProgress
Another query is pending on this socket. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrNoAclLink
An ACL link to the remote device does not exist.
btLibErrOutOfMemory
Not enough memory to perform this query.
btLibErrParamError
recordH is an invalid handle or numEntries is NULL.
btLibErrSdpAttributeNotSet
The specified attribute does not exist in the specified service record.
btLibErrStackNotOpen
The Bluetooth stack failed to open when the library was opened.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

This function supports the universal attributes defined in "Service Discovery Protocol" chapter of the Specification of the Bluetooth System. Specifically, this function gives valid results for ServiceClassIdList, ProtocolDescriptorList, BrowseGroupList, LanguageBaseAttributeIDList, and ProfileDescriptorList attributes.

If the specified SDP memory record refers to a service record on a remote device, this function generates a btLibSocketEventSdpGetNumListEntries event when the result is available or the query fails.

See Also

BtLibSdpServiceRecordGetNumLists(), BtLibSdpServiceRecordGetAttribute(), BtLibSdpServiceRecordGetStringOrUrlLength(), BtLibSdpServiceRecordMapRemote()

BtLibSdpServiceRecordGetNumLists Function ^TOP^

Purpose

Get the number of lists in a protocol descriptor list SDP attribute.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordGetNumLists (
   int32_t fdME,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   uint16_t *numLists
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle identifying the SDP memory record.
attributeID
Attribute identifier of the attribute whose number of lists is retrieved.
numLists
On return, indicates the number of lists.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrPending
The specified SDP memory record refers to a service record on a remote device. The result will be returned through an event.
btLibErrBusy
The connection is parked. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrInProgress
Another query is pending on this socket. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrNoAclLink
An ACL link to the remote device does not exist.
btLibErrOutOfMemory
Not enough memory to perform this query.
btLibErrParamError
recordH is an invalid handle or numLists is NULL.
btLibErrSdpAttributeNotSet
The specified attribute does not exist in the specified service record.
btLibErrStackNotOpen
The Bluetooth stack failed to open when the library was opened.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

If the specified SDP memory record refers to a service record on a remote device, this function generates a btLibSocketEventSdpGetNumListEntries event when the result is available or the query fails.

See Also

BtLibSdpServiceRecordGetNumListEntries(), BtLibSdpServiceRecordGetAttribute(), BtLibSdpServiceRecordGetStringOrUrlLength(), BtLibSdpServiceRecordMapRemote()

BtLibSdpServiceRecordGetRawAttribute Function ^TOP^

Purpose

Retrieve the value of an attribute of an SDP memory record. The retrieved attribute is in the format defined in the "Service Discovery Protocol" chapter of the Specification of the Bluetooth System.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordGetRawAttribute (
   int32_t fdME,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   uint8_t *value,
   uint16_t *valSize
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle identifying the SDP memory record.
attributeID
Attribute identifier of the attribute to retrieve.
value
Buffer into which this function stores the retrieved SDP attribute data. You must allocate this buffer. This pointer must not be NULL.
valSize
Size of the value buffer upon entry. This parameter must not be zero. Upon return, contains the number of bytes retrieved.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrPending
The specified SDP memory record refers to a service record on a remote device. The result will be returned through an event.
btLibErrBusy
The connection is parked. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrInProgress
A query is already pending on this socket. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrNoAclLink
An ACL link to the remote device does not exist.
btLibErrOutOfMemory
Not enough memory to perform the query.
btLibErrParamError
recordH is an invalid handle, value is NULL, valSize is 0, or the size of the attribute value is larger than valSize.
btLibErrSdpAttributeNotSet
The specified attribute does not exist in the specified service record.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

If the specified SDP memory record refers to a service record on a remote device, this function generates a btLibSocketEventSdpGetRawAttribute event when the result is available or the query fails.

See Also

BtLibSdpServiceRecordSetRawAttribute(), BtLibSdpServiceRecordGetSizeOfRawAttribute(), BtLibSdpServiceRecordMapRemote()

BtLibSdpServiceRecordGetSizeOfRawAttribute Function ^TOP^

Purpose

Return the size, in bytes, of any attribute of an SDP memory record.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordGetSizeOfRawAttribute (
   int32_t fdME,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   uint16_t *size
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle identifying the SDP memory record.
attributeID
Attribute identifier of the attribute whose size is retrieved.
size
Pointer to a uint16_t into which the size of the attribute will be stored by this function. Must not be NULL.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrPending
The specified SDP memory record refers to a service record on a remote device. The result will be returned through an event.
btLibErrBusy
The connection is parked. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrInProgress
A query is already pending on this socket. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrNoAclLink
An ACL link to the remote device does not exist.
btLibErrOutOfMemory
Not enough memory to perform the query.
btLibErrParamError
recordH is an invalid handle or size is NULL.
btLibErrSdpAttributeNotSet
The specified attribute does not exist in the specified service record.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

If the specified SDP memory record refers to a service record on a remote device, this function generates a btLibSocketEventSdpGetRawAttributeSize event when the result is available or the query fails.

See Also

BtLibSdpServiceRecordGetRawAttribute(), BtLibSdpServiceRecordMapRemote(), BtLibSdpServiceRecordSetRawAttribute()

BtLibSdpServiceRecordGetStringOrUrlLength Function ^TOP^

Purpose

Get the length of a string or URL attribute in a SDP memory record.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordGetStringOrUrlLength (
   int32_t fdME,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   uint16_t *size
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle identifying the SDP memory record.
attributeID
Attribute identifier of the attribute whose length is retrieved.
size
Pointer to a uint16_t into which the length of the string or URL will be stored. This parameter cannot be NULL.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrPending
The specified SDP memory record refers to a service record on a remote device. The result will be returned through an event.
btLibErrBusy
The connection is parked. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrInProgress
A query is already pending on this socket. This error can occur only if the SDP memory record refers to a service record on a remote device.
btLibErrNoAclLink
An ACL link to the remote device does not exist.
btLibErrOutOfMemory
Not enough memory to perform the query.
btLibErrParamError
The recordH does not refer to a valid handle, length is NULL, or the attribute is not a string or a URL.
btLibErrSdpAttributeNotSet
The specified attribute does not exist in the specified SDP record.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

Bluetooth strings do not include a null terminator.

If the SDP memory record refers to a service record on a remote device, this function generates a btLibSocketEventSdpGetStringLen event when the result is available or the query fails.

See Also

BtLibSdpServiceRecordGetAttribute(), BtLibSdpServiceRecordGetNumListEntries(), BtLibSdpServiceRecordGetNumLists(), BtLibSdpServiceRecordMapRemote()

BtLibSdpServiceRecordMapRemote Function ^TOP^

Purpose

Configure an SDP memory record so it refers to a service record on a remote device.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordMapRemote (
   BtLibSocketRef socketRef,
   BtLibDeviceAddressType *rDev,
   BtLibSdpRemoteServiceRecordHandle remoteHandle,
   BtLibSdpRecordHandle recordH
)

Parameters

socketRef
The SDP socket.
rDev
The device to query.
remoteHandle
Remote service record handle.
recordH
SDP memory handle of an empty SDP record.

Returns

Returns one of the following values:

btLibErrNoError
The mapping was successful.
btLibErrOutOfMemory
Not enough memory to perform mapping.
btLibErrParamError
recordH is invalid or refers to an invalid memory chunk.
btLibErrSdpMapped
The SDP memory record is already mapped to a remote service record.
btLibErrSocket
The specified socket is invalid or not in use.
btLibErrSocketProtocol
The specified socket is not an SDP socket.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

You must create an SDP memory record using BtLibSdpServiceRecordCreate() before using this function.

Note that this function does not copy the contents of the remote service record to the SDP memory record in local memory.

BtLibSdpServiceRecordSetAttribute Function ^TOP^

Purpose

Set the value of an attribute in an SDP memory record. If the attribute is a list or a protocol descriptor list (a list of lists), this function sets the value of a specific list entry. The SDP memory record must represent a local unadvertised service record.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordSetAttribute (
   int32_t fdME,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   BtLibSdpAttributeDataType *attributeValue,
   uint16_t listNumber,
   uint16_t listEntry
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle of the service record to modify.
attributeID
Attribute identifier of the attribute to set.
attributeValue
Pointer to the new value for the attribute. This pointer must not be NULL.
listNumber
to modify if the attribute is a protocol descriptor list. Otherwise this parameter is ignored.
listEntry
Item to set in the list if the attribute is a list attribute. Otherwise this parameter is ignored.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrAdvertised
An advertised record was passed in recordH. The record must not be advertised.
btLibErrOutOfMemory
Not enough memory to set the attribute.
btLibErrParamError
recordH is invalid or attributeValue is NULL.
btLibErrRemoteRecord
A remote record was passed in recordH. The record must be local.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

This function only works on SDP memory records that are local and not advertised. You can advertise the record after you finish modifying it.

This function supports the universal attributes defined in the Specification of the Bluetooth System.

See Also

BtLibSdpServiceRecordGetAttribute(), BtLibSdpServiceRecordStartAdvertising(), BtLibSdpServiceRecordStopAdvertising()

BtLibSdpServiceRecordSetAttributesForSocket Function ^TOP^

Purpose

Initialize an SDP memory record so it can represent an existing L2Cap or RfComm listener socket as a service.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordSetAttributesForSocket(
    BtLibSocketRef socketRef,
   BtLibSdpUuidType *serviceUuidList,
   uint8_t uuidListLen,
   const char *serviceName,
   uint16_t serviceNameLen,
   BtLibSdpRecordHandle recordH
)

Parameters

socketRef
Reference number for an RfComm or L2Cap socket in listening mode.
serviceUuidList
List of UUIDs for the service record.
uuidListLen
Number of entries in serviceUUIDList. A maximum of 12 entries is allowed.
serviceName
User-friendly name for the service in English; if you want to use another language, you should use the lower-level functions and a language base attribute ID list.
serviceNameLen
Size, in bytes, of serviceName.
recordH
Handle of the service record to be initialized.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrAdvertised
The record specified by recordH is being advertised. You must stop advertising the record before you can change it.
btLibErrNotOpen
The Bluetooth library Entity is not open.
btLibErrOutOfMemory
Not enough memory to store the contents of the SDP record.
btLibErrParamError
recordH is not a valid record handle.
btLibErrRemoteRecord
A remote record was passed in recordH. Because the service is local, the record must be local.
btLibErrSocket
The specified socket is invalid or not in use.
btLibErrSocketRole
The specified socket is not a listener socket.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

You must first create an SDP record using BtLibSdpServiceRecordCreate(). However, the record must not be advertised. In other words, don't call BtLibSdpServiceRecordStartAdvertising() until after calling this function.

See Also

BtLibSdpServiceRecordCreate(), BtLibSocketListen()

BtLibSdpServiceRecordSetRawAttribute Function ^TOP^

Purpose

Set the value for an attribute of a SDP memory record. This function allows you to specify the attribute as an array of bytes in the format defined in the "Service Discovery Protocol" chapter of the Specification of the Bluetooth System. The SDP memory record must represent a local unadvertised service record.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordSetRawAttribute (
   int32_t fdME,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   const uint8_t *value,
   uint16_t valSize
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle identifying the SDP memory record.
attributeID
Attribute identifier of the attribute to set.
value
Array of bytes containing SDP attribute data in the format defined in the SDP protocol. This parameter must not be NULL.
valSize
Size, in bytes, of value. This parameter must not be 0.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrAdvertised
recordH is being advertised. The record must not be advertised.
btLibErrOutOfMemory
Not enough memory to set the attribute.
btLibErrParamError
recordH is invalid, value is NULL, or valSize is 0.
btLibErrRemoteRecord
recordH refers to a service record on a remote device. The service record must be local.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

If the service record is being advertised, you must stop advertising it before you modify it.

See Also

BtLibSdpServiceRecordGetRawAttribute(), BtLibSdpServiceRecordSetAttribute(), BtLibSdpServiceRecordStartAdvertising(), BtLibSdpServiceRecordStopAdvertising()

BtLibSdpServiceRecordsGetByServiceClass Function ^TOP^

Purpose

Get the service record handles corresponding to the service classes advertised on a remote device.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordsGetByServiceClass (
   BtLibSocketRef socketRef,
   BtLibDeviceAddressType *rDev,
   BtLibSdpUuidType *uuidList,
   uint16_t uuidListLen
)

Parameters

socketRef
The SDP socket.
rDev
Remote device to query.
uuidList
Array of UUIDs identifying the service classes. This parameter must not be NULL.
uuidListLen
Number of elements in the uuidList. You can specify a maximum of 12 UUIDs.

Returns

Returns one of the following values:

btLibErrPending
The results will be returned through an event.
btLibErrBusy
The connection to the remote device is parked.
btLibErrInProgress
A SDP query is already in progress on this socket.
btLibErrNoAclLink
An ACL link to the remote device does not exist.
btLibErrOutOfMemory
Not enough memory to perform the query.
btLibErrParamError
One or more parameters are invalid.
btLibErrSocket
The specified socket is invalid or not in use.
btLibErrSocketProtocol
The specified socket is not an SDP socket.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

This function generates a btLibSocketEventSdpServiceRecordHandle event when the matching service records are available or the query fails.

BtLibSdpServiceRecordStartAdvertising Function ^TOP^

Purpose

Make visible an SDP memory record representing a local SDP service record. Remote devices can access visible service records through SDP.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordStartAdvertising (
   int32_t fdME,
   BtLibSdpRecordHandle recordH
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle of the service record to make available to remote devices.

Returns

Returns one of the following values:

btLibErrNoError
Success
btLibErrParamError
recordH is not a valid record handle.
btLibErrRemoteRecord
recordH refers to a remote record. The record must be local.
btLibErrSdpAdvertised
The service record is already accessible by remote devices.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

You cannot modify an SDP memory record while it is available to remote devices.

See Also

BtLibSdpServiceRecordStopAdvertising()

BtLibSdpServiceRecordStopAdvertising Function ^TOP^

Purpose

Hide an SDP memory record representing a local SDP service record. Remote devices cannot access hidden service records through SDP.

Declared In

BtLib.h

Prototype

status_t BtLibSdpServiceRecordStopAdvertising (
   int32_t fdME,
   BtLibSdpRecordHandle recordH
)

Parameters

fdME
The ME's file descriptor.
recordH
Handle of the service record to hide.

Returns

Returns one of the following values:

btLibErrNoError
Success. The SDP record is no longer available to remote devices.
btLibErrParamError
recordH is not a valid record handle.
btLibErrRemoteRecord
recordH refers to a remote record. The record must be local.
btLibErrSdpNotAdvertised
The service record is already hidden from remote devices.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

See Also

BtLibSdpServiceRecordStartAdvertising()

BtLibSdpUuidInitialize Macro ^TOP^

Purpose

Macro that sets the value of a UUID.

Declared In

BtLibTypes.h

Prototype

#define BtLibSdpUuidInitialize (
   uuidVar,
    rawValue,
    uuidSize
)

Parameters

uuidVar
BtLibSdpUuidType to initialize.
rawValue
Array of bytes representing the UUID. The size of this array depends on uuidSize.
uuidSize
BtLibSdpUuidType member specifying the size of the rawValue array.

Returns

Nothing.

BtLibSdpVerifyRawDataElement Function ^TOP^

Purpose

Verify that a raw SDP data element is properly formed.

Declared In

BtLib.h

Prototype

status_t BtLibSdpVerifyRawDataElement (
   int32_t fdME,
   const uint8_t *value,
   uint16_t valSize,
   uint8_t maxLevel
)

Parameters

fdME
The ME's file descriptor.
value
Raw SDP attribute data.
valSize
Size of value, in bytes. The size of the data element must be less than or equal to this parameter, otherwise this function fails.
maxLevel
Maximum level of recursion over which this function verifies the data element. Must be at least one.

Returns

Returns one of the following values:

btLibErrNoError
SDP data element is properly formatted.
btLibErrError
SDP data element is not properly formatted.
btLibErrNotOpen
The reference Bluetooth library is not open.
btLibErrParamError
value is NULL.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

This function checks all size descriptors in the element to ensure that the data element fits into the indicated length. In the case of data element sequences or alternates, this function calls itself recursively.

The maxLevel parameter specifies the maximum number of times this function calls itself. Limiting the recursion level prevents an infinite loop if the data is bad. maxLevel must be large enough to handle the complete data element. For example, to verify a simple data element such as an unsigned integer, maxLevel must be at least 1. To verify a data element sequence of UUIDs, maxLevel must be at least 2.

See Also

BtLibSdpParseRawDataElement(), BtLibSdpGetRawDataElementSize(), BtLibSdpGetRawElementType()

BtLibSecurityFindTrustedDeviceRecord Function ^TOP^

Purpose

Search the device database for the device with the specified Bluetooth address. Return the index of the corresponding device record in the database.

Declared In

BtLib.h

Prototype

status_t BtLibSecurityFindTrustedDeviceRecord (
   int32_t fdME,
   BtLibDeviceAddressType *addrP,
   uint16_t *indexP
)

Parameters

fdME
File descriptor of the Management Entity.
addrP
Bluetooth address of remote device.
indexP
Index of the found record.

Returns

Returns one of the following values:
btLibErrNoError
Success.
btLibErrNotFound
No record with the specified remote device address was found.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

See Also

BtLibSecurityGetTrustedDeviceRecordInfo(), BtLibSecurityRemoveTrustedDeviceRecord()

BtLibSecurityGetTrustedDeviceRecordInfo Function ^TOP^

Purpose

Get information from a device record in the device database.

Declared In

BtLib.h

Prototype

status_t BtLibSecurityGetTrustedDeviceRecordInfo (
   int32_t fdME,
   uint16_t index,
   BtLibDeviceAddressType *addrP,
   char *nameBuffer,
   uint8_t nameBufferSize,
   BtLibClassOfDeviceType *codP,
   uint32_t *lastConnectedP,
   Boolean *trustedP
)

Parameters

fdME
File descriptor of the Management Entity.
index
Index of the record.
addrP
Bluetooth address of remote device.
nameBuffer
Pointer to buffer to store user-friendly name of remote device. You must allocate this buffer. Provide a NULL pointer if the user-friendly name is not needed.
nameBufferSize
Size of the nameBuffer buffer on entry. On exit, the size of the name.
codP
Pointer to a BtLibClassOfDeviceType representing the class of the device. You must allocate this structure. Provide a NULL pointer if the device class is not needed.
lastConnectedP
The date since the device last connected. This date is measured in seconds since midnight January 1, 1904. Provide a NULL pointer if the date of last connection is not needed.
trustedP
If true, the device is bonded and can connect to the local device without authentication. If false, the device is paired but not bonded—it will need to reauthenticate if it connects again. Provide a NULL pointer if this information is not needed.

Returns

Returns one of the following values:

btLibErrNoError
Success.
dmErrIndexOutOfRange
A record with the specified index could not be found.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

See Also

BtLibSecurityFindTrustedDeviceRecord()

BtLibSecurityNumTrustedDeviceRecords Function ^TOP^

Purpose

Return the number of bonded devices in the device database or return the total number of devices in the device database.

Declared In

BtLib.h

Prototype

status_t BtLibSecurityNumTrustedDeviceRecords (
   int32_t fdME,
   Boolean trustedOnly,
   uint16_t *numP
)

Parameters

fdME
File descriptor of the Management Entity.
trustedOnly
true to only obtain the total number of trusted devices in the database. false will obtain the total number of devices in the devices database, including both bonded and paired but not bonded devices.
numP
On return, contains the number of trusted devices.

Returns

Returns one of the following values:

btLibErrNoError
Success.
iosErrBadFD
The Management Entity file descriptor is bad.
iosErrNotOpened
The Management Entity file descriptor isn't open.

See Also

BtLibSecurityFindTrustedDeviceRecord(), BtLibSecurityGetTrustedDeviceRecordInfo()

BtLibSecurityRemoveTrustedDeviceRecord Function ^TOP^

Purpose

Removes a device from the device database.

Declared In

BtLib.h

Prototype

status_t BtLibSecurityRemoveTrustedDeviceRecord (
   int32_t fdME,
   uint16_t index
)

Parameters

fdME
The file descriptor of the Management Entity.
index
Index of the record to remove.

Returns

Returns one of the following values:

btLibErrNoError
Success.
dmErrIndexOutOfRange
A record with the specified index could not be found.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

See Also

BtLibSecurityFindTrustedDeviceRecord()

BtLibSetGeneralPreference Function ^TOP^

Purpose

Set one of the general management preferences.

Declared In

BtLib.h

Prototype

status_t BtLibSetGeneralPreference (
   int32_t fdME,
   BtLibGeneralPrefEnum pref,
   void *prefValueP,
   uint16_t prefValueSize
)

Parameters

fdME
The ME's file descriptor.
pref
General preference to set. See BtLibGeneralPrefEnum.
prefValueP
Pointer to the value of the preference. This parameter must not be NULL. See BtLibGeneralPrefEnum.
prefValueSize
The size, in bytes, of prevValueP.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrPending
The results will be returned through an event.
btLibErrParamError
One or more parameters is invalid. Be sure that prefValueSize matches the size of the preference value.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

See the BtLibGeneralPrefEnum 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()

BtLibSocketAdvanceCredit Function ^TOP^

Purpose

Advance credit to a given RfComm connection socket.

Declared In

BtLib.h

Prototype

status_t BtLibSocketAdvanceCredit (
   BtLibSocketRef socketRef,
   uint8_t credit
)

Parameters

socketRef
The BtLibSocketRef indicating the socket.
credit
Number credits to add to the total number of credits for this socket. The total number of credits represents the number of packets the remote device can send before data flow stops.

Returns

Returns one of the following values:

btLibErrNoError
Success
btLibErrFailed
Too many credits advanced.
btLibErrSocket
The specified socket is invalid.
btLibErrSocketProtocol
The specified socket is not an RfComm socket.
btLibErrSocketRole
The specified socket is not connected.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

RfComm uses a credit based flow control mechanism. For each credit the connection has, one packet of data can be sent. When the credits are spent, data flow stops until you advance more credits using this function.

Multiple calls to this function have a cumulative effect.

BtLibSocketClose Function ^TOP^

Purpose

Close a socket, free associated resources, and kill all associated socket connections.

Declared In

BtLib.h

Prototype

status_t BtLibSocketClose (
   BtLibSocketRef socketRef
)

Parameters

socketRef
The BtLibSocketRef indicating the socket.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrSocket
The specified socket is invalid.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

No events are generated when closing a socket.

If there are no Management Entity file descriptors open, and this function closes the last connected L2CAP, RFCOMM, SCO, or BNEP file descriptor, then the following steps are taken:

  • If there are any remaining ACL links, they are destroyed.
  • If the radio has been used since the last reinitialization, the stack and radio are shut down and reinitialized.

See Also

BtLibSocketCreate(), BtLibSocketListen(), BtLibSocketConnect(), BtLibSocketRespondToConnection()

BtLibSocketConnect Function ^TOP^

Purpose

Create an outbound L2Cap, RfComm, SCO, or BNEP connection.

Declared In

BtLib.h

Prototype

status_t BtLibSocketConnect (
   BtLibSocketRef socketRef,
   BtLibSocketConnectInfoType *connectInfo
)

Parameters

socketRef
The socket to connect.
connectInfo
BtLibSocketConnectInfoType containing Bluetooth device address and protocol-specific connection information.

Returns

Returns one of the following values:

btLibErrPending
The results will be returned through an event.
btLibErrNoAclLink
An ACL link for the remote device does not exist
btLibErrSocket
The specified socket is invalid.
btLibErrSocketProtocol
The protocol of the specified socket is not supported. This function only supports the L2Cap and RfComm protocols.
btLibErrSocketRole
The specified socket is already connected or listening.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

If the connection succeeds, the btLibSocketEventConnectedOutbound event is generated and its status field is set to btLibErrNoError. If connection fails, the same event is generated with a non-zero status field, or a btLibSocketEventDisconnected is generated. In both cases, the status field indicates the reason for the failure.

If the connection succeeds, when inbound data arrives, IOSGetmsg() will return a message with an empty control part and a data part containing the received data. When the channel disconnects, a btLibSocketEventDisconnected event is generated.

See Also

BtLibSocketSend(), BtLibSocketClose()

BtLibSocketCreate Function ^TOP^

Purpose

Create a socket (by opening a file descriptor) to an L2CAP, RFCOMM, SDP, SCO, or BNEP device.

Declared In

BtLib.h

Prototype

status_t BtLibSocketCreate (
   BtLibSocketRef *socketRefP,
   BtLibProtocolEnum socketProtocol
)

Parameters

socketRefP
Pointer to an allocated BtLibSocketRef that will receive the socket value on return. This pointer must not be NULL.
socketProtocol
The protocol (L2Cap, RFComm, or SDP) to use on the socket.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrParamError
socketRefP is NULL.
btLibErrTooMany
The maximum number of sockets allocated for the system has already been reached. The Bluetooth library supports a maximum of 16 socket connections.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

No events are generated when creating a socket.

Before terminating, applications should close all of the sockets that they have created.


NOTE: A socket reference is the same thing as an IOS file descriptor.

See Also

BtLibSocketConnect(), BtLibSocketListen(), BtLibSocketClose()

BtLibSocketEventName Function ^TOP^

Purpose

Return the name of the given socket event code.

Declared In

BtLib.h

Prototype

const char *BtLibSocketEventName (
   BtLibSocketEventEnum event
)

Parameters

event
The socket event code whose name should be returned.

Returns

Returns a pointer to a null-terminated string with the human-readable name of the event.

Comments

This function is primarily provided for debugging purposes.

BtLibSocketGetInfo Function ^TOP^

Purpose

Retrieve information for a currently open socket.

Declared In

BtLib.h

Prototype

status_t BtLibSocketGetInfo (
   BtLibSocketRef socketRef,
   BtLibSocketInfoEnum infoType,
   void *valueP,
   uint32_t valueSize
)

Parameters

socketRef
The socket to query.
infoType
Type of information to retrieve. See BtLibSocketInfoEnum.
valueP
Buffer into which this function stores the result. You must allocate the buffer.
valueSize
Size, in bytes, of the valueP buffer. This size must match that of the requested information.

Returns

Returns one of the following values:

btLibErrNoError
Success.
btLibErrParamError
One or more parameters is invalid. Be sure that the valueSize parameter matches the size of the information you're retrieving.
btLibErrSdpNotMapped
The SDP socket has not been mapped to a remote SDP service record. This error occurs when you try to obtain the SDP service record handle before you map socket to a remote service record using BtLibSdpServiceRecordMapRemote.
btLibErrSocket
The specified socket is invalid or not in use.
btLibErrSocketRole
The specified socket is not connected or has the wrong role for the request.
btlibErrSocketProtocol
The specified socket has the wrong protocol for the request.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

BtLibSocketListen Function ^TOP^

Purpose

Set up an L2Cap, RFComm, SCO, or BNEP socket as a listener.

Declared In

BtLib.h

Prototype

status_t BtLibSocketListen (
   BtLibSocketRef socketRef,
   BtLibSocketListenInfoType *listenInfoP
)

Parameters

socketRef
The socket to listen on.
listenInfoP
Protocol-specific listening information. For more information see BtLibSocketListenInfoType. This parameter must be NULL if the socket is an SCO socket, otherwise it must not be NULL.

Returns

Returns one of the following values:

btLibErrNoError
Success. The socket is listening for incoming connections.
btLibErrBusy
The given PSM is in use (L2Cap only)
btLibErrParamError
listenInfoP is NULL.
btLibErrSocket
The specified socket is invalid.
btLibErrSocketProtocol
The protocol of the specified socket is not supported. This function only supports the L2Cap and RfComm protocols.
btLibErrSocketRole
The specified socket is already listening or connected.
btLibErrTooMany
There are no resources to create a listener socket of this type.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

A listener socket waits for a remote device to initiate a connection to the local device and then generates a btLibSocketEventConnectRequest event to notify the application that it needs to handle the connection attempt.

You need to respond to this event with a call to BtLibSocketConnect() on the listener socket to accept or reject the connection.

Under certain circumstances, the listenInfo parameter acts as an output as well as an input. See the discussion of BtLibSocketListenInfoType.

See Also

BtLibSocketClose()

BtLibSocketRespondToConnection Function ^TOP^

Purpose

Accept or reject an in-bound connection on a given listener socket.

Declared In

BtLib.h

Prototype

status_t BtLibSocketRespondToConnection (
   BtLibSocketRef socketRef,
   Boolean accept
)

Parameters

socketRef
The listener socket that needs to respond to a connection attempt.
accept
true to accept the connection; false to reject the connection.

Returns

Returns one of the following values:

btLibErrNoError
Success. This status is returned when accept is false.
btLibErrFailed
One or more parameters is invalid.
btLibErrPending
The results will be returned through an event.
btLibErrSocket
The specified socket is invalid or not in use.
btLibErrSocketProtocol
The protocol of the specified socket is not supported. This function only supports the L2Cap and RfComm protocols.
btLibErrSocketRole
The specified socket is not a listener socket.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

You should call this function when you respond to a btLibSocketEventConnectRequest event delivered to a listener socket.

If the connection succeeds, the btLibSocketEventConnectedInbound event is generated and its status field is set to btLibErrNoError. If connection fails, the same event is generated with a non-zero status field, or a btLibSocketEventDisconnected is generated. In both cases, the status field indicates the reason for the failure.

Once the connection succeeds, future calls to IOSPoll() will receive data messages whenever data is received from the remote device. If the channel disconnects, a btLibSocketEventDisconnected event is generated.

RfComm listener sockets and L2Cap listener sockets behave differently when you call this function. When you respond to an inbound L2Cap connection, a new L2Cap socket is created to exchange data with the remote device, and the L2Cap listener socket continues to listen for more connections. In other words, a single L2Cap listener socket can "spawn" several L2Cap sockets. This mechanism allows you to create a piconet.

When you respond to an RfComm connection, a new data socket is created through which you can exchange data with the remote device. However, unlike L2Cap, the listener socket remains intact but may not be reused; it also cannot be closed until the data socket is closed. You may, however, create a new listener socket to detect more inbound connections.

See Also

BtLibSocketListen(), BtLibSocketSend(), BtLibSocketClose()

BtLibSocketSend Function ^TOP^

Purpose

Send data over a connected L2Cap, RfComm, BNEP socket.

Declared In

BtLib.h

Prototype

status_t BtLibSocketSend (
   BtLibSocketRef socketRef,
   uint8_t *data,
   uint32_t dataLen
)

Parameters

socketRef
The transmitting socket.
data
Pointer to data to send.
dataLen
Length of data to send. This value must be less than the Maximum Transmission Unit (MTU) for the socket. The MTU indicates the size of the largest packet that the remote device can receive and is determined when the socket is connected.

Returns

Returns one of the following values:

btLibErrPending
The results will be returned through an event.
btLibErrBusy
A send is already in process.
btLibErrNoAclLink
An ACL link for the remote device does not exist
btLibErrSocket
The specified socket is invalid.
btLibErrSocketProtocol
The protocol of the specified socket is not supported by this function. You can only send using the L2Cap and RfCommprotocols.
btLibErrSocketRole
The specified socket is not connected.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

Comments

If the socket is not L2Cap, RfComm, or BNEP, or the socket is not connected, the data is silently discarded.

When the data has been sent successfully, a btLibSocketEventSendComplete event is generated and its status field is set to btLibErrNoError. If the data is not sent successfully, the same event is generated with a non-zero status field.


NOTE: Unlike previous versions of Palm OS, you can immediately reuse or dispose of the memory containing the data.

See Also

BtLibSocketClose()

BtLibStartInquiry Function ^TOP^

Purpose

Start a Bluetooth inquiry.

Declared In

BtLib.h

Prototype

status_t BtLibStartInquiry (
   int32_t fdME,
   uint8_t timeOut,
   uint8_t maxResp
)

Parameters

fdME
The ME's file descriptor.
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 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.
iosErrBadFd
The specified file descriptor is invalid.
iosErrNotOpened
The specified file descriptor is not open.

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 event is generated. When the inquiry is complete, a btLibManagementEventInquiryComplete event is generated. If the application calls BtLibCancelInquiry(), a btLibManagementEventInquiryCanceled event is generated.

See Also

BtLibCancelInquiry()