(68K) Bluetooth Library: Sockets and Service Discovery | Palm OS® Programmer's API Reference

The Bluetooth library uses sockets to represent L2CAP, RFCOMM, and SDP connections. This chapter presents reference material for the socket and SDP support provided by the Bluetooth library API:

Socket-Related Data Structures: This section lists some of the more important types used by the Bluetooth library.
Socket Callback Events: The Bluetooth library socket API supports L2CAP, RFCOMM, and SDP, the upper protocols of the Bluetooth specification. As with the management functions, the socket functions are mostly asynchronous. To signal to the application that socket operations have completed, the Bluetooth library generates socket callback events by calling a callback function.
Socket Disconnection Error Codes: In addition to the standard error codes that can accompany socket events, the status codes accompanying the disconnection and connection events can have the additional values enumerated in this section.
Socket Functions: The functions in this section perform general socket tasks and tasks related to L2CAP and RFCOMM sockets. The functions specific to SDP sockets are in the next section.
Service Discovery Protocol Functions: This section describes functions and macros specific to the Bluetooth Service Discovery Protocol (SDP).
Application-Defined Functions: This section describes the callback functions that handle socket events.

The header file BtLib.h declares the Bluetooth library functions and macros. The header file BtLibTypes.h declares the data structures that you use with those functions and macros.

Socket-Related Data Structures ^TOP^

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

BtLibL2CapPsmType Typedef ^TOP^

Purpose

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

Prototype

typedef UInt16 BtLibL2CapPsmType;

BtLibLanguageBaseTripletType Struct ^TOP^

Purpose

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

Prototype

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

Fields

naturalLanguageIdentifier: A UInt16 representing a natural language. See Language Constants for a set of constants that can be used in this field.
characterEncoding: A UInt16 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 Offsets for offsets that are added to this value to get the attribute identifiers for specific attributes represented in this language.

Language Constants

These constants are used in the naturalLanguageIdentifier field of the BtLibLanguageBaseTripletType and are defined in the ISO 639:1988 specification.

Constants

btLibLangAfar
btLibLangAbkihazian
btLibLangAfrikaans
btLibLangAmharic
btLibLangArabic
btLibLangAssamese
btLibLangAymara
btLibLangAzerbaijani
btLibLangBashkir
btLibLangByelorussian
btLibLangBulgarian
btLibLangBihari
btLibLangBislama
btLibLangBengali
btLibLangTibetan
btLibLangBreton
btLibLangCatalan
btLibLangCorsican
btLibLangCzech
btLibLangWelsh
btLibLangDanish
btLibLangGerman
btLibLangBhutani
btLibLangGreek
btLibLangEnglish
btLibLangEsperanto
btLibLangSpanish
btLibLangEstonian
btLibLangBasque
btLibLangPersian
btLibLangFinnish
btLibLangFiji
btLibLangFaroese
btLibLangFrench
btLibLangFrisian
btLibLangIrish
btLibLangScotsGaelic
btLibLangGalician
btLibLangGuarani
btLibLangGujarati
btLibLangHausa
btLibLangHindi
btLibLangCroation
btLibLangHungarian
btLibLangArmenian
btLibLangInterlingua
btLibLangInterlingue
btLibLangInupiak
btLibLangIndonesian
btLibLangIcelandic
btLibLangItalian
btLibLangHebrew
btLibLangJapanese
btLibLangYiddish
btLibLangJavanese
btLibLangGeorgian
btLibLangKazakh
btLibLangGreenlandic
btLibLangCambodian
btLibLangKannada
btLibLangKorean
btLibLangKashmiri
btLibLangKurdish
btLibLangKirghiz
btLibLangLatin
btLibLangLingala
btLibLangLaothian
btLibLangLithuanian
btLibLangLatvian
btLibLangMalagasy
btLibLangMaori
btLibLangMacedonian
btLibLangMalayalam
btLibLangMongolian
btLibLangMoldavian
btLibLangMarathi
btLibLangMalay
btLibLangMaltese
btLibLangBurmese
btLibLangNaura
btLibLangNepali
btLibLangDutch
btLibLangNorwegian
btLibLangOccitan
btLibLangOromo
btLibLangOriya
btLibLangPunjabi
btLibLangPolish
btLibLangPashto
btLibLangPortuguese
btLibLangQuechua
btLibLangRhaeto_Romance
btLibLangKirundi
btLibLangRomanian
btLibLangRussian
btLibLangKinyarwanda
btLibLangSanskrit
btLibLangSindhi
btLibLangSangho
btLibLangSerbo_Croation
btLibLangSinghalese
btLibLangSlovak
btLibLangSlovenian
btLibLangSamoan
btLibLangShona
btLibLangSomali
btLibLangAlbanian
btLibLangSerbian
btLibLangSiswati
btLibLangSesotho
btLibLangSundanese
btLibLangSwedish
btLibLangSwahili
btLibLangTamil
btLibLangTelugu
btLibLangTajik
btLibLangThai
btLibLangTigrinya
btLibLangTurkmen
btLibLangTagalog
btLibLangSetswanna
btLibLangTonga
btLibLangTurkish
btLibLangTsonga
btLibLangTatar
btLibLangTwi
btLibLangUkranian
btLibLangUrdu
btLibLangUzbek
btLibLangVietnamese
btLibLangVolapuk
btLibLangWolof
btLibLangXhosa
btLibLangYoruba
btLibLangChinese
btLibLangZulu

Character Encoding Constants

These constants are used to specify the character encoding used for SDP attributes. More information about these character sets can be found at http://www.iana.org/assignments/character-sets.

Constants

