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

83    Bluetooth Library: Sockets and Service Discovery

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

Part IV: Libraries

83 Bluetooth Library: Sockets and Service Discovery

Socket-Related Data Structures

BtLibL2CapPsmType

BtLibLanguageBaseTripletType

BtLibProfileDescriptorListEntryType

BtLibProtocolDescriptorListEntryType

BtLibRfCommServerIdType

BtLibSdpAttributeDataType

BtLibSdpAttributeIdType

BtLibSdpRecordHandle

BtLibSdpRemoteServiceRecordHandle

BtLibSdpUuidSizeEnum

BtLibSdpUuidType

BtLibSocketEventType

BtLibSocketRef

BtLibStringType

BtLibUrlType

Socket Callback Events

btLibSocketEventConnectedInbound

btLibSocketEventConnectedOutbound

btLibSocketEventConnectRequest

btLibSocketEventData

btLibSocketEventDisconnected

btLibSocketEventSdpServiceRecordHandle

btLibSocketEventSdpGetAttribute

btLibSocketEventSdpGetStringLen

btLibSocketEventSdpGetNumListEntries

btLibSocketEventSdpGetNumLists

btLibSocketEventSdpGetRawAttribute

btLibSocketEventSdpGetRawAttributeSize

btLibSocketEventSdpGetServerChannelBy
Uuid

btLibSocketEventSdpGetPsmByUuid

btLibSocketEventSendComplete

Socket Disconnection Error Codes

Socket Functions

BtLibSocketAdvanceCredit

BtLibSocketClose

BtLibSocketConnect

BtLibSocketCreate

BtLibSocketGetInfo

BtLibSocketListen

BtLibSocketRespondToConnection

BtLibSocketSend

Service Discovery Protocol Functions

BtLibSdpCompareUuids

BtLibSdpGetPSMByUuid

BtLibSdpGetRawDataElementSize

BtLibSdpGetRawDataElementType

BtLibSdpGetServerChannelByUuid

BtLibSdpParseRawDataElement

BtLibSdpServiceRecordCreate

BtLibSdpServiceRecordDestroy

BtLibSdpServiceRecordGetAttribute

BtLibSdpServiceRecordGetNumListEntries

BtLibSdpServiceRecordGetNumLists

BtLibSdpServiceRecordGetRawAttribute

BtLibSdpServiceRecordGetSizeOfRawAttribute

BtLibSdpServiceRecordGetStringOrUrlLength

BtLibSdpServiceRecordMapRemote

BtLibSdpServiceRecordSetAttribute

BtLibSdpServiceRecordSetAttributesForSocket

BtLibSdpServiceRecordSetRawAttribute

BtLibSdpServiceRecordsGetByServiceClass

BtLibSdpServiceRecordStartAdvertising

BtLibSdpServiceRecordStopAdvertising

BtLibSdpUuidInitialize

BtLibSdpVerifyRawDataElement

Application-Defined Functions

BtLibSocketCallback

     

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.

See Also

BtLibSdpUuidType, BtLibProtocolDescriptorListEntryType, BtLibProfileDescriptorListEntryType, BtLibLanguageBaseTripletType, BtLibUrlType, BtLibStringType

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

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:

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 (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   UInt8credit
)

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

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.

See Also

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

BtLibSocketConnect Function ^TOP^

Purpose

Create an outbound L2CAP or RFCOMM connection.

Declared In

BtLib.h

Prototype

