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
BtLibClassOfDeviceType Typedef
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
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
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
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
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
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
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
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
Masks
These constants define bit masks to isolate certain fields of the device class.
A mask to isolate the major service class field from the other fields of the device class. |
|
A mask to isolate the major device class field from the other fields of the device class. |
|
A mask to isolate the minor device class field from the other fields of the device class. |
|
Used as a device filter for the |
|
Used as a device filter for the |
|
Used as a device filter for the |
|
Used as a device filter for the |
|
Used as a device filter for the |
|
Used as a device filter for the |
|
Used as a device filter for the |
BtLibDeviceAddressType Struct
Purpose
Defines the address of a Bluetooth device.
Declared In
BtLibTypes.h
Prototype
typedef struct BtLibDeviceAddressType { uint8_t address[btLibDeviceAddressSize]; } BtLibDeviceAddressType
Fields
BtLibDeviceAddressTypePtr Typedef
Purpose
A pointer to a Bluetooth address.
Declared In
BtLibTypes.h
Prototype
typedef BtLibDeviceAddressType *BtLibDeviceAddressTypePtr
BtLibFriendlyNameType Struct
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.
BtLibFriendlyNameTypePtr Typedef
Purpose
Defines a pointer to a friendly Bluetooth device name.
Declared In
BtLibTypes.h
Prototype
typedef BtLibFriendlyNameType *BtLibFriendlyNameTypePtr
BtLibL2CapChannelIdType Typedef
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
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
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
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
, andbtLibManagementEventAuthenticationComplete
. -
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 aBtLibFriendlyNameType
structure. Used by thebtLibManagementEventNameResult
andbtLibManagementEventLocalNameChange
events. -
inquiryResult
- Information about a single device found during an inquiry procedure.
bdAddr
contains the address of the device found andclassOfDevice
identifies the device class.padding
is reserved for system use. The data part of the message contains a structure of typeBtLibFriendlyNameType
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 thebtLibManagementEventInquiryResult
-
modeChange
- Used by the
btLibManagementEventModeChange
event.bdAddr
specifies the address of an ACL link whose mode has changed.curMode
indicates the new current mode, andinterval
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, andenabled
indicates whether encryption is on or off. -
roleChange
- Used by
btLibManagementEventRoleChange
.bdAddr
indicates the address of the device whose role has changed, andnewRole
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
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
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
andchannel
.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
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
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
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
Purpose
The BtLibSdpAttributeIdType
type represents a SDP attribute identifier.
Declared In
BtLibTypes.h
Prototype
typedef uint16_t BtLibSdpAttributeIdType
BtLibSdpRecordHandle Typedef
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
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
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
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
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
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
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
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
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
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
andBT_RF_MAXFRAMESIZE
. If your application can handle any frame size, set this value toBT_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.
-
padding
- Reserved for system use.
See Also
BtLibSocketSend()
, BtLibSocketClose()
BtLibSocketEventType Struct
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
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
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 toBT_L2CAP_RANDOM_PSM
, theBtLibSocketListen
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 callBtLibSocketListen
. -
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
andBT_RF_MAXFRAMESIZE
. If your application can handle any frame size, set this value toBT_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
BtLibSocketRef Typedef
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
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
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
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
Bluetooth Data Element Sizes
Purpose
Define the possible sizes of Bluetooth Data Elements.
Declared In
BtLibTypes.h
Constants
-
Table 13.10 Bluetooth Data Element sizes
See Also
"Bluetooth Data Element Types"
Bluetooth Data Element Types
Purpose
Define the types of Data Elements supported by the Bluetooth system.
Declared In
BtLibTypes.h
Constants
See Also
"Bluetooth Data Element Sizes"
Bluetooth Device Names
Purpose
Define the names of Bluetooth STREAMS devices.
Declared In
BtLibTypes.h
Constants
Bluetooth Disconnection Codes
Purpose
Values for the status field of btLibSocketEventDisconnected
events, which explain why the disconnect occurred.
Declared In
BtLibTypes.h
Constants
Bluetooth Error Codes
Purpose
Error codes that can occur when issuing Bluetooth calls.
Declared In
BtLibTypes.h
Constants
Bluetooth Module Names
Purpose
Names of the Bluetooth STREAMS modules.
Declared In
BtLibTypes.h
Constants
BSD Sockets Constants
Purpose
Constants used when utilizing the BSD Sockets API.
Declared In
BtLibTypes.h
Constants
Character Encoding Constants
Purpose
Define character encodings for Bluetooth.
Declared In
BtLibTypes.h
Constants
L2Cap Constants
Purpose
Constants for the L2Cap protocol.
Declared In
BtLibTypes.h
Constants
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
Purpose
Define languages supported by the Bluetooth system.
Declared In
BtLibTypes.h
Constants
Management Event Status Codes
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
Miscellaneous Bluetooth Constants
Purpose
These constants don't fit into other categories, but are important nonetheless.
Declared In
BtLibTypes.h
Constants
Attribute Identifier Constants
Purpose
Define offsets for human-readable attributes that can be provided in multiple languages.
Declared In
BtLibTypes.h
Constants
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
Purpose
Raw values for protocol UUIDs that are predefined by the Bluetooth specification.
Declared In
BtLibTypes.h
Constants
RfComm Constants
Purpose
Constants for the RfCommprotocol.
Declared In
BtLibTypes.h
Constants
Service Class UUIDs
Purpose
Raw values for service class UUIDs predefined by the Bluetooth specification.
Declared In
BtLibTypes.h
Constants
Service Description Flags
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
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
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
BtLibGeneralPrefEnum Enum
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
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
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
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
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 orbtLibErrCanceled
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
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
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
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. Thestatus
field isbtLibErrNoError
if the connection has completed successfully. Otherwise, thestatus
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 thestatus
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
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 aBtLibProtocolEnum
representing the socket's protocol. -
btLibSocketInfo_RemoteDeviceAddress
-
BtLibSocketGetInfo()
returns aBtLibDeviceAddressType
representing the address of the device at the other end of this socket. -
btLibSocketInfo_SendPending = 100
-
BtLibSocketGetInfo()
returns aBoolean
indicating whether a send is currently in progress. -
btLibSocketInfo_MaxTxSize
-
BtLibSocketGetInfo()
returns auint32_t
representing the maximum packet size the local device can transmit. -
btLibSocketInfo_MaxRxSize
-
BtLibSocketGetInfo()
returns auint32_t
representing the maximum packet size the local device can receive. -
btLibSocketInfo_L2CapPsm = 200
-
BtLibSocketGetInfo()
returns aBtLibL2CapPsmType
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 aBtLibL2CapChannelIdType
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 aBtLibRfCommServerIdType
that represents the socket's RfComm server channel. This information is valid for RfComm sockets only. -
btLibSocketInfo_RfCommOutstandingCredits
-
BtLibSocketGetInfo()
returns auint16_t
containing the number of remaining credits on this socket. This information is valid for RfComm sockets only. -
btLibSocketInfo_SdpServiceRecordHandle = 400
-
BtLibSocketGetInfo()
returns theBtLibSdpRemoteServiceRecordHandle
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
Purpose
Service attributes whose definitions are common to all service records.
Declared In
BtLibTypes.h
Constants
A language attribute ID list. See "Attribute Identifier Constants."
A language attribute ID list. See "Attribute Identifier Constants." |
|
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
sysBtLaunchCmdDoServiceUI
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
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
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
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
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 BtLibSdp
xxx() 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
Bluetooth Functions and Macros
BtLibAddrAToBtd Function
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
Returns
Pointer to a BtLibDeviceAddressType
to store the converted device address.
Returns
Returns btLibErrNoError
to indicate that the conversion was successful.
See Also
BtLibAddrBtdToA Function
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_tstrBufSize
)
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
isNULL
-
strBuf
isNULL
-
strBufSize
is less than 18, the number of bytes required to store the ASCII formatted address
BtLibCancelInquiry Function
Purpose
Cancel a Bluetooth inquiry in process.
Declared In
BtLib.h
Prototype
status_t BtLibCancelInquiry (
int32_t fdME
)
Parameters
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
BtLibClose Function
Purpose
Close the Bluetooth Management Entity.
Declared In
BtLib.h
Prototype
status_t BtLibClose (
int32_t fdME
)
Parameters
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
BtLibDiscoverDevices Function
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_tfdME
, char*instructionTxt
, char*buttonTxt
, BooleanaddressAsName
, BtLibClassOfDeviceType*filterTable
, uint8_tfilterTableLen
, BooleanhideFavorites
, BtLibDeviceAddressType*deviceTable
, uint8_tdeviceTableLen
, 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 thedeviceTableLen
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
Purpose
Get one of the general management preferences.
Declared In
BtLib.h
Prototype
status_t BtLibGetGeneralPreference ( int32_tfdME
, BtLibGeneralPrefEnumpref
, void*prefValueP
, uint16_tprefValueSize
)
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
BtLibGetRemoteDeviceName Function
Purpose
Get the name of the remote device with the specified address.
Declared In
BtLib.h
Prototype
status_t BtLibGetRemoteDeviceName ( int32_tfdME
, BtLibDeviceAddressType*remoteDeviceP
, BtLibGetNameEnumretrievalMethod
)
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
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_tfdME
, BtLibDeviceAddressType*remoteDeviceP
, BtLibGetNameEnumretrievalMethod
, char*buffer
, size_tbufferLen
)
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
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
Returns
Returns x
in L2Cap byte order.
See Also
BtLibL2CapHToNS()
, BtLibL2CapNToHL()
, BtLibL2CapNToHS()
BtLibL2CapHToNS Macro
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
Returns
Returns x
in L2Cap byte order.
See Also
BtLibL2CapHToNL()
, BtLibL2CapNToHS()
, BtLibL2CapNToHL()
BtLibL2CapNToHL Macro
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
Returns
See Also
BtLibL2CapNToHS()
, BtLibL2CapHToNL()
, BtLibL2CapHToNS()
BtLibL2CapNToHS Macro
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
Returns
See Also
BtLibL2CapNToHL()
, BtLibL2CapHToNS()
, BtLibL2CapNToHL()
BtLibLinkConnect Function
Purpose
Create a Bluetooth Asynchronous Connectionless (ACL) link.
Declared In
BtLib.h
Prototype
status_t BtLibLinkConnect ( int32_tfdME
, 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 Function
Purpose
Disconnect an existing ACL Link.
Declared In
BtLib.h
Prototype
status_t BtLibLinkDisconnect ( int32_tfdME
, 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
BtLibLinkGetState Function
Purpose
Declared In
BtLib.h
Prototype
status_t BtLibLinkGetState ( int32_tfdME
, BtLibDeviceAddressType*remoteDeviceP
, BtLibLinkPrefsEnumpref
, void*linkStateP
, uint16_tlinkStateSize
)
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
. SeeBtLibLinkPrefsEnum
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
BtLibLinkSetState Function
Purpose
Declared In
BtLib.h
Prototype
status_t BtLibLinkSetState ( int32_tfdME
, BtLibDeviceAddressType*remoteDeviceP
, BtLibLinkPrefsEnumpref
, void*linkStateP
, uint16_tlinkStateSize
)
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. SeeBtLibLinkPrefsEnum
. -
→ 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
BtLibMEEventName Function
Purpose
Return the name of the specified Management Entity event code.
Declared In
BtLib.h
Prototype
const char *BtLibMEEventName (
BtLibManagementEventEnum event
)
Parameters
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
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
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
BtLibPiconetCreate Function
Purpose
Set up the local device to be the master of a piconet.
Declared In
BtLib.h
Prototype
status_t BtLibPiconetCreate ( int32_tfdME
, BooleanunlockInbound
, Booleandiscoverable
)
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. Iffalse
, 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 ifunlockInbound
isfalse
.
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
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
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
BtLibPiconetLockInbound Function
Purpose
Prevent remote devices from creating ACL links into the piconet.
Declared In
BtLib.h
Prototype
status_t BtLibPiconetLockInbound (
int32_t fdME
)
Parameters
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 Function
Purpose
Allow remote devices to create ACL links into the piconet.
Declared In
BtLib.h
Prototype
status_t BtLibPiconetUnlockInbound ( int32_tfdME
, Booleandiscoverable
)
Parameters
-
→ fdME
- The ME's file descriptor.
-
→ discoverable
- If
true
, configures the radio to be discoverable. In other words, the radio responds to inquiries. Iffalse
, 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
BtLibRegisterService Function
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
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
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
Returns
Returns x
in RfComm byte order.
See Also
BtLibRfCommHToNS()
, BtLibRfCommNToHL()
, BtLibRfCommNToHS()
BtLibRfCommHToNS Macro
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
Returns
Returns x
in RfComm byte order.
See Also
BtLibRfCommHToNL()
, BtLibRfCommNToHL()
, BtLibRfCommNToHS()
BtLibRfCommNToHL Macro
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
Returns
See Also
BtLibRfCommNToHS()
, BtLibRfCommHToNL()
, BtLibRfCommHToNS()
BtLibRfCommNToHS Macro
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
Returns
See Also
BtLibRfCommNToHL()
, BtLibRfCommHToNL()
, BtLibRfCommHToNS()
BtLibSdpCompareUuids Function
Purpose
Declared In
BtLib.h
Prototype
status_t BtLibSdpCompareUuids ( int32_tfdME
, 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
Purpose
Get an available L2Cap PSM using SDP.
Declared In
BtLib.h
Prototype
status_t BtLibSdpGetPsmByUuid ( BtLibSocketRefsocketRef
, BtLibDeviceAddressType*rDev
, BtLibSdpUuidType*serviceUUIDList
, uint8_tuuidListLen
)
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
Purpose
Macro that returns a constant representing the data element's size.
Declared In
BtLib.h
Prototype
BtLibSdpGetRawDataElementSize (
header
)
Parameters
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
Purpose
Macro that returns an SDP data element's type.
Declared In
BtLib.h
Prototype
BtLibSdpGetRawElementType (
header
)
Parameters
Returns
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
Purpose
Get an available RfComm server channel using SDP.
Declared In
BtLib.h
Prototype
status_t BtLibSdpGetServerChannelByUuid ( BtLibSocketRefsocketRef
, BtLibDeviceAddressType*rDev
, BtLibSdpUuidType*serviceUUIDList
, uint8_tuuidListLen
)
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
BtLibSdpHToNL Macro
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
Returns
See Also
BtLibSdpHToNS()
, BtLibSdpNToHL()
, BtLibSdpNToHS()
BtLibSdpHToNS Macro
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
Returns
See Also
BtLibSdpHToNL()
, BtLibSdpNToHL()
, BtLibSdpNToHS()
BtLibSdpNToHL Macro
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
Returns
See Also
BtLibSdpNToHS()
, BtLibSdpHToNL()
, BtLibSdpHToNS()
BtLibSdpNToHS Macro
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
Returns
See Also
BtLibSdpNToHL()
, BtLibSdpHToNL()
, BtLibSdpHToNS()
BtLibSdpParseRawDataElement Function
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_tfdME
, 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
, orlength
isNULL
. -
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
Purpose
Allocate a memory chunk that represents an SDP service record.
Declared In
BtLib.h
Prototype
status_t BtLibSdpServiceRecordCreate ( int32_tfdME
, BtLibSdpRecordHandle*recordH
)
Parameters
Returns
Returns one of the following values:
-
btLibErrNoError
- Success.
-
btLibErrOutOfMemory
- Not enough memory to allocate the memory chunk.
-
btLibErrParamError
-
recordH
isNULL
. -
iosErrBadFd
- The specified file descriptor is invalid.
-
iosErrNotOpened
- The specified file descriptor is not open.
See Also
BtLibSdpServiceRecordDestroy()
, BtLibSdpServiceRecordStartAdvertising()
, BtLibSdpServiceRecordStopAdvertising()
BtLibSdpServiceRecordDestroy Function
Purpose
Free the memory associated with a SDP memory record.
Declared In
BtLib.h
Prototype
status_t BtLibSdpServiceRecordDestroy ( int32_tfdME
, BtLibSdpRecordHandlerecordH
)
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
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_tfdME
, BtLibSdpRecordHandlerecordH
, BtLibSdpAttributeIdTypeattributeID
, BtLibSdpAttributeDataType*attributeValue
, uint16_tlistNumber
, uint16_tlistEntry
)
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 orattributeValues
isNULL
. -
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
Purpose
Get the number of entries in a list attribute.
Declared In
BtLib.h
Prototype
status_t BtLibSdpServiceRecordGetNumListEntries ( int32_tfdME
, BtLibSdpRecordHandlerecordH
, BtLibSdpAttributeIdTypeattributeID
, uint16_tlistNumber
, 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 ornumEntries
isNULL
. -
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
Purpose
Get the number of lists in a protocol descriptor list SDP attribute.
Declared In
BtLib.h
Prototype
status_t BtLibSdpServiceRecordGetNumLists ( int32_tfdME
, BtLibSdpRecordHandlerecordH
, BtLibSdpAttributeIdTypeattributeID
, 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 ornumLists
isNULL
. -
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
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_tfdME
, BtLibSdpRecordHandlerecordH
, BtLibSdpAttributeIdTypeattributeID
, 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
isNULL
,valSize
is0
, or the size of the attribute value is larger thanvalSize
. -
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
Purpose
Return the size, in bytes, of any attribute of an SDP memory record.
Declared In
BtLib.h
Prototype
status_t BtLibSdpServiceRecordGetSizeOfRawAttribute ( int32_tfdME
, BtLibSdpRecordHandlerecordH
, BtLibSdpAttributeIdTypeattributeID
, 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 beNULL
.
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 orsize
isNULL
. -
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
Purpose
Get the length of a string or URL attribute in a SDP memory record.
Declared In
BtLib.h
Prototype
status_t BtLibSdpServiceRecordGetStringOrUrlLength ( int32_tfdME
, BtLibSdpRecordHandlerecordH
, BtLibSdpAttributeIdTypeattributeID
, 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 beNULL
.
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
isNULL
, 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
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 ( BtLibSocketRefsocketRef
, BtLibDeviceAddressType*rDev
, BtLibSdpRemoteServiceRecordHandleremoteHandle
, BtLibSdpRecordHandlerecordH
)
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
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_tfdME
, BtLibSdpRecordHandlerecordH
, BtLibSdpAttributeIdTypeattributeID
, BtLibSdpAttributeDataType*attributeValue
, uint16_tlistNumber
, uint16_tlistEntry
)
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 orattributeValue
isNULL
. -
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
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( BtLibSocketRefsocketRef
, BtLibSdpUuidType*serviceUuidList
, uint8_tuuidListLen
, const char*serviceName
, uint16_tserviceNameLen
, BtLibSdpRecordHandlerecordH
)
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
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_tfdME
, BtLibSdpRecordHandlerecordH
, BtLibSdpAttributeIdTypeattributeID
, const uint8_t*value
, uint16_tvalSize
)
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
isNULL
, orvalSize
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
Purpose
Get the service record handles corresponding to the service classes advertised on a remote device.
Declared In
BtLib.h
Prototype
status_t BtLibSdpServiceRecordsGetByServiceClass ( BtLibSocketRefsocketRef
, BtLibDeviceAddressType*rDev
, BtLibSdpUuidType*uuidList
, uint16_tuuidListLen
)
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
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_tfdME
, BtLibSdpRecordHandlerecordH
)
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
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_tfdME
, BtLibSdpRecordHandlerecordH
)
Parameters
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
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 therawValue
array.
Returns
BtLibSdpVerifyRawDataElement Function
Purpose
Verify that a raw SDP data element is properly formed.
Declared In
BtLib.h
Prototype
status_t BtLibSdpVerifyRawDataElement ( int32_tfdME
, const uint8_t*value
, uint16_tvalSize
, uint8_tmaxLevel
)
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
isNULL
. -
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
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_tfdME
, 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
Purpose
Get information from a device record in the device database.
Declared In
BtLib.h
Prototype
status_t BtLibSecurityGetTrustedDeviceRecordInfo ( int32_tfdME
, uint16_tindex
, BtLibDeviceAddressType*addrP
, char*nameBuffer
, uint8_tnameBufferSize
, 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 aNULL
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. Iffalse
, the device is paired but not bonded—it will need to reauthenticate if it connects again. Provide aNULL
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
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_tfdME
, BooleantrustedOnly
, 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
Purpose
Removes a device from the device database.
Declared In
BtLib.h
Prototype
status_t BtLibSecurityRemoveTrustedDeviceRecord ( int32_tfdME
, uint16_tindex
)
Parameters
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
Purpose
Set one of the general management preferences.
Declared In
BtLib.h
Prototype
status_t BtLibSetGeneralPreference ( int32_tfdME
, BtLibGeneralPrefEnumpref
, void*prefValueP
, uint16_tprefValueSize
)
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
. SeeBtLibGeneralPrefEnum
. -
→ 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
BtLibSocketAdvanceCredit Function
Purpose
Advance credit to a given RfComm connection socket.
Declared In
BtLib.h
Prototype
status_t BtLibSocketAdvanceCredit ( BtLibSocketRefsocketRef
, uint8_tcredit
)
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
Purpose
Close a socket, free associated resources, and kill all associated socket connections.
Declared In
BtLib.h
Prototype
status_t BtLibSocketClose (
BtLibSocketRef socketRef
)
Parameters
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
Purpose
Create an outbound L2Cap, RfComm, SCO, or BNEP connection.
Declared In
BtLib.h
Prototype
status_t BtLibSocketConnect ( BtLibSocketRefsocketRef
, 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
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
, BtLibProtocolEnumsocketProtocol
)
Parameters
-
← socketRefP
- Pointer to an allocated
BtLibSocketRef
that will receive the socket value on return. This pointer must not beNULL
. -
→ socketProtocol
- The protocol (L2Cap, RFComm, or SDP) to use on the socket.
Returns
Returns one of the following values:
-
btLibErrNoError
- Success.
-
btLibErrParamError
-
socketRefP
isNULL
. -
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.
See Also
BtLibSocketConnect()
, BtLibSocketListen()
, BtLibSocketClose()
BtLibSocketEventName Function
Purpose
Return the name of the given socket event code.
Declared In
BtLib.h
Prototype
const char *BtLibSocketEventName (
BtLibSocketEventEnum event
)
Parameters
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
Purpose
Retrieve information for a currently open socket.
Declared In
BtLib.h
Prototype
status_t BtLibSocketGetInfo ( BtLibSocketRefsocketRef
, BtLibSocketInfoEnuminfoType
, void*valueP
, uint32_tvalueSize
)
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
Purpose
Set up an L2Cap, RFComm, SCO, or BNEP socket as a listener.
Declared In
BtLib.h
Prototype
status_t BtLibSocketListen ( BtLibSocketRefsocketRef
, BtLibSocketListenInfoType*listenInfoP
)
Parameters
-
→ socketRef
- The socket to listen on.
-
↔ listenInfoP
- Protocol-specific listening information. For more information see
BtLibSocketListenInfoType
. This parameter must beNULL
if the socket is an SCO socket, otherwise it must not beNULL
.
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
isNULL
. -
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
BtLibSocketRespondToConnection Function
Purpose
Accept or reject an in-bound connection on a given listener socket.
Declared In
BtLib.h
Prototype
status_t BtLibSocketRespondToConnection ( BtLibSocketRefsocketRef
, Booleanaccept
)
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
isfalse
. -
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
Purpose
Send data over a connected L2Cap, RfComm, BNEP socket.
Declared In
BtLib.h
Prototype
status_t BtLibSocketSend ( BtLibSocketRefsocketRef
, uint8_t*data
, uint32_tdataLen
)
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
BtLibStartInquiry Function
Purpose
Declared In
BtLib.h
Prototype
status_t BtLibStartInquiry ( int32_tfdME
, uint8_ttimeOut
, uint8_tmaxResp
)
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.