btLibCharSet_US_ASCII
btLibCharSet_Adobe_Standard_Encoding
btLibCharSet_Adobe_Symbol_Encoding
btLibCharSet_ANSI_X3_110_1983
btLibCharSet_ASMO_449
btLibCharSet_Big5
btLibCharSet_Big5_HKSCS
btLibCharSet_BS_4730
btLibCharSet_BS_viewdata
btLibCharSet_CSA_Z243_4_1985_1
btLibCharSet_CSA_Z243_4_1985_2
btLibCharSet_CSA_Z243_4_1985_gr
btLibCharSet_CSN_369103
btLibCharSet_DEC_MCS
btLibCharSet_DIN_66003
btLibCharSet_dk_us
btLibCharSet_DS_2089
btLibCharSet_EBCDIC_AT_DE
btLibCharSet_EBCDIC_AT_DE_A
btLibCharSet_EBCDIC_CA_FR
btLibCharSet_EBCDIC_DK_NO
btLibCharSet_EBCDIC_DK_NO_A
btLibCharSet_EBCDIC_ES
btLibCharSet_EBCDIC_ES_A
btLibCharSet_EBCDIC_ES_S
btLibCharSet_EBCDIC_FI_SE
btLibCharSet_EBCDIC_FI_SE_A
btLibCharSet_EBCDIC_FR
btLibCharSet_EBCDIC_IT
btLibCharSet_EBCDIC_PT
btLibCharSet_EBCDIC_UK
btLibCharSet_EBCDIC_US
btLibCharSet_ECMA_cyrillic
btLibCharSet_ES 23
btLibCharSet_ES2
btLibCharSet_EUC_JP
btLibCharSet_EUC_KR
btLibCharSet_Extended_UNIX_Code_Fixed_Width_for_Japanese
btLibCharSet_GB2312
btLibCharSet_GB_1988_80
btLibCharSet_GB_2312_80
btLibCharSet_GOST_19768_74
btLibCharSet_greek7
btLibCharSet_greek7_old
btLibCharSet_greek_ccitt
btLibCharSet_HP_DeskTop
btLibCharSet_HP_Legal
btLibCharSet_HP_Math8
btLibCharSet_HP_Pi_font
btLibCharSet_hp_roman8
btLibCharSet_HZ_GB_2312
btLibCharSet_IBM037
btLibCharSet_IBM038
btLibCharSet_IBM273
btLibCharSet_IBM274
btLibCharSet_IBM275
btLibCharSet_IBM277
btLibCharSet_IBM278
btLibCharSet_IBM280
btLibCharSet_IBM281
btLibCharSet_IBM284
btLibCharSet_IBM285
btLibCharSet_IBM290
btLibCharSet_IBM297
btLibCharSet_IBM420
btLibCharSet_IBM423
btLibCharSet_IBM424
btLibCharSet_IBM437
btLibCharSet_IBM500
btLibCharSet_IBM775
btLibCharSet_IBM850
btLibCharSet_IBM851
btLibCharSet_IBM852
btLibCharSet_IBM855
btLibCharSet_IBM857
btLibCharSet_IBM860
btLibCharSet_IBM861
btLibCharSet_IBM862
btLibCharSet_IBM863
btLibCharSet_IBM864
btLibCharSet_IBM865
btLibCharSet_IBM866
btLibCharSet_IBM868
btLibCharSet_IBM869
btLibCharSet_IBM870
btLibCharSet_IBM871
btLibCharSet_IBM880
btLibCharSet_IBM891
btLibCharSet_IBM903
btLibCharSet_IBM904
btLibCharSet_IBM905
btLibCharSet_IBM918
btLibCharSet_IBM1026
btLibCharSet_IBM00858
btLibCharSet_IBM00924
btLibCharSet_IBM01140
btLibCharSet_IBM01141
btLibCharSet_IBM01142
btLibCharSet_IBM01143
btLibCharSet_IBM01144
btLibCharSet_IBM01145
btLibCharSet_IBM01146
btLibCharSet_IBM01147
btLibCharSet_IBM01148
btLibCharSet_IBM01149
btLibCharSet_IBM_Symbols
btLibCharSet_IBM_Thai
btLibCharSet_IEC_P27_1
btLibCharSet_INIS
btLibCharSet_INIS_8
btLibCharSet_INIS_cyrillic
btLibCharSet_INVARIANT
btLibCharSet_ISO_646_basic_1983
btLibCharSet_ISO_646_irv_1983
btLibCharSet_ISO_2022_CN
btLibCharSet_ISO_2022_CN_EXT
btLibCharSet_ISO_2022_JP
btLibCharSet_ISO_2022_JP_2
btLibCharSet_ISO_2022_KR
btLibCharSet_ISO_2033_1983
btLibCharSet_ISO_5427
btLibCharSet_ISO_5427_1981
btLibCharSet_ISO_5428_1980
btLibCharSet_ISO_6937_2_25
btLibCharSet_ISO_6937_2_add
btLibCharSet_ISO_8859_1
btLibCharSet_ISO_8859_10
btLibCharSet_iso_8859_13
btLibCharSet_iso_8859_14
btLibCharSet_ISO_8859_15
btLibCharSet_ISO_8859_1_Windows_3_0_Latin_1
btLibCharSet_ISO_8859_1_Windows_3_1_Latin_1
btLibCharSet_ISO_8859_2
btLibCharSet_ISO_8859_2_Windows_Latin_2
btLibCharSet_ISO_8859_3
btLibCharSet_ISO_8859_4
btLibCharSet_ISO_8859_5
btLibCharSet_ISO_8859_6
btLibCharSet_ISO_8859_6_E
btLibCharSet_ISO_8859_6_I
btLibCharSet_ISO_8859_7
btLibCharSet_ISO_8859_8
btLibCharSet_ISO_8859_8_E
btLibCharSet_ISO_8859_8_I
btLibCharSet_ISO_8859_9
btLibCharSet_ISO_8859_9_Windows_Latin_5
btLibCharSet_ISO_8859_supp
btLibCharSet_ISO_10367_box
btLibCharSet_ISO_10646_UCS_2
btLibCharSet_ISO_10646_UCS_4
btLibCharSet_ISO_10646_UCS_Basic
btLibCharSet_ISO_10646_Unicode_Latin1
btLibCharSet_ISO_10646_UTF_1
btLibCharSet_iso_ir_90
btLibCharSet_ISO_Unicode_IBM_1261
btLibCharSet_ISO_Unicode_IBM_1264
btLibCharSet_ISO_Unicode_IBM_1265
btLibCharSet_ISO_Unicode_IBM_1268
btLibCharSet_ISO_Unicode_IBM_1276
btLibCharSet_IT
btLibCharSet_JIS_C6220_1969_jp
btLibCharSet_JIS_C6220_1969_ro
btLibCharSet_JIS_C6226_1978
btLibCharSet_JIS_C6226_1983
btLibCharSet_JIS_C6229_1984_a
btLibCharSet_JIS_C6229_1984_b
btLibCharSet_JIS_C6229_1984_b_add
btLibCharSet_JIS_C6229_1984_hand
btLibCharSet_JIS_C6229_1984_hand_add
btLibCharSet_JIS_C6229_1984_kana
btLibCharSet_JIS_Encoding
btLibCharSet_JIS_X0201
btLibCharSet_JIS_X0212_1990
btLibCharSet_JUS_I_B1_002
btLibCharSet_JUS_I_B1_003_mac
btLibCharSet_JUS_I_B1_003_serb
btLibCharSet_KOI8_R
btLibCharSet_KOI8_U
btLibCharSet_KSC5636
btLibCharSet_KS_C_5601_1987
btLibCharSet_latin_greek
btLibCharSet_Latin_greek_1
btLibCharSet_latin_lap
btLibCharSet_macintosh
btLibCharSet_Microsoft_Publishing
btLibCharSet_MNEM
btLibCharSet_MNEMONIC
btLibCharSet_MSZ_7795_3
btLibCharSet_NATS_DANO
btLibCharSet_NATS_DANO_ADD
btLibCharSet_NATS_SEFI
btLibCharSet_NATS_SEFI_ADD
btLibCharSet_NC_NC00_10_81
btLibCharSet_NF_Z_62_010
btLibCharSet_NF_Z_62_010__1973_
btLibCharSet_NS_4551_1
btLibCharSet_NS_4551_2
btLibCharSet_PC8_Danish_Norwegian
btLibCharSet_PC8_Turkish
btLibCharSet_PT
btLibCharSet_PT2
btLibCharSet_SCSU
btLibCharSet_SEN_850200_B
btLibCharSet_SEN_850200_C
btLibCharSet_Shift_JIS
btLibCharSet_TIS_620
btLibCharSet_T_101_G2
btLibCharSet_T_61_7bit
btLibCharSet_T_61_8bit
btLibCharSet_UNICODE_1_1
btLibCharSet_UNICODE_1_1_UTF_7
btLibCharSet_UNKNOWN_8BIT
btLibCharSet_us_dk
btLibCharSet_UTF_16
btLibCharSet_UTF_16BE
btLibCharSet_UTF_16LE
btLibCharSet_UTF_7
btLibCharSet_UTF_8
btLibCharSet_Ventura_International
btLibCharSet_Ventura_Math
btLibCharSet_Ventura_US
btLibCharSet_videotex_suppl
btLibCharSet_VIQR
btLibCharSet_VISCII
btLibCharSet_Windows_31J
btLibCharSet_windows_1250
btLibCharSet_windows_1251
btLibCharSet_windows_1252
btLibCharSet_windows_1253
btLibCharSet_windows_1254
btLibCharSet_windows_1255
btLibCharSet_windows_1256
btLibCharSet_windows_1257
btLibCharSet_windows_1258