Err BtLibSocketConnect (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   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.

See Also

BtLibSocketSend(), BtLibSocketClose()

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 (
   UInt16btLibRefNum,
   BtLibSocketRef*socketRefP,
   BtLibSocketProcPtrcallbackP,
   UInt32refCon,
   BtLibProtocolEnumsocketProtocol
)

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.

See Also

BtLibSocketConnect(), BtLibSocketListen(), BtLibSocketClose()

BtLibSocketGetInfo Function ^TOP^

Purpose

Retrieve information for a currently open socket.

Declared In

BtLib.h

Prototype

Err BtLibSocketGetInfo (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   BtLibSocketInfoEnuminfoType,
   void*valueP,
   UInt32valueSize
)

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 (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   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.

See Also

BtLibSocketClose()

BtLibSocketRespondToConnection Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSocketRespondToConnection (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   Booleanaccept
)

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.

See Also

BtLibSocketListen(), BtLibSocketSend(), BtLibSocketClose()

BtLibSocketSend Function ^TOP^

Purpose

Send data over a connected L2CAP or RFCOMM socket.

Declared In

BtLib.h

Prototype

Err BtLibSocketSend (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   UInt8*data,
   UInt32dataLen
)

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.

See Also

BtLibSocketClose()

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 (
   UInt16btLibRefNum,
   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 (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   BtLibDeviceAddressType*remoteDeviceP,
   BtLibSdpUuidType*serviceUuidList,
   UInt8uuidListLen
)

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.

See Also

BtLibSdpGetServerChannelByUuid()

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.

See Also

BtLibSdpGetRawDataElementType(), BtLibSdpParseRawDataElement(), BtLibSdpVerifyRawDataElement()

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.

See Also

BtLibSdpGetRawDataElementSize(), BtLibSdpParseRawDataElement(), BtLibSdpVerifyRawDataElement()

BtLibSdpGetServerChannelByUuid Function ^TOP^

Purpose

Get an available RFCOMM server channel using SDP.

Declared In

BtLib.h

Prototype

Err BtLibSdpGetServerChannelByUuid(
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   BtLibDeviceAddressType*remoteDeviceP,
   BtLibSdpUuidType*serviceUuidList,
   UInt8uuidListLen
)

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.

See Also

BtLibSdpGetPSMByUuid()

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 (
   UInt16btLibRefNum,
   constUInt8*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.

See Also

BtLibSdpVerifyRawDataElement(), BtLibSdpGetRawDataElementType(), BtLibSdpGetRawDataElementSize()

BtLibSdpServiceRecordCreate Function ^TOP^

Purpose

Allocate a memory chunk that represents an SDP service record.

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordCreate (
   UInt16btLibRefNum,
   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.

See Also

BtLibSdpServiceRecordDestroy(), BtLibSdpServiceRecordStartAdvertising(), BtLibSdpServiceRecordStopAdvertising()

BtLibSdpServiceRecordDestroy Function ^TOP^

Purpose

Free the memory associated with a SDP memory record.

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordDestroy (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH
)

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.

See Also

BtLibSdpServiceRecordCreate(), BtLibSdpServiceRecordStartAdvertising(), BtLibSdpServiceRecordStopAdvertising()

BtLibSdpServiceRecordGetAttribute Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetAttribute (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH,
   BtLibSdpAttributeIdTypeattributeID,
   BtLibSdpAttributeDataType*attributeValues,
   UInt16listNumber,
   UInt16listEntry
)

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.

See Also

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

BtLibSdpServiceRecordGetNumListEntries Function ^TOP^

Purpose

Get the number of entries in a list attribute.

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetNumListEntries (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH,
   BtLibSdpAttributeIdTypeattributeID,
   UInt16listNumber,
   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.

See Also

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

BtLibSdpServiceRecordGetNumLists Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetNumLists (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH,
   BtLibSdpAttributeIdTypeattributeID,
   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.

See Also

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

BtLibSdpServiceRecordGetRawAttribute Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetRawAttribute (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH,
   BtLibSdpAttributeIdTypeattributeID,
   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.

See Also

BtLibSdpServiceRecordSetRawAttribute(), BtLibSdpServiceRecordGetSizeOfRawAttribute(), BtLibSdpServiceRecordMapRemote()

BtLibSdpServiceRecordGetSizeOfRawAttribute Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetSizeOfRawAttribute (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH,
   BtLibSdpAttributeIdTypeattributeID,
   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.

See Also

BtLibSdpServiceRecordGetRawAttribute(), BtLibSdpServiceRecordMapRemote(), BtLibSdpServiceRecordSetRawAttribute()

BtLibSdpServiceRecordGetStringOrUrlLength Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordGetStringOrUrlLength (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH,
   BtLibSdpAttributeIdTypeattributeID,
   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.

See Also

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

BtLibSdpServiceRecordMapRemote Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordMapRemote (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   BtLibDeviceAddressType*remoteDeviceP,
   BtLibSdpRemoteServiceRecordHandleremoteHandle,
   BtLibSdpRecordHandlerecordH
)

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 (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH,
   BtLibSdpAttributeIdTypeattributeID,
   BtLibSdpAttributeDataType*attributeValue,
   UInt16listNumber,
   UInt16listEntry
)

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.

See Also

BtLibSdpServiceRecordGetAttribute(), BtLibSdpServiceRecordStartAdvertising(), BtLibSdpServiceRecordStopAdvertising()

BtLibSdpServiceRecordSetAttributesForSocket Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordSetAttributesForSocket (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   BtLibSdpUuidType*serviceUUIDList,
   UInt8uuidListLen,
   constChar*serviceName,
   UInt16serviceNameLen,
   BtLibSdpRecordHandlerecordH
)

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.

See Also

BtLibSdpServiceRecordCreate(), BtLibSocketListen()

BtLibSdpServiceRecordSetRawAttribute Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordSetRawAttribute (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH,
   BtLibSdpAttributeIdTypeattributeID,
   constUInt8*value,
   UInt16valSize
)

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.

See Also

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

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 (
   UInt16btLibRefNum,
   BtLibSocketRefsocket,
   BtLibDeviceAddressType*remoteDeviceP,
   BtLibSdpUuidType*uuidList,
   UInt16uuidListLen,
   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 (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH
)

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.

See Also

BtLibSdpServiceRecordStopAdvertising()

BtLibSdpServiceRecordStopAdvertising Function ^TOP^

Purpose

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

Declared In

BtLib.h

Prototype

Err BtLibSdpServiceRecordStopAdvertising (
   UInt16btLibRefNum,
   BtLibSdpRecordHandlerecordH
)

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.

See Also

BtLibSdpServiceRecordStartAdvertising()

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 (
   UInt16btLibRefNum,
   constUInt8*value,
   UInt16valSize,
   UInt8maxLevel
)

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.

See Also

BtLibSdpParseRawDataElement(), BtLibSdpGetRawDataElementType(), BtLibSdpGetRawDataElementSize()

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

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