Attribute Identifier Offsets

Constants

btLibServiceNameOffset: The offset from the baseAttributeID to get the attribute identifier of the service name.
btLibServiceDescriptionOffset: The offset from the baseAttributeID to get the attribute identifier of the service description.
btLibProviderNameOffset: The offset from the baseAttributeID to get the attribute identifier of the provider name.

BtLibProfileDescriptorListEntryType Struct ^TOP^

Purpose

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

Prototype

typedef struct 
BtLibProfileDescriptorListEntryType {
  BtLibSdpUuidType profUUID;
  UInt16 version;
} BtLibProfileDescriptorListEntryType;

Fields

profUUID: The UUID of the profile.
version: The version of the profile.

BtLibProtocolDescriptorListEntryType Struct ^TOP^

Purpose

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

Prototype

typedef struct 
BtLibProtocolDescriptorListEntryType {
  BtLibSdpUuidType protoUUID;
  union { 
    BtLibL2CapPsmType psm;
    BtLibRfCommServerIdType channel;
  } param;
} BtLibProtocolDescriptorListEntryType;

Fields

protoUUID: The UUID of the protocol.
param: A union containing two members: psm and channel. psm is applicable for a L2CAP protocol descriptor and specifies the Protocol and Service Multiplexor. channel is applicable to a RFCOMM protocol descriptor and specifies the server channel.

BtLibRfCommServerIdType Typedef ^TOP^

Purpose

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

Prototype

typedef UInt8 BtLibRfCommServerIdType;

BtLibSdpAttributeDataType Struct ^TOP^

Purpose

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

Prototype

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

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.

BtLibSdpAttributeIdType Typedef ^TOP^

Purpose

The BtLibSdpAttributeIdType type represents a SDP attribute identifier.

Prototype

typedef UInt16 BtLibSdpAttributeIdType;

The following constants are defined by the Bluetooth library. They represent the universal attributes in the Specification of the Bluetooth System.

Universal Attribute IDs

Constants

btLibServiceClassIdList
btLibServiceRecordState
btLibServiceId
btLibProtocolDescriptorList
btLibBrowseGroupList
btLibLanguageBaseAttributeIdList
btLibTimeToLive
btLibAvailability
btLibProfileDescriptorList
btLibDocumentationUrl
btLibClientExecutableUrl
btLibIconUrl

BtLibSdpRecordHandle Typedef ^TOP^

Purpose

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

Prototype

typedef MemHandle BtLibSdpRecordHandle;

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

BtLibSdpRemoteServiceRecordHandle Typedef ^TOP^

Purpose

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

Prototype

typedef UInt32 BtLibSdpRemoteServiceRecordHandle;

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

BtLibSdpUuidSizeEnum Enum ^TOP^

Purpose

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

Prototype

typedef enum {
  btLibUuidSize16 = 2,
  btLibUuidSize32 = 4,
  btLibUuidSize128 = 16
} BtLibSdpUuidSizeEnum;

Constants

btLibUuidSize16: 16-bit UUID
btLibUuidSize32: 32-bit UUID
btLibUuidSize128: Full size 128-bit UUID

BtLibSdpUuidType Struct ^TOP^

Purpose

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

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 BtLibSdpUuidInitialize() macro.

Prototype

typedef struct BtLibSdpUuidType {
  BtLibSdpUuidSizeEnum size;
  UInt8 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.

Predefined UUIDs

Constants

btLibSdpUUID_SC_SERVICE_DISCOVERY_SERVER
btLibSdpUUID_SC_BROWSE_GROUP_DESC
btLibSdpUUID_SC_PUBLIC_BROWSE_GROUP
btLibSdpUUID_SC_SERIAL_PORT
btLibSdpUUID_SC_LAN_ACCESS_PPP
btLibSdpUUID_SC_DIALUP_NETWORKING
btLibSdpUUID_SC_IRMC_SYNC
btLibSdpUUID_SC_OBEX_OBJECT_PUSH
btLibSdpUUID_SC_OBEX_FILE_TRANSFER
btLibSdpUUID_SC_IRMC_SYNC_COMMAND
btLibSdpUUID_SC_HEADSET
btLibSdpUUID_SC_CORDLESS_TELEPHONY
btLibSdpUUID_SC_INTERCOM
btLibSdpUUID_SC_FAX
btLibSdpUUID_SC_HEADSET_AUDIO_GATEWAY
btLibSdpUUID_SC_WAP
btLibSdpUUID_SC_WAP_CLIENT
btLibSdpUUID_SC_PNP_INFO
btLibSdpUUID_SC_GENERIC_NETWORKING
btLibSdpUUID_SC_GENERIC_FILE_TRANSFER
btLibSdpUUID_SC_GENERIC_AUDIO
btLibSdpUUID_SC_GENERIC_TELEPHONY

btLibSdpUUID_PROT_SDP
btLibSdpUUID_PROT_RFCOMM
btLibSdpUUID_PROT_TCS_BIN
btLibSdpUUID_PROT_L2CAP
btLibSdpUUID_PROT_IP
btLibSdpUUID_PROT_UDP
btLibSdpUUID_PROT_TCP
btLibSdpUUID_PROT_TCS_AT
btLibSdpUUID_PROT_OBEX
btLibSdpUUID_PROT_FTP
btLibSdpUUID_PROT_HTTP
btLibSdpUUID_PROT_WSP

BtLibSocketEventType Struct ^TOP^

Purpose

The BtLibSocketEventType structure contains detailed information regarding a socket callback 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.

Prototype

typedef struct _BtLibSocketEventType {
  BtLibSocketEventEnum event;
  BtLibSocketRef socket;
  Err status;
  union
  {
    ...
  } eventData;
} BtLibSocketEventType,
    *BtLibSocketEventTypePtr;

Fields

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

BtLibSocketRef Typedef ^TOP^

Purpose

The BtLibSocketRef type identifies a socket.

Prototype

typedef Int16 BtLibSocketRef;

BtLibStringType Struct ^TOP^

Purpose

The BtLibStringType structure represents a string in an SDP attribute.

Prototype

typedef struct BtLibStringType {
  Char *str;
  UInt16 strLen;
} BtLibStringType;

Fields

str: An array of characters representing the string. This array is not null-terminated.
strLen: The length of the string.

BtLibUrlType Struct ^TOP^

Purpose

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

Prototype

typedef struct BtLibUrlType {
  Char *url;
  UInt16 urlLen;
} BtLibUrlType;

Fields

url: An array of characters representing the URL. This array is not null-terminated.
urlLen: The length of the string.

Socket Callback Events ^TOP^

The Bluetooth library socket API supports L2CAP, RFCOMM, and SDP, the upper protocols of the Bluetooth specification. As with the management functions, the socket functions are mostly asynchronous. To signal to the application that socket operations have completed, the Bluetooth library generates a socket callback events by calling a callback function.

You specify the callback function when you create a socket. When an event occurs, the callback function is called with two parameters: a pointer to a BtLibSocketEventType structure and a pointer to a user-defined structure.

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

btLibSocketEventConnectedInbound ^TOP^

A remote connection has been accepted because the application has called BtLibSocketRespondToConnection().

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

BtLibSocketRef newSocket;

This BtLibSocketRef contains the reference to the new socket.

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 converts the listener socket into socket that exchanges data with the remote device.

btLibSocketEventConnectedOutbound ^TOP^

An outbound connection initiated by a call to BtLibSocketConnect() has completed. The status field is btLibErrNoError if the connection has completed successfully. Otherwise, the status field indicates why the connection failed.

btLibSocketEventConnectRequest ^TOP^

A remote device has requested a connection.

You must respond to this event with a call to BtLibSocketRespondToConnection().

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

BtLibDeviceAddressType requestingDevice;

This BtLibDeviceAddressType contains the address of the remote device requesting the connection.

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.

btLibSocketEventData ^TOP^

Purpose

Data has been received on a socket.

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

Prototype

struct {
  UInt16 dataLen;
  UInt8 *data;
} data;

Fields

dataLen: The size, in bytes, of the received data.
data: A pointer to the received data.

btLibSocketEventDisconnected ^TOP^

The connection has been lost or one of the devices has disconnected. The socket is now invalid. The status field indicates the reason for the disconnection.

btLibSocketEventSdpServiceRecordHandle ^TOP^

Purpose

A request for remote service records matching a list of service classes has completed. The application initiated this request by calling the BtLibSdpServiceRecordsGetByServiceClass() function.

If the status field is btLibErrNoError, the SDP operation completed successfully, and the eventData field contains valid information. Otherwise the SDP operation failed, and the status field indicates the reason for the failure.

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

Prototype

struct {
  UInt16 numSrvRec;
  BtLibSdpRemoteServiceRecordHandle
    *serviceRecordList;
} sdpServiceRecordHandles;

Fields

numSrvRec: Number of remote service record handles in the returned array.
serviceRecordList: An array of BtLibSdpRemoteServiceRecordHandles for the service records matching the service class list.

btLibSocketEventSdpGetAttribute ^TOP^

Purpose

An attribute request has completed. The application initiated this request by calling the BtLibSdpServiceRecordGetAttribute() function.

If the status field is btLibErrNoError, the operation completed successfully, and the eventData field contains valid data. Otherwise the operation failed, and the status field indicates the reason for the failure.

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

Prototype

struct {
  BtLibSdpAttributeIdType attributeID;
  BtLibSdpRecordHandle recordH;
  union {
    ...
  } info;
} sdpAttribute;

Fields

attributeID: The attribute identifier of the attribute.
recordH: A handle identifying the SDP memory record from which the attribute is retrieved.
info: A union containing information specific to the event. See The info Field.

The info Field

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

Prototype

struct {
  BtLibSdpAttributeDataType *attributeValues;
  UInt16 listNumber;
  UInt16 listEntry;
} data;

Fields

attributeValues: A BtLibSdpAttributeDataType containing the value of the attribute or list entry.
listNumber: The index of the list in which this list entry appears or 0 if the attribute is not a protocol descriptor list. The index of the first list is 0.
listEntry: The index of the list entry within the list or 0 if the attribute is not a list. The index of the first entry is 0.

btLibSocketEventSdpGetStringLen ^TOP^

Purpose

A string or URL length request has completed. The application initiated this request by calling BtLibSdpServiceRecordGetStringOrUrlLength().

If the status field is btLibErrNoError, the operation completed successfully, and length can be found in the eventData field. Otherwise the operation failed, and the status field indicates the reason for the failure.

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

Prototype

struct {
  BtLibSdpAttributeIdType attributeID;
  BtLibSdpRecordHandle recordH;
  union {
    ...
  } info;
} sdpAttribute;

Fields

attributeID: The attribute identifier of the attribute.
recordH: A handle identifying the SDP memory record from which the string length is retrieved.
info: A union containing information specific to the event. See The info Field.

The info Field

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

UInt16 strLength;

This field contains the length of the string or URL represented by the attribute. Bluetooth strings and URLs are not null-terminated.

btLibSocketEventSdpGetNumListEntries ^TOP^

Purpose

A number of list entries request has completed. The application initiated this request by calling BtLibSdpServiceRecordGetNumListEntries().

If the status field is btLibErrNoError, the operation completed successfully, and the number of list entries can be found in the eventData field. Otherwise the operation failed, and the status field indicates the reason for the failure.

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

Prototype

struct {
  BtLibSdpAttributeIdType attributeID;
  BtLibSdpRecordHandle recordH;
  union {
    ...
  } info;
} sdpAttribute;

Fields

attributeID: The attribute identifier of the attribute.
recordH: A handle identifying the SDP memory record from which the number of list entries is retrieved.
info: A union containing information specific to the event. See The info Field.

The info Field

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

UInt16 numItems;

This field contains the number of entries in the list attribute.

btLibSocketEventSdpGetNumLists ^TOP^

Purpose

A number of lists request has completed. The application initiated this request by calling BtLibSdpServiceRecordGetNumLists().

If the status field is btLibErrNoError, the operation completed successfully, and the number of lists can be found in the eventData field. Otherwise the operation failed, and the status field indicates the reason for the failure.

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

Prototype

struct {
  BtLibSdpAttributeIdType attributeID;
  BtLibSdpRecordHandle recordH;
  union {
    ...
  } info;
} sdpAttribute;

Fields

attributeID: The attribute identifier of the attribute.
recordH: A handle identifying the SDP memory record from which the number of lists is retrieved.
info: A union containing information specific to the event. See The info Field.

The info Field

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

UInt16 numItems;

This field contains the number of lists in the protocol list descriptor attribute.

btLibSocketEventSdpGetRawAttribute ^TOP^

Purpose

A get raw attribute request has completed. The application initiated the request by calling BtLibSdpServiceRecordGetRawAttribute().

If the status field is btLibErrNoError, the operation completed successfully, and the raw attribute can be found in the eventData field. Otherwise the operation failed, and the status field indicates the reason for the failure.

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

Prototype

struct {
  BtLibSdpAttributeIdType attributeID;
  BtLibSdpRecordHandle recordH;
  union {
    ...
  } info;
} sdpAttribute;

Fields

attributeID: The attribute identifier of the attribute.
recordH: A handle identifying the SDP memory record from which the raw attribute is retrieved.
info: A union containing information specific to the event. See The info Field.

The info Field

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

Prototype

struct {
  UInt16 valSize;
  UInt8 *value;
} rawData;

Fields

valSize: Number of size, in bytes, of the raw attribute value.
value: Byte array containing the raw attribute value.

btLibSocketEventSdpGetRawAttributeSize ^TOP^

Purpose

A get raw attribute size request has completed. The application initiated this request by calling BtLibSdpServiceRecordGetSizeOfRawAttribute().

If the status field is btLibErrNoError, the operation completed successfully, and the size of the attribute can be found in the eventData field. Otherwise the operation failed, and the status field indicates the reason for the failure.

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

Prototype

struct {
  BtLibSdpAttributeIdType attributeID;
  BtLibSdpRecordHandle recordH;
  union {
    ...
  } info;
} sdpAttribute;

Fields

attributeID: The attribute identifier of the attribute.
recordH: A handle identifying the SDP memory record from which the size of the raw attribute is retrieved.
info: A union containing information specific to the event. See The info Field.

The info Field

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

UInt16 valSize;

This field contains the size, in bytes, of the raw attribute value.

btLibSocketEventSdpGetServerChannelBy
Uuid ^TOP^

Purpose

A get server channel request has completed. The application initiated this request by calling BtLibSdpGetServerChannelByUuid().

If the status field is btLibErrNoError, the operation completed successfully, and the server channel can be found in the eventData field. Otherwise, the operation failed, and the status field indicates the reason for the failure.

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

Prototype

struct {
  BtLibSdpRemoteServiceRecordHandle
    remoteHandle; 
  union {
    ...
  } param;
} sdpByUuid;

Fields

remoteHandle: The handle for the remote SDP service record.
param: A union containing information that depends on the event. See The param Field.

The param Field

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

BtLibRfCommServerIdType channel;

This BtLibRfCommServerIdType contains the RFCOMM server channel represented by the SDP service record.

btLibSocketEventSdpGetPsmByUuid ^TOP^

Purpose

A get PSM request has completed. The application initiated this request by calling BtLibSdpGetPSMByUuid().

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

Prototype

struct {
  BtLibSdpRemoteServiceRecordHandle
    remoteHandle; 
  union {
    ...
  } param;
} sdpByUuid;

Fields

remoteHandle: The handle for the remote SDP service record.
param: A union containing information that depends on the event. See The param Field.

The param Field

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

BtLibL2CapPsmType psm;

This BtLibL2CapPsmType contains the PSM value of the L2CAP channel represented by the SDP service record.

btLibSocketEventSendComplete ^TOP^

Purpose

A send request has completed. The application initiated this request by calling BtLibSocketSend().

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

Prototype

struct {
  UInt16 dataLen;
  UInt8 *data;
} data;

Fields

dataLen: The number of bytes of data that were actually sent.
data: Not used. This variable does not contain any valid information.

Error Conditions

btLibErrNoError: Success.
btLibErrNoAclLink: No ACL Link.

Socket Disconnection Error Codes ^TOP^

In addition to the standard error codes that can accompany socket events, the status codes accompanying the btLibSocketEventConnectedInbound, btLibSocketEventConnectedOutbound, and btLibSocketEventDisconnected events can have the following additional values:

btLibL2DiscConfigOptions: Configuration failed due to an unrecognized configuration option.
btLibL2DiscConfigReject: Configuration was rejected (unknown reason).
btLibL2DiscConfigUnacceptable: Configuration failed due to unacceptable parameters.
btLibL2DiscConnNoResources: The remote device is out of resources.
btLibL2DiscConnPsmUnsupported: The remote device does not support the requested protocol service (PSM).
btLibL2DiscConnSecurityBlock: The remote device's security system denied the connection.
btLibL2DiscLinkDisc: The underlying ACL Link was disconnected.
btLibL2DiscQosViolation: The connection was terminated due to a Quality of Service (QOS) violation.
btLibL2DiscReasonUnknown: Disconnection occurred for an unknown reason.
btLibL2DiscRequestTimeout: An L2CAP request timed out.
btLibL2DiscSecurityBlock: The local security manager refused the connection attempt.
btLibL2DiscUserRequest: Disconnection was requested by either the local or remote device.

Socket Functions ^TOP^

The Bluetooth library uses sockets to represent L2CAP, RFCOMM, and SDP connections. The functions in this section perform general socket tasks and tasks related to L2CAP and RFCOMM sockets. The functions specific to SDP sockets are in the Service Discovery Protocol Functions section.

BtLibSocketAdvanceCredit Function ^TOP^

Purpose

Advance credit to a given RFCOMM connection socket.

Declared In

BtLib.h

Prototype

Err BtLibSocketAdvanceCredit (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   UInt8 credit
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: RFCOMM socket reference number.
→ 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.

Comments

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

Multiple calls to this function have a cumulative effect.

BtLibSocketClose Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSocketClose (
   UInt16 btLibRefNum,
   BtLibSocketRef socket
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number of socket to close.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrSocket: The specified socket is invalid.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

No callback events are generated when closing a socket.

BtLibSocketConnect Function ^TOP^

Purpose

Create an outbound L2CAP or RFCOMM connection.

Declared In

BtLib.h

Prototype

Err BtLibSocketConnect (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   BtLibSocketConnectInfoType *connectInfo
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number of 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 a callback event.
btLibErrNoAclLink: An ACL link for the remote device does not exist
btLibErrNotOpen: The referenced Bluetooth library is not open.
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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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, the btLibSocketEventData event is generated whenever data is received from the remote device. When the channel disconnects, a btLibSocketEventDisconnected event is generated.

BtLibSocketConnectInfoType

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.

Prototype

typedef struct BtLibSocketConnectInfoType {
  BtLibDeviceAddressTypePtr remoteDeviceP;
  union {
    ...
  } data;
} 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 two members: L2Cap, and RfComm.

L2Cap

Use the L2Cap union member if you're setting up a L2CAP socket. This member contains the following structure:

Prototype

struct {
  BtLibL2CapPsmType remotePsm;
  UInt16 minRemoteMtu;
  UInt16 localMtu;
} L2Cap;

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

Use the RfComm union member if you're setting up a RFCOMM socket. This member contains the following structure:

Prototype

struct {
  BtLibRfCommServerIdType remoteService; 
  UInt16 maxFrameSize;
  UInt8 advancedCredit;
} RfComm;

Fields

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).
maxFrameSize: The maximum frame size your application can handle. This value must be between BT_RF_MINFRAMESIZE and BT_RF_MAXFRAMESIZE. If your application can handle any frame size, set this value to BT_RF_DEFAULT_FRAMESIZE.
advancedCredit: An amount of credit the socket advances to the remote device when it successfully connects. Additional credit can be advanced using the BtLibSocketAdvanceCredit() function once the connection has been established.

BtLibSocketCreate Function ^TOP^

Purpose

Create a socket with foreground notification. The Bluetooth library supports a maximum of 16 socket connections.

Declared In

BtLib.h

Prototype

Err BtLibSocketCreate (
   UInt16 btLibRefNum,
   BtLibSocketRef *socketRefP,
   BtLibSocketProcPtr callbackP,
   UInt32 refCon,
   BtLibProtocolEnum socketProtocol
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
← socketRefP: Pointer to an allocated BtLibSocketRef that contains the socket value upon return. This pointer must not be NULL.
→ callbackP: Callback procedure used to respond to socket events. This value must not be NULL.
→ refCon: Caller-defined data to pass to the callback procedure.
→ socketProtocol: Protocol (L2CAP, RFCOMM, or SDP) to use with this socket.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: Either socketRefP or callbackP is NULL.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.
btLibErrTooMany: The maximum number of sockets allocated for the system has already been reached. The Bluetooth library supports a maximum of 16 socket connections.

Comments

No callback events are generated when creating a socket.

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

BtLibSocketGetInfo Function ^TOP^

Purpose

Retrieve information for a currently open socket.

Declared In

BtLib.h

Prototype

Err BtLibSocketGetInfo (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   BtLibSocketInfoEnum infoType,
   void *valueP,
   UInt32 valueSize
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number for the socket to query.
→ infoType: Type of information to retrieve. See BtLibSocketInfoEnum.
← valueP: Buffer into which this function stores the result. You must allocate this buffer.
→ valueSize: Size, in bytes, of the valueP buffer. This size must match the size of the retrieved information.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: One or more parameters is invalid. Be sure that the 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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

BtLibSocketInfoEnum

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

Prototype

typedef enum {
  btLibSocketInfo_Protocol = 0,
  btLibSocketInfo_RemoteDeviceAddress,
  btLibSocketInfo_SendPending = 100,
  btLibSocketInfo_MaxTxSize,
  btLibSocketInfo_MaxRxSize,
  btLibSocketInfo_L2CapPsm = 200,
  btLibSocketInfo_L2CapChannel,
  btLibSocketInfo_RfCommServerId = 300,
  btLibSocketInfo_RfCommOutstandingCredits,
  btLibSocketInfo_SdpServiceRecordHandle = 400
} BtLibSocketInfoEnum;

Constants

btLibSocketInfo_L2CapChannel: BtLibSocketGetInfo returns a BtLibL2CapChannelIDType that represents the channel identifier for this socket. A BtLibL2CapChannelIDType is actually a UInt16. 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_L2CapPsm: BtLibSocketGetInfo returns a BtLibL2CapPsmType that represents the Protocol and Service Multiplexer (PSM) this socket is using to route packets. This information is only valid for L2CAP sockets.
btLibSocketInfo_MaxRxSize: BtLibSocketGetInfo returns a UInt32 representing the maximum packet size the local device can receive.
btLibSocketInfo_MaxTxSize: BtLibSocketGetInfo returns a UInt32 representing the maximum packet size the local device can transmit.
btLibSocketInfo_Protocol: BtLibSocketGetInfo returns a BtLibProtocolEnum representing the socket's protocol. The members of this enum are btLibL2CapProtocol, btLibRfCommProtocol, and btLibSdpProtocol.
btLibSocketInfo_RemoteDeviceAddress: BtLibSocketGetInfo returns a BtLibDeviceAddressType representing the address of the device at the other end of this socket.
btLibSocketInfo_RfCommServerId: BtLibSocketGetInfo returns a BtLibRfCommServerIdType that represents the socket's RFCOMM server channel. This information is valid for RFCOMM sockets only.
btLibSocketInfo_RfCommOutstandingCredits: BtLibSocketGetInfo returns a UInt16 containing the number of remaining credits on this socket. This information is valid for RFCOMM sockets only.
btLibSocketInfo_SdpServiceRecordHandle: BtLibSocketGetInfo returns the BtLibSdpRemoteServiceRecordHandle for the service record associated with this socket. This information is valid for SDP sockets only.
btLibSocketInfo_SendPending: BtLibSocketGetInfo returns a Boolean indicating whether a send is currently in progress.

BtLibSocketListen Function ^TOP^

Purpose

Set up an L2CAP or RFCOMM socket as a listener.

Declared In

BtLib.h

Prototype

Err BtLibSocketListen (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   BtLibSocketListenInfoType *listenInfo
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number of the socket.
↔ listenInfo: Protocol-specific listening information. For more information see BtLibSocketListenInfoType. This parameter must not be NULL.

Returns

Returns one of the following values:

btLibErrNoError: Success. The socket is listening for incoming connections.
btLibErrBusy: The given PSM is in use (L2CAP only)
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: listenInfo is NULL.
btLibErrSocket: The specified socket is invalid.
btLibErrSocketProtocol: The protocol of the specified socket is not supported. This function only supports the L2CAP and RFCOMM protocols.
btLibErrSocketRole: The specified socket is already listening or connected.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.
btLibErrTooMany: There are no resources to create a listener socket of this type.

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 BtLibSocketRespondToConnection() 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 documentation for BtLibSocketListenInfoType that follows.

BtLibSocketListenInfoType

The BtLibSocketListenInfoType structure allows you to specify data specific to the protocol of the listening socket.

Prototype

typedef struct BtLibSocketListenInfoType {
  union {
    ...
  } data;
} BtLibSocketListenInfoType;

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.

L2Cap

Use the L2Cap union member if you're setting up a L2CAP socket as a listener. This member contains the following structure:

Prototype

struct {
  BtLibL2CapPsmType localPsm;
  UInt16 localMtu;
  UInt16 minRemoteMtu;
} L2Cap;

Fields

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

RfComm

Use the RfComm union member if you're setting up a RFCOMM socket as a listener. This member contains the following structure:

Prototype

struct {
   BtLibRfCommServerIdType serviceID;
   UInt16 maxFrameSize;
   UInt8 advancedCredit; 
} RfComm;

Fields

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

BtLibSocketRespondToConnection Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSocketRespondToConnection (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   Boolean accept
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number of the listener socket.
→ accept: true to accept the connection; false to reject the connection.

Returns

Returns one of the following values:

btLibErrNoError: Success. This status is returned when accept is false.
btLibErrFailed: One or more parameters is invalid.
btLibErrPending: The results will be returned through a callback event.
btLibErrNotOpen: The referenced Bluetooth library is not open.
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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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, a btLibSocketEventData callback event is generated whenever data received from the remote device. If the channel disconnects, a btLibSocketEventDisconnected 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.

On the other hand, when you respond to an RFCOMM connection, the RFCOMM listener socket becomes a connection socket through which you can exchange data with the remote device. If you want to create another RFCOMM connection, you need to create another listener socket.

BtLibSocketSend Function ^TOP^

Purpose

Send data over a connected L2CAP or RFCOMM socket.

Declared In

BtLib.h

Prototype

Err BtLibSocketSend (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   UInt8 *data,
   UInt32 dataLen
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number of the transmitting socket.
→ data: Pointer to data to send. If the send returns btLibErrPending, the data buffer contents must remain intact until the btLibSocketEventSendComplete event occurs.
→ 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 a callback event.
btLibErrBusy: A send is already in process.
btLibErrNoAclLink: An ACL link for the remote device does not exist
btlibErrNotOpen: The referenced Bluetooth library is not open.
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 RFCOMM protocols.
btLibErrSocketRole: The specified socket is not connected.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

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

Note that there can be only one send in progress at a time per socket. You must wait for the btLibSocketEventSendComplete event before sending another packet.

Service Discovery Protocol Functions ^TOP^

This section describes functions and macros related to the Bluetooth Service Discovery Protocol (SDP).

BtLibSdpCompareUuids Function ^TOP^

Purpose

Compare two UUIDs.

Declared In

BtLib.h

Prototype

Err BtLibSdpCompareUuids (
   UInt16 btLibRefNum,
   BtLibSdpUuidType *uuid1,
   BtLibSdpUuidType *uuid2
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth Library.
→ uuid1: UUID to compare.
→ uuid2: UUID to compare.

Returns

Returns one of the following values:

btLibErrNoError: UUIDs are the same
btLibErrError: UUIDs are different.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: One or both UUIDs are invalid.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

BtLibSdpGetPSMByUuid Function ^TOP^

Purpose

Get an available L2CAP PSM using SDP.

Declared In

BtLib.h

Prototype

Err BtLibSdpGetPsmByUuid (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   BtLibDeviceAddressType *remoteDeviceP,
   BtLibSdpUuidType *serviceUuidList,
   UInt8 uuidListLen
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number for an SDP socket.
→ remoteDeviceP: 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 a callback event.
btLibErrNotOpen: The referenced Bluetooth library is not open.
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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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.

BtLibSdpGetRawDataElementSize Macro ^TOP^

Purpose

Returns a constant representing the data element's size.

Declared In

BtLib.h

Prototype

#define BtLibSdpGetRawDataElementSize (
   header
)

Parameters

→ header: First byte of a data element

Returns

A constant representing the size of the data element.

Comments

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

The result of this macro is one of the following constants:

Data Element Sizes

btLibDESD_1BYTE: A 1-byte element. However, if the data element's type is btLibDETD_NIL then the size is 0 bytes.
btLibDESD_2BYTES: A 2-byte element.
btLibDESD_4BYTES: A 4-byte element.
btLibDESD_8BYTES: An 8-byte element.
btLibDESD_16BYTES: A 16-byte element.
btLibDESD_ADD_8BITS: The element's actual data size, in bytes, is contained in the next 8 bits.
btLibDESD_ADD_16BITS: The element's actual data size, in bytes, is contained in the next 16 bits.
btLibDESD_ADD_32BITS: The element's actual data size, in bytes, is contained in the next 32 bits.

These size constants are discussed in greater detail in the "Service Discovery Protocol" chapter of the Specification of the Bluetooth System.

BtLibSdpGetRawDataElementType Macro ^TOP^

Purpose

Returns an SDP data element's type.

Declared In

BtLib.h

Prototype

#define BtLibSdpGetRawDataElementType (
   header
)

→ header: The first byte of a data element

Returns

The type of the data element.

Comments

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

The result of this macro is one of the following constants:

Data Element Types

btLibDETD_NIL: Nil, the null type
btLibDETD_UINT: Unsigned Integer.
btLibDETD_SINT: Signed Integer
btLibDETD_UUID: UUID, a universally unique identifier
btLibDETD_TEXT: Text string
btLibDETD_BOOL: Boolean
btLibDETD_SEQ: Data element sequence
btLibDETD_ALT: Data element alternative
btLibDETD_URL: URL, a uniform resource locator

These types are discussed in greater detail in the "Service Discovery Protocol" chapter of the Specification of the Bluetooth System.

BtLibSdpGetServerChannelByUuid Function ^TOP^

Purpose

Get an available RFCOMM server channel using SDP.

Declared In

BtLib.h

Prototype

Err BtLibSdpGetServerChannelByUuid(
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   BtLibDeviceAddressType *remoteDeviceP,
   BtLibSdpUuidType *serviceUuidList,
   UInt8 uuidListLen
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number for an SDP socket.
→ remoteDeviceP: 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 a callback event.
btLibErrNotOpen: The referenced Bluetooth library is not open.
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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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 btLibSocketEventSdpGetServerChannelBy Uuid event when the query completes or fails.

BtLibSdpParseRawDataElement Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpParseRawDataElement (
   UInt16 btLibRefNum,
   const UInt8 *dataElementP,
   UInt16 *offset,
   UInt32 *length
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ dataElementP: Pointer to a raw SDP data element.
← offset: Offset, in bytes, between dataElementP and the start of the data field.
← lengthP: Length, in bytes, of the data field.

Returns

Returns one of the following values:

btLibErrNoError: Successfully parsed the attribute.
btLibErrNotOpen: The reference Bluetooth library is not open.
btLibErrParamError: dataElementP, offset, or length is NULL.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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.

BtLibSdpServiceRecordCreate Function ^TOP^

Purpose

Allocate a memory chunk that represents an SDP service record.

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordCreate (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle *recordH
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
← recordH: SDP memory handle for the new SDP memory record.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrOutOfMemory: Not enough memory to allocate the memory chunk.
btLibErrParamError: recordH is NULL.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

BtLibSdpServiceRecordDestroy Function ^TOP^

Purpose

Free the memory associated with a SDP memory record.

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordDestroy (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ recordH: SDP memory handle associated with the memory chunk to be freed.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrParamError: recordH does not refer to an valid SDP memory record.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

This function stops advertising the record before it frees it.

BtLibSdpServiceRecordGetAttribute Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetAttribute (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   BtLibSdpAttributeDataType *attributeValues,
   UInt16 listNumber,
   UInt16 listEntry
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ recordH: Handle identifying the SDP memory record.
→ attributeID: Attribute identifier of the attribute to retrieve.
← attributeValues: 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 a callback 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrOutOfMemory: Not enough memory to perform the query.
btLibErrParamError: recordH is an invalid handle or attributeValues is NULL.
btLibErrSdpAttributeNotSet: The specified attribute does not exist in the specified service record.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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 buffer to which attributeValues points must not be freed before the event occurs; making the buffer global ensures that it remains over the duration of the SDP query.

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.

BtLibSdpServiceRecordGetNumListEntries Function ^TOP^

Purpose

Get the number of entries in a list attribute.

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetNumListEntries (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   UInt16 listNumber,
   UInt16 *numEntries
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ 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: 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 a callback 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrOutOfMemory: Not enough memory to perform this query.
btLibErrParamError: recordH is an invalid handle or numEntries is NULL.
btLibErrSdpAttributeNotSet: The specified attribute does not exist in the specified service record.
btLibErrStackNotOpen: The Bluetooth stack failed to open when the library was opened.

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.

BtLibSdpServiceRecordGetNumLists Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetNumLists (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   UInt16 *numLists
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ recordH: Handle identifying the SDP memory record.
→ attributeID: Attribute identifier of the attribute whose number of lists is retrieved.
← numLists: 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 a callback 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrOutOfMemory: Not enough memory to perform this query.
btLibErrParamError: recordH is an invalid handle or numLists is NULL.
btLibErrSdpAttributeNotSet: The specified attribute does not exist in the specified service record.
btLibErrStackNotOpen: The Bluetooth stack failed to open when the library was opened.

Comments

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

BtLibSdpServiceRecordGetRawAttribute Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetRawAttribute (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   UInt8 *value,
   UInt16 *valSize
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ 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 a callback 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrOutOfMemory: Not enough memory to perform the query.
btLibErrParamError: recordH is an invalid handle, value is NULL, valSize is 0, or the size of the attribute value is larger than valSize.
btLibErrSdpAttributeNotSet: The specified attribute does not exist in the specified service record.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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.

BtLibSdpServiceRecordGetSizeOfRawAttribute Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetSizeOfRawAttribute (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   UInt16 *size
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ recordH: Handle identifying the SDP memory record.
→ attributeID: Attribute identifier of the attribute whose size is retrieved.
← size: Pointer to a UInt16 to store the size of the attribute. This parameter must not be NULL.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrPending: The specified SDP memory record refers to a service record on a remote device. The result will be returned through a callback 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrOutOfMemory: Not enough memory to perform the query.
btLibErrParamError: recordH is an invalid handle or size is NULL.
btLibErrSdpAttributeNotSet: The specified attribute does not exist in the specified service record.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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.

BtLibSdpServiceRecordGetStringOrUrlLength Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetStringOrUrlLength (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   UInt16 *length
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ recordH: Handle identifying the SDP memory record.
→ attributeID: Attribute identifier of the attribute whose length is retrieved.
← length: Pointer to a UInt16 where the length of the attribute is stored. This parameter cannot be NULL.

Returns

Returns one of the following values:

btLibErrNoError: Success.
btLibErrPending: The specified SDP memory record refers to a service record on a remote device. The result will be returned through a callback 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrOutOfMemory: Not enough memory to perform the query.
btLibErrParamError: The recordH does not refer to a valid handle, length is NULL, or the attribute is not a string or a URL.
btLibErrSdpAttributeNotSet: The specified attribute does not exist in the specified SDP record.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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.

BtLibSdpServiceRecordMapRemote Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordMapRemote (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   BtLibDeviceAddressType *remoteDeviceP,
   BtLibSdpRemoteServiceRecordHandle remoteHandle,
   BtLibSdpRecordHandle recordH
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number of an SDP socket.
→ remoteDeviceP: 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

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

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

BtLibSdpServiceRecordSetAttribute Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordSetAttribute (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   BtLibSdpAttributeDataType *attributeValue,
   UInt16 listNumber,
   UInt16 listEntry
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ 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: List 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrOutOfMemory: Not enough memory to set the attribute.
btLibErrParamError: recordH is invalid or attributeValue is NULL.
btLibErrRemoteRecord: A remote record was passed in recordH. The record must be local.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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.

BtLibSdpServiceRecordSetAttributesForSocket Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordSetAttributesForSocket (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   BtLibSdpUuidType *serviceUUIDList,
   UInt8 uuidListLen,
   const Char *serviceName,
   UInt16 serviceNameLen,
   BtLibSdpRecordHandle recordH
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: 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.
→ 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 referenced Bluetooth library 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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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.

BtLibSdpServiceRecordSetRawAttribute Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordSetRawAttribute (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH,
   BtLibSdpAttributeIdType attributeID,
   const UInt8 *value,
   UInt16 valSize
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
btLibErrOutOfMemory: Not enough memory to set the attribute.
btLibErrParamError: recordH is invalid, value is NULL, or valSize is 0.
btLibErrRemoteRecord: recordH refers to a service record on a remote device. The service record must be local.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

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

BtLibSdpServiceRecordsGetByServiceClass Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordsGetByServiceClass (
   UInt16 btLibRefNum,
   BtLibSocketRef socket,
   BtLibDeviceAddressType *remoteDeviceP,
   BtLibSdpUuidType *uuidList,
   UInt16 uuidListLen,
   BtLibSdpRemoteServiceRecordHandle *srvRecList,
   UInt16 *numSrvRec
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ socket: Reference number of an SDP socket.
→ remoteDevice: 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.
← srvRecList: Array of service record handles into which this function stores the results of the SDP query. You must allocate this array. This pointer must not be NULL.
↔ numSrvRec: Number of service records allocated in srvRecList. This value is sent to the SDP server so it can limit the number of responses. On return, the actual number of records retrieved.

Returns

Returns one of the following values:

btLibErrPending: The results will be returned through a callback 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.
btLibErrNotOpen: The referenced Bluetooth library is not open.
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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

You need to allocate srvRecList, an array of BtLibSdpRemoteServiceRecordHandles large enough to accommodate all of the service record handles corresponding to the specified service classes. Specify the size of the array using the numSrvRec parameter.

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

BtLibSdpServiceRecordStartAdvertising Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordStartAdvertising (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ recordH: Handle of the service record to make available to remote devices.

Returns

Returns one of the following values:

btLibErrNoError: Success
btLibErrNotOpen: The referenced Bluetooth library is not open.
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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

Comments

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

BtLibSdpServiceRecordStopAdvertising Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordStopAdvertising (
   UInt16 btLibRefNum,
   BtLibSdpRecordHandle recordH
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ recordH: Handle of the service record to hide.

Returns

Returns one of the following values:

btLibErrNoError: Success. The SDP record is no longer available to remote devices.
btLibErrNotOpen: The referenced Bluetooth library is not open.
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.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

BtLibSdpUuidInitialize Macro ^TOP^

Purpose

Sets the value of a UUID.

Declared In

BtLib.h

Prototype

#define BtLibSdpUuidInitialize (
   uuid,
   value,
   valSize
)

Parameters

uuid: BtLibSdpUuidType to initialize.
value: Array of bytes representing the UUID. The size of this array depends on valSize.
valSize: BtLibSdpUuidSizeEnum member specifying the size of the value array.

Returns

None.

BtLibSdpVerifyRawDataElement Function ^TOP^

Purpose

Verify that a raw SDP data element is properly formed.

Declared In

BtLib.h

Prototype

Err BtLibSdpVerifyRawDataElement (
   UInt16 btLibRefNum,
   const UInt8 *value,
   UInt16 valSize,
   UInt8 maxLevel
)

Parameters

→ btLibRefNum: Reference number for the Bluetooth library.
→ value: Raw SDP attribute data.
→ valSize: Size of value, in bytes. The size of the data element must be less than or equal to this parameter, otherwise this function fails.
→ maxLevel: Maximum level of recursion over which this function verifies the data element. Must be at least one.

Returns

Returns one of the following values:

btLibErrNoError: SDP data element is properly formatted.
btLibErrError: SDP data element is not properly formatted.
btLibErrNotOpen: The reference Bluetooth library is not open.
btLibErrParamError: value is NULL.
btLibErrStackNotOpen: The Bluetooth stack failed to initialize when the library was opened.

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.

Application-Defined Functions ^TOP^

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

BtLibSocketCallback Function ^TOP^

Purpose

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

Declared In

BtLibTypes.h

Prototype

void (
   *BtLibSocketProcPtr
) (
   BtLibSocketEventType *sEvent,
   UInt32 refCon
)

Parameters

→ sEvent: BtLibSocketEventType structure containing the event parameters.
→ refCon: General purpose integer which you can use to hold application-specific information. When you call BtLibSocketCreate() to create the socket, you can specify a value to pass to this parameter.

Returns

Returns nothing.

Comments

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

You must specify this callback function when you create a socket. You do this by calling BtLibSocketCreate().

83 Bluetooth Library: Sockets and Service Discovery

Socket-Related Data Structures ^TOP^

BtLibL2CapPsmType Typedef ^TOP^

Purpose

Prototype

BtLibLanguageBaseTripletType Struct ^TOP^

Purpose

Prototype

Fields

Language Constants

Constants

Character Encoding Constants

Constants

Attribute Identifier Offsets

Constants

BtLibProfileDescriptorListEntryType Struct ^TOP^

Purpose

Prototype

Fields

BtLibProtocolDescriptorListEntryType Struct ^TOP^

Purpose

Prototype

Fields

BtLibRfCommServerIdType Typedef ^TOP^

Purpose

Prototype

BtLibSdpAttributeDataType Struct ^TOP^

Purpose

Prototype

See Also

BtLibSdpAttributeIdType Typedef ^TOP^

Purpose

Prototype

Universal Attribute IDs

Constants

BtLibSdpRecordHandle Typedef ^TOP^

Purpose

Prototype

BtLibSdpRemoteServiceRecordHandle Typedef ^TOP^

Purpose

Prototype

BtLibSdpUuidSizeEnum Enum ^TOP^

Purpose

Prototype

Constants

BtLibSdpUuidType Struct ^TOP^

Purpose

Prototype

Fields

Predefined UUIDs

Constants

BtLibSocketEventType Struct ^TOP^

Purpose

Prototype

Fields

BtLibSocketRef Typedef ^TOP^

Purpose

Prototype

BtLibStringType Struct ^TOP^

Purpose

Prototype

Fields

BtLibUrlType Struct ^TOP^

Purpose

Prototype

Fields

Socket Callback Events ^TOP^

btLibSocketEventConnectedInbound ^TOP^

btLibSocketEventConnectedOutbound ^TOP^

btLibSocketEventConnectRequest ^TOP^

btLibSocketEventData ^TOP^

Purpose

Prototype

Fields

btLibSocketEventDisconnected ^TOP^

btLibSocketEventSdpServiceRecordHandle ^TOP^

Purpose

Prototype

Fields

btLibSocketEventSdpGetAttribute ^TOP^