1543 CNX 2/901 184 Uen version R1a 00-04-28 12:01
Users Manual -Bluetooth PC Reference Stack byEricsson
Bluetooth PC Reference Stack by Ericsson
History
Date Issue CommentsSeptember 23,
1999Created Information compiled by Jörgen Olsson on the behalf of
ECS/UMPMarch 2, 2000 Updated for
the P1C releaseMarch 8, 2000 Created for the
PC ReferenceStack
Based on the generic HOST stack documentation with thesame version number.
April 24, 2000 Updated forthe R1a release
THE INFORMATION OF THIS DOCUMENT IS PROVIDED AS IS AND ERICSSON MAKES NO REPRESENTATIONS ORWARRANTIES WHATSOEVER, WHETHER EXPRESS OR IMPLIED, FOR THE ACCURACY OF THE INFORMATION PROVIDEDHEREIN. IN NO EVENT SHALL ERICSSON BE LIABLE FOR ANY CONSEQUENCES ARISING FROM THE USE OF THISINFORMATION NOR FOR ANY INFRINGEMENT OF PATENTS OR OTHER INTELLECTUAL PROPERTY RIGHTS OF THIRDPARTIES WHICH MAY RESULT FROM THE USE. NO LICENSE IS GRANTED BY IMPLICATION OR OTHERWISE UNDER ANYINTELLECTUAL PROPERTY RIGHTS OF ERICSSON.
ALL RIGHTS RESERVED. NO PART OF THIS DOCUMENT MAY BE REPRODUCED IN ANY FORM WITHOUT THE WRITTENPERMISSION OF THE COPYRIGHT HOLDER. THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUTNOTICE.
© Ericsson Mobile Communications AB, 2000
Bluetooth PC Reference Stack by Ericsson
CONTENTS1. INTRODUCTION............................................................................................................................... 1
1.1 ABOUT THIS DOCUMENT................................................................................................................ 11.2 INTRODUCTION .............................................................................................................................. 11.3 DELIVERABLES................................................................................................................................ 2
1.3.1 Delivery objects....................................................................................................................... 21.4 SYSTEM LEVEL DESCRIPTION ......................................................................................................... 31.5 SUPPORTED BLUETOOTH ADAPTED PROTOCOL LAYERS .............................................................. 41.6 CONCEPTUAL DESCRIPTION OF THE PC REFERENCE STACK......................................................... 51.7 SUPPORTED BLUETOOTH PROFILES & ROLES ................................................................................ 61.8 BLUETOOTH APPLICATIONS........................................................................................................... 81.9 AN INTRODUCTION TO THE API.................................................................................................... 91.10 QUALITY AND INTEROPERABILITY ................................................................................................. 9
1.10.1 Two Different Architectures ................................................................................................... 91.10.1.1 In the Bluetooth Specifications ..................................................................................................91.10.1.2 In Ericsson’s Implementation ..................................................................................................10
1.10.2 Summary............................................................................................................................... 101.11 ABBREVIATIONS USED IN THIS DOCUMENT.................................................................................. 111.12 REFERENCES ................................................................................................................................. 111.13 GLOSSARY..................................................................................................................................... 11
2. INSTALLATION AND SET-UP..................................................................................................... 13
2.1 INTRODUCTION ............................................................................................................................ 132.2 INSTALLATION PROCEDURE ......................................................................................................... 13
3. GUIDE LINES – COM SERVER INTERFACE............................................................................ 16
3.1 COM-SERVER SPECIFIC METHODS........................................................................................... 163.1.1 COM-Server Methods – Overview....................................................................................... 163.1.2 COM-Server Methods – Interface description...................................................................... 16
SendMsg ...........................................................................................................................................................16MsgReceived....................................................................................................................................................17GetCurrentProcessID......................................................................................................................................17GetExternalProcessID.....................................................................................................................................17
4. GUIDE LINES – WRITING BLUETOOTH APPLICATIONS ................................................. 18
4.1 INTRODUCTION ............................................................................................................................ 18
5. API DESCRIPTIONS ....................................................................................................................... 19
5.1 GLOBAL API DESCRIPTIONS ........................................................................................................ 195.1.1 Interface Overview................................................................................................................ 205.1.2 Layer to Layer ....................................................................................................................... 20
5.1.2.1 Message layout...............................................................................................................................205.1.2.2 Data elements.................................................................................................................................235.1.2.3 Data Message .................................................................................................................................255.1.2.4 General Header ..............................................................................................................................255.1.2.4 General Header (MsgID) ..............................................................................................................265.1.2.5 Interface specific items..................................................................................................................30
5.1.3 Layer to MSG........................................................................................................................ 315.1.3.1 Message layout...............................................................................................................................315.1.3.2 Data elements.................................................................................................................................315.1.3.3 Communication procedures.........................................................................................................32
5.1.4 Layer to State ........................................................................................................................ 325.1.4.1 Message layout...............................................................................................................................325.1.4.2 Data elements.................................................................................................................................335.1.4.3 Communication procedures.........................................................................................................33
Bluetooth PC Reference Stack by Ericsson
5.2 STACK CONNECTION MANAGER INTERFACE (SCM).................................................................. 345.2.1 General description ............................................................................................................... 345.2.2 Start procedure...................................................................................................................... 36
5.2.2.1 Overview ........................................................................................................................................365.2.2.2 Function Interface ..........................................................................................................................365.2.2.3 Message Interface ..........................................................................................................................375.2.2.4 Data elements.................................................................................................................................385.2.2.5 Communication procedures.........................................................................................................38
5.2.3 Data & voice link set up procedure ....................................................................................... 395.2.3.1 Overview ........................................................................................................................................395.2.3.2 Function Interface ..........................................................................................................................395.2.3.3 Message Interface ..........................................................................................................................405.2.3.4 Data elements.................................................................................................................................415.2.3.5 Communication procedures.........................................................................................................43
5.2.4 Data & voice link disconnect procedure................................................................................ 465.2.4.1 Overview ........................................................................................................................................465.2.4.2 Function Interface ..........................................................................................................................465.2.4.3 Message Interface ..........................................................................................................................465.2.4.4 Data elements.................................................................................................................................475.2.4.5 Communication procedures.........................................................................................................48
5.2.5 Pairing control procedure ..................................................................................................... 495.2.5.1 Overview ........................................................................................................................................495.2.5.2 Function Interface ..........................................................................................................................495.2.5.3 Message Interface ..........................................................................................................................495.2.5.4 Data elements.................................................................................................................................495.2.5.5 Communication procedures.........................................................................................................50
5.2.6 Result Codes.......................................................................................................................... 515.3 RFCOMM PROTOCOL INTERFACE (RFCOMM) ........................................................................ 53
5.3.1 Context.................................................................................................................................. 535.3.2 Implementation restrictions.................................................................................................. 545.3.3 Start procedure...................................................................................................................... 55
5.3.3.1 Overview ........................................................................................................................................555.3.3.2 Communication procedures.........................................................................................................56
5.3.4 Connection procedure ........................................................................................................... 585.3.4.1 Overview ........................................................................................................................................585.3.4.2 Communication procedures.........................................................................................................60
5.3.5 Collective interface ................................................................................................................ 615.3.5.1 Overview ........................................................................................................................................615.3.5.2 Communication procedures.........................................................................................................63
5.3.6 Data interface........................................................................................................................ 645.3.6.1 Overview ........................................................................................................................................645.3.6.2 Communication procedures.........................................................................................................65
5.3.7 Serial port emulation interface.............................................................................................. 675.3.7.1 Overview ........................................................................................................................................675.3.7.2 Communication procedures.........................................................................................................71
5.4 SERVICE DISCOVERY PROTOCOL INTERFACE (SDP).................................................................... 745.4.1 SDC ...................................................................................................................................... 75
5.4.1.1 CONNECT PROCEDURE ............................................................................................................765.4.1.2 SERVICE DISCOVERY PROCEDURE 1 .....................................................................................795.4.1.3 SERVICE DISCOVERY PROCEDURE 2 .....................................................................................855.4.1.4 DISCONNECT PROCEDURE......................................................................................................885.4.1.5 SUPPORT PROCEDURES ............................................................................................................89
5.4.2 DBM ..................................................................................................................................... 935.4.2.1 START Procedure ..........................................................................................................................955.4.2.2 WRITE Actions...............................................................................................................................995.4.2.3 READ actions ...............................................................................................................................1045.4.2.4 Miscellaneous actions..................................................................................................................108
5.4.3 SDS..................................................................................................................................... 1105.4.3.1 START Procedure ........................................................................................................................110
5.5 L2CAP INTERFACE .................................................................................................................... 113
Bluetooth PC Reference Stack by Ericsson
5.5.1 Overview............................................................................................................................. 1135.5.2 Component management. ................................................................................................... 114
5.5.2.1 Interface and MSC's.....................................................................................................................1145.5.3 Connection establishment. .................................................................................................. 118
5.5.3.1 Interface and MSC's.....................................................................................................................1185.5.4 Connection configuration. .................................................................................................. 121
5.5.4.1 Interface and MSC's.....................................................................................................................1215.5.5 Data transfer ....................................................................................................................... 124
5.5.5.1 Interface and MSC's.....................................................................................................................1245.5.6 Connection misc.................................................................................................................. 127
5.5.6.1 Interface and MSC's.....................................................................................................................1275.5.7 COMMUNICATION PROCEDURES............................................................................. 1295.5.8 Data types + constants. ...................................................................................................... 130
5.5.8.1 L2CA_TQoS..................................................................................................................................1305.5.8.2 L2CA_NEG_…: negative reply results. ....................................................................................1315.5.8.3 L2CA_POS_…: positive reply results. ......................................................................................1315.5.8.4 L2CA_QOS_…: QoS negotiation fields.....................................................................................1325.5.8.5 L2CA_CONFIG_…: Default values for CID configuration....................................................132
5.6 HOST CONTROLLER INTERFACE (HCI)...................................................................................... 1335.6.1 General Description ............................................................................................................ 1335.6.2 Start Commands ................................................................................................................. 134
5.6.2.1 Overview ......................................................................................................................................1345.6.2.2 Communication Procedures.......................................................................................................134
5.6.3 Link Control Commands..................................................................................................... 1365.6.3.1 Overview ......................................................................................................................................136
5.6.4 Interface Specific Items ....................................................................................................... 1455.6.4.1 ReqAddSco ...................................................................................................................................1455.6.4.2 Communication Procedures.......................................................................................................145
5.6.5 Link Policy Commands ....................................................................................................... 1495.6.5.1 Overview ......................................................................................................................................1495.6.5.2 Layout ...........................................................................................................................................1495.6.5.3 Defines ..........................................................................................................................................151
5.6.6 Communication Procedures................................................................................................ 1515.6.7 Host Controller & Baseband Commands ............................................................................ 152
5.6.7.1 Overview ......................................................................................................................................1525.6.7.2 Layout ...........................................................................................................................................1525.6.7.3 Communication procedures.......................................................................................................161
5.6.8 Informational Commands ................................................................................................... 1635.6.9 Status commands ................................................................................................................ 164
5.6.9.1 Overview ......................................................................................................................................1645.6.9.2 Layout ...........................................................................................................................................1645.6.9.3 Message Interface ........................................................................................................................1655.6.9.4 Data elements...............................................................................................................................166
5.6.10 Test commands.................................................................................................................... 1665.6.10.1 Overview ..................................................................................................................................1665.6.10.2 Layout.......................................................................................................................................1665.6.10.3 Message Interface ....................................................................................................................1665.6.10.4 Data elements ..........................................................................................................................1675.6.10.5 Defines ......................................................................................................................................167
5.6.11 Communication Procedures................................................................................................ 1685.6.12 Data Commands ................................................................................................................. 170
5.6.12.2 Communication procedures ..................................................................................................1735.6.12.3 Interface specific items............................................................................................................173
5.6.13 HCI Error values ................................................................................................................ 1745.7 TIMER SERVICE (TIM) ................................................................................................................ 176
5.7.1 Interface Timer.................................................................................................................... 1765.7.1.1 Overview ......................................................................................................................................1765.7.1.2 Layout ...........................................................................................................................................1765.7.1.3 Message Interface ........................................................................................................................1765.7.1.4 Data elements...............................................................................................................................176
Bluetooth PC Reference Stack by Ericsson
Communication procedures ................................................................................................................ 177
6. TEST SAMPLE APPLICATION SUITE...................................................................................... 178
6.1 TESTSAMPLE APPLICATION........................................................................................................ 1786.1.1 Client type of application .................................................................................................... 1806.1.2 Server type of application.................................................................................................... 1816.1.3 Security type of application ................................................................................................ 182
6.2 SUPPORT API.............................................................................................................................. 1836.2.1 Function library module ..................................................................................................... 183
BTAPI_ConnectRfcomm ..............................................................................................................................183BTAPI_ HandleMsg ......................................................................................................................................184BTAPI_ Init.....................................................................................................................................................184BTAPI_ InitStackForClient...........................................................................................................................184BTAPI_ Init Processes ...................................................................................................................................185BTAPI_ InitStackForServer ..........................................................................................................................185BTAPI_ RegisterProfile.................................................................................................................................185BTAPI_ Start...................................................................................................................................................185
6.2.2 BT profile support ............................................................................................................... 1866.2.3 Enhanced VOS module....................................................................................................... 186
EVOS_ Init......................................................................................................................................................186EVOS_ Receive ..............................................................................................................................................1866.2.3.1 EVOS_GetMsg..............................................................................................................................1866.2.3.2 EVOS_PutMsg..............................................................................................................................187
7. CHAT APPLICATION SUITE...................................................................................................... 189
7.1 BLUETOOTH NEIGHBOURHOOD ................................................................................................. 1897.2 CHAT CLIENT ............................................................................................................................. 1907.3 CHAT SERVER ............................................................................................................................. 191
8. APPENDIX 1 - DELIVERY STRUCTURE .................................................................................. 193
9. APPENDIX 2 – MSC TEST SAMPLE.......................................................................................... 194
10. APPENDIX 3 – SDC EXAMPLES............................................................................................. 197
10.1 APPENDIX 3.A : EXAMPLE SERVICE ATTRIBUTE....................................................................... 19710.2 APPENDIX 3.B : EXAMPLE (SERVICE SEARCH ATTRIBUTE) ....................................................... 19710.3 APPENDIX 3.C : EXAMPLE (SEARCHPATTERN) ......................................................................... 198
11. APPENDIX 4 – DBM EXAMPLES ........................................................................................... 199
11.1.1 Example of generating a typical DBM database service record .......................................... 19911.1.2 Examples of other attributes ............................................................................................... 201
Bluetooth PC Reference Stack by Ericsson
TABLE OF TABLESTABLE 1-1 ABBREVIATIONS ........................................................................................................................ 11TABLE 3-1 COM SERVER METHODS........................................................................................................... 16TABLE 3: GENERAL MESSAGES ..................................................................................................................... 19TABLE 4: COMMAND AND EVENT MESSAGES................................................................................................. 20TABLE 5: BT STACK INTERFACE OVERVIEW................................................................................................. 20TABLE 6: INTERFACE BETWEEN LAYER A TO B............................................................................................. 21TABLE 7: INTERFACE BETWEEN LAYER B AND A .......................................................................................... 23TABLE 8: GENERAL MESSAGE HEADER......................................................................................................... 24TABLE 9: CONTROL MESSAGE....................................................................................................................... 25TABLE 10: DATA MESSAGE........................................................................................................................... 26TABLE 11: PARAMETERS OF INTERFACE BETWEEN LAYER A TO LAYER B .................................................... 27TABLE 12: FUNCTION AND MESSAGE NAMING.................................................................................................. 31TABLE 13: INTERFACE BETWEEN ANY LAYER TO MSG .................................................................................. 31TABLE 14: PARAMETERS OF INTERFACE BETWEEN ANY LAYER TO MSG ....................................................... 32TABLE 15: INTERFACE BETWEEN ANY LAYER TO STATE ............................................................................... 33TABLE 16: PARAMETERS OF INTERFACE BETWEEN ANY LAYER TO STATE .................................................... 33TABLE 2 : FUNCTION INTERFACE OF THE START PROCEDURE........................................................................ 37TABLE 3 : MESSAGE INTERFACE OF START PROCEDURE................................................................................ 37TABLE 4 : DATA ELEMENTS OF START PROCEDURE....................................................................................... 38TABLE 5 : FUNCTION INTERFACE OF DATA & VOICE LINK SET UP PROCEDURE ............................................. 40TABLE 6 : MESSAGE INTERFACE OF DATA & VOICE LINK SET UP PROCEDURE .............................................. 41TABLE 7 : DATA ELEMENTS FOR DATA & VOICE LINK SET UP PROCEDURE................................................... 43TABLE 8 : FUNCTION INTERFACE OF DATA & VOICE LINK DISCONNECT PROCEDURE ................................... 46TABLE 9 : MESSAGE INTERFACE OF DATA & VOICE LINK DISCONNECT PROCEDURE .................................... 47TABLE 10 : DATA ELEMENTS FOR DATA & VOICE LINK DISCONNECT PROCEDURE ....................................... 47TABLE 11 : FUNCTION INTERFACE OF THE PAIRING CONTROL PROCEDURE .................................................. 49TABLE 12 : MESSAGE INTERFACE OF THE PAIRING CONTROL PROCEDURE ................................................... 49TABLE 13 : DATA ELEMENTS FOR THE PAIRING CONTROL PROCEDURE........................................................ 50TABLE 14 : GENERAL RESULT CODES.............................................................................................................. 51TABLE 5-15 FUNCTION INTERFACE OF COM’S START PROCEDURE ............................................................... 55TABLE 5-16 MESSAGE INTERFACE OF COM’S START PROCEDURE ................................................................ 56TABLE 5-17 DATA ELEMENTS OF COM’S START PROCEDURE ....................................................................... 56TABLE 5-18 FUNCTION INTERFACE OF COM’S CONNECTION PROCEDURE .................................................... 59TABLE 5-19 MESSAGE INTERFACE OF COM’S CONNECTION PROCEDURE ..................................................... 59TABLE 5-19 DATA ELEMENTS OF COM’S CONNECTION PROCEDURE............................................................. 60TABLE 5-20 FUNCTION INTERFACE OF COM’S COLLECTIVE INTERFACE ....................................................... 62TABLE 5-21 MESSAGE INTERFACE OF COM’S COLLECTIVE INTERFACE........................................................ 62TABLE 5-22 DATA ELEMENTS OF COM’S COLLECTIVE INTERFACE ............................................................... 62TABLE 5-23 FUNCTION INTERFACE OF COM’S DATA INTERFACE.................................................................. 65TABLE 5-24 MESSAGE INTERFACE OF COM’S DATA INTERFACE................................................................... 65TABLE 5-25 DATA ELEMENTS OF COM’S DATA INTERFACE .......................................................................... 65TABLE 5-26 FUNCTION INTERFACE OF SERIAL PORT EMULATION INTERFACE................................................ 67TABLE 5-27 MESSAGE INTERFACE OF SERIAL PORT EMULATION INTERFACE................................................. 69TABLE 5-28 DATA ELEMENTS OF SERIAL PORT EMULATION INTERFACE ........................................................ 69TABLE 5-30 DEFINED CONSTANTS/TYPES WITHIN THE COM COMPONENT. .................................................. 71TABLE 5-30 : FUNCTION INTERFACE OF CONNECT PROCEDURE.................................................................... 77TABLE 5-31 : MESSAGE INTERFACE OF CONNECT PROCEDURE..................................................................... 77TABLE 5-32 : DATA ELEMENTS OF CONNECT PROCEDURE............................................................................ 78TABLE 5-33 : GENERAL ERROR CODES ......................................................................................................... 78TABLE 5-34 : FUNCTION INTERFACE OF SERVICE DISCOVERY PROCEDURE 1 ............................................... 80TABLE 5-35 : MESSAGE INTERFACE OF SERVICE DISCOVERY PROCEDURE 1 ................................................ 80TABLE 5-36 : DATA ELEMENTS FOR SERVICE DISCOVERY PROCEDURE 1 ..................................................... 82TABLE 5-37 : STRUCT TDATAELEMENT IN SDC ........................................................................................... 83TABLE 5-38 : FUNCTION INTERFACE OF SERVICE DISCOVERY PROCEDURE 2 ............................................... 85TABLE 5-39 : MESSAGE INTERFACE OF SERVICE DISCOVERY PROCEDURE 2 ................................................ 86TABLE 5-40 : DATA ELEMENTS FOR SERVICE DISCOVERY PROCEDURE 2 ..................................................... 87TABLE 5-41 : FUNCTION INTERFACE OF DISCONNECT PROCEDURE............................................................... 89TABLE 5-42 : MESSAGE INTERFACE OF DISCONNECT PROCEDURE................................................................ 89
Bluetooth PC Reference Stack by Ericsson
TABLE 5-43 : DATA ELEMENTS OF DISCONNECT PROCEDURE....................................................................... 89TABLE 5-44 : FUNCTION INTERFACE OF SUPPORT PROCEDURES ................................................................... 90TABLE 5-45 : DATA ELEMENTS OF SUPPORT PROCEDURE............................................................................. 91TABLE 5-46 : STRUCTS FOR SUPPORT PROCEDURES...................................................................................... 92TABLE 5-47: FUNCTION INTERFACE OF START PROCEDURE .......................................................................... 95TABLE 5-48: MESSAGE INTERFACE OF START PROCEDURE........................................................................... 95TABLE 5-49: DATA ELEMENTS OF START PROCEDURE.................................................................................. 96TABLE 5-50 : GENERAL ERROR CODES ......................................................................................................... 96TABLE 5-51 : STRUCT TDATAELEMENT IN DBM.......................................................................................... 97TABLE 5-52 : STRUCT TDATABASE WITH TYPE OF DATABASE....................................................................... 98TABLE 5-53 : FUNCTION INTERFACE OF WRITE ACTIONS............................................................................ 100TABLE 5-54 : MESSAGE INTERFACE OF WRITE ACTIONS............................................................................. 101TABLE 5-55 : DATA ELEMENTS OF WRITE ACTIONS.................................................................................... 102TABLE 5-56 : FUNCTION INTERFACE FOR READ ACTIONS ........................................................................... 104TABLE 5-57 : MESSAGE INTERFACE FOR READ ACTIONS ............................................................................ 104TABLE 5-58 : DATA ELEMENTS OF READ ACTIONS ..................................................................................... 106TABLE 5-59 : FUNCTION INTERFACE FOR MISCELLANEOUS ACTIONS ......................................................... 108TABLE 5-60 : MESSAGE INTERFACE FOR MISCELLANEOUS ACTIONS .......................................................... 108TABLE 5-61 : DATA ELEMENTS FOR MISCELLANEOUS ACTIONS ................................................................. 109TABLE 5-62: FUNCTION INTERFACE OF SDS START PROCEDURE................................................................ 111TABLE 5-63: MESSAGE INTERFACE OF SDS START PROCEDURE................................................................. 111TABLE 5-64: DATA ELEMENTS OF SDS START PROCEDURE ....................................................................... 111TABLE 5-65 : GENERAL ERROR CODES ....................................................................................................... 111TABLE 5-66 : L2CA_TQOS DATA ELEMENTS .............................................................................................. 131TABLE 5-67- FUNCTIONS OF COMMON INTERFACE...................................................................................... 134TABLE 5-68- MESSAGES OF COMMON INTERFACE ...................................................................................... 134TABLE 5-69- DATA ELEMENTS OF COMMON INTERFACE............................................................................. 134TABLE 5-70 - DEFINES OF COMMON INTERFACE ......................................................................................... 134TABLE 5-71 - FUNCTIONS OF LINK CONTROL COMMANDS.......................................................................... 137TABLE 5-72 - MESSAGES OF LINK CONTROL COMMANDS........................................................................... 140TABLE 5-73 - DATA ELEMENTS OF LINK CONTROL COMMANDS................................................................ 143TABLE 5-74 - DEFINES OF LINK CONTROL COMMANDS .............................................................................. 145TABLE 5-75 - FUNCTIONS OF LINK POLICY COMMANDS ............................................................................. 149TABLE 5-76 - MESSAGES OF LINK POLICY COMMANDS .............................................................................. 150TABLE 5-77 - DATA ELEMENTS OF LINK POLICY COMMANDS .................................................................... 150TABLE 5-78 - DEFINES OF LINK POLICY COMMANDS .................................................................................. 151TABLE 79 - FUNCTIONS OF HOST CONTROLLER & BASEBAND COMMANDS .................................................. 154TABLE 5-80 - MESSAGES OF HOST CONTROLLER & BASEBAND COMMANDS............................... 157TABLE 5-81 - DATA ELEMENTS OF HOST CONTROLLER AND BASEBAND COMMANDS .................................. 159TABLE 5-82 - DEFINES OF HOST CONTROLLER & BASEBAND COMMANDS ................................................... 161TABLE 5-83 - FUNCTIONS OF INFORMATIONAL COMMANDS ...................................................................... 163TABLE 5-84 - MESSAGES OF INFORMATIONAL COMMANDS ........................................................................ 163TABLE 5-85 - DATA ELEMENTS OF INFORMATIONAL COMMANDS............................................................... 164TABLE 5-86 - DEFINES OF INFORMATIONAL COMMANDS ............................................................................ 164TABLE 5-87 - FUNCTIONS OF STATUS COMMANDS...................................................................................... 165TABLE 5-88 - MESSAGES OF STATUS COMMANDS....................................................................................... 165TABLE 5-89 - DATA ELEMENTS OF STATUS COMMANDS............................................................................. 166TABLE 5-90 - FUNCTIONS OF STATUS COMMANDS...................................................................................... 166TABLE 5-91 - MESSAGES OF STATUS COMMANDS....................................................................................... 167TABLE 5-92 - DATA ELEMENTS OF STATUS COMMANDS............................................................................. 167TABLE 5-93 - DEFINES OF STATUS COMMANDS .......................................................................................... 167TABLE 5-94 - FUNCTIONS OF DATA COMMANDS......................................................................................... 170TABLE 5-95 - MESSAGES OF DATA COMMANDS.......................................................................................... 171TABLE 5-96 - DATA ELEMENTS OF DATA COMMANDS................................................................................ 171TABLE 5-97 - DEFINES OF DATA COMMANDS ............................................................................................. 172TABLE 5-98 - HCI ERROR VALUES.............................................................................................................. 175TABLE 5-99 : FUNCTION INTERFACE OF TIMER ........................................................................................... 176TABLE 5-100 : MESSAGE INTERFACE OF TIMER .......................................................................................... 176TABLE 5-101: DATA ELEMENTS OF TIMER FUNCTION/MESSAGES .............................................................. 177TABLE 6-1 FILE DESCRIPTION OF THE SAMPLE APPLICATION ..................................................................... 179
Bluetooth PC Reference Stack by Ericsson
TABLE 6-2 CLIENT APPLICATION FLOWCHART .......................................................................................... 181TABLE 6-3 FILE DESCRIPTION OF THE SUPPORT COMPONENT..................................................................... 183
Bluetooth PC Reference Stack by Ericsson
TABLE OF FIGURES
FIGURE 1-1 AN OVERVIEW OF THE PC REFERENCE STACK AND ITS COMPONENTS. .................................... 3FIGURE 1-2. WHAT IS A BLUETOOTH PROFILE?............................................................................................ 6FIGURE 1-3. SUPPORTED PROFILES AND ROLES............................................................................................ 7FIGURE 2-1. SELECT DESTINATION FOLDER ............................................................................................... 13FIGURE 2-2. SELECT COMPONENTS ............................................................................................................ 14FIGURE 2-3. SELECT PROGRAM FOLDER.................................................................................................... 14FIGURE 2-4 CURRENT SETTINGS INFORMATION ........................................................................................ 15FIGURE 2-5 SETUP PROCEDURE COMPLETE ............................................................................................... 15FIGURE 4-1 THE API WILL GIVE ACCESS TO THE SERVICES PROVIDED BY THE PROTOCOLS IN THE STACK.
18FIGURE 10: MSC OF GENERAL MESSAGES ..................................................................................................... 19FIGURE 11: COMMAND AND EVENT MESSAGES................................................................................................. 19FIGURE 12: START UP MSC........................................................................................................................... 27FIGURE 13: REGISTRATION MSC .................................................................................................................... 28FIGURE 14: DE-REGISTRATION MSC............................................................................................................. 28FIGURE 15: CONNECTION SET-UP MSC......................................................................................................... 29FIGURE 16: DISCONNECT MSC...................................................................................................................... 29FIGURE 17: DATA TRANSMISSION MSC ........................................................................................................ 30FIGURE 2 : MSC FOR DATA & VOICE LINK SET UP PROCEDURE .................................................................... 44FIGURE 3 : MSC FOR DATA & VOICE LINK DISCONNECT PROCEDURE........................................................... 48FIGURE 4 : MSC FOR THE PAIRING CONTROL PROCEDURE ........................................................................... 50FIGURE 5-5 COM CONTEXT .......................................................................................................................... 54FIGURE 5-6 START COM COMPONENT. ......................................................................................................... 56FIGURE 5-7 SIGN-UP TO THE COM COMPONENT. .......................................................................................... 57FIGURE 5-8 DE-REGISTRATION OF A SERVER(APPLICATION).......................................................................... 57FIGURE 5-9 INFORMATION ABOUT DATA-SIZE. .............................................................................................. 58FIGURE 5-10 SETTING UP CONNECTION. ........................................................................................................ 60FIGURE 5-11 DISCONNECTING A CONNECTION. ............................................................................................. 63FIGURE 5-12 RFCOMM’S FLOW CONTROL. .................................................................................................. 63FIGURE 5-13 TEST RFCOMM CONNECTION. ................................................................................................ 64FIGURE 5-14 TRANSFERRING DATA. .............................................................................................................. 66FIGURE 5-15 REMOTE PORT SETTINGS. .......................................................................................................... 71FIGURE 5-16 PORT-FLOW DIRECTION SETTINGS............................................................................................. 72FIGURE 5-17 SEND MODEM-STATUS SIGNALS. ............................................................................................... 73FIGURE 5-18 SEND LINE-STATUS SIGNALS. .................................................................................................... 74FIGURE 5-19 : SDC PROTOCOL INTERFACE OVERVIEW ................................................................................ 76FIGURE 5-20 : MSC FOR CONNECT PROCEDURE ........................................................................................... 79FIGURE 5-21 : MSC FOR SERVICE DISCOVERY PROCEDURE 1....................................................................... 84FIGURE 5-22 : MSC FOR SERVICE DISCOVERY PROCEDURE 2 COMBINATION............................................... 88FIGURE 5-23 : PROTOCOL OVERVIEW DBM .................................................................................................. 94FIGURE 5-24: PROTOCOL INTERFACE OVERVIEW DBM................................................................................. 94FIGURE 5-25 : MSC OF START PROCEDURE .................................................................................................. 99FIGURE 5-26 : MSC FOR WRITE ACTIONS ON THE DATABASE..................................................................... 102 FIGURE 5-27 : MSC FOR READ ACTIONS................................................................................................... 107FIGURE 5-28 : MSC FOR MISCELLANEOUS ACTIONS................................................................................... 110FIGURE 5-29 : MSC OF SDS START PROCEDURE........................................................................................ 111FIGURE 5-30 MSC FOR STARTING L2CA : MSC_START .......................................................................... 116FIGURE 5-31 MSC FOR REGISTERING TO L2CA: MSC_REGISTER........................................................... 116FIGURE 5-32 MSC FOR DEREGISTERING FROM L2CA: MSC_DEREGISTER............................................. 116FIGURE 5-33 MSC FOR REQUESTING IF AN ACL IS IN USE BY L2CA............................................................ 117FIGURE 5-34 MSC OF SETTING UP A CONNECTION ...................................................................................... 119FIGURE 5-35 MSC OF TERMINATING A CONNECTION .................................................................................. 119FIGURE 5-36 MSC OF TERMINATING A NON-EXISTENT CONNECTION........................................................... 120FIGURE 5-37 MSC OF DISCONNECTION IN CASE OF E.G. OUT OF RANGE ..................................................... 120FIGURE 5-38 MSC OF CONFIGURATION SEQUENCE (FOR ONE DIRECTION)................................................... 123FIGURE 5-39 MSC OF A SINGLE DATA TRANSFER ....................................................................................... 125
Bluetooth PC Reference Stack by Ericsson
FIGURE 5-40 MSC OF AN INFO REQUEST ................................................................................................... 128FIGURE 5-41 MSC OF AN ECHO REQUEST.................................................................................................. 128FIGURE 5-42 EXAMPLE OF A COMPLETE MSC ............................................................................................ 129FIGURE 5-43 - CONTEXT OF HCI ................................................................................................................. 133FIGURE 5-44 - HCI INITIALISATION............................................................................................................. 135FIGURE 5-45 - ACL CONNECTION WITH PAIRING ........................................................................................ 145FIGURE 5-46 - ACL CONNECTION WITH AUTHENTICATION ........................................................................ 146FIGURE 5-47 - INQUIRY ............................................................................................................................... 146FIGURE 5-48 - PERIODIC INQUIRY ............................................................................................................... 147FIGURE 5-49 – QOS SETUP .......................................................................................................................... 151FIGURE 5-50 - READ LINKKEY.................................................................................................................... 161FIGURE 5-51 – SET INQUIRY FILTER............................................................................................................ 162FIGURE 5-52 - SET CONNECT FILTER........................................................................................................... 162FIGURE 5-53 - LOCAL LOOPBACK MODE..................................................................................................... 168FIGURE 5-54 - REMOTE LOOPBACK MODE .................................................................................................. 169FIGURE 5-55 - USAGE OF DATA FUNCTIONS ................................................................................................ 173FIGURE 5-56: MSC OF TIMER USE............................................................................................................... 177FIGURE 6-1 HOW THE DIFFERENT PARTS OF THE SAMPLE APPLICATION INTERACTS WITH EACH OTHER, THE
STACK AND VOS. ................................................................................................................................ 178FIGURE 6-2 TEST SAMPLE CLIENT INTERFACE......................................................................................... 179FIGURE 6-3 TEST SAMPLE SERVER INTERFACE........................................................................................ 180FIGURE 6-4 TEST SAMPLE SECURITY INTERFACE. ................................................................................... 180
Bluetooth PC Reference Stack by Ericsson
Page 1
1. INTRODUCTION
1.1 About this Document
This document describes the interface and the functionality provided by the Bluetooth PCReference Stack. It also covers the set-up procedure of the PC Reference Stack.This, the first, chapter explains the purpose of and the benefits of using the Bluetooth PCReference Stack which is based upon the Bluetooth Host Stack provided by Ericsson. Theforthcoming chapters will handle the following topics:The second chapter discusses the set-up procedure of the PC Reference Stack.The last chapters describe the interface used by an application that uses the services provided bythe PC Reference Stack.
1.2 Introduction
The Bluetooth PC Reference Stack gives the customer a high quality, ready to use modulecontaining selected higher level Bluetooth protocols to be integrated in a Windows environment.The Bluetooth PC Reference Stack will run in a Windows NT, 98 or 2000 environment hereafterwe refer to as Windows or Win32 environment.
The Bluetooth PC Reference Stack communicates downwards towards a Bluetooth Module on aserial interface.
By purchasing the Bluetooth PC Reference Stack the customer will get:
• Convenient and easy access to higher level Bluetooth protocols
• High Quality and Interoperability
• A product with a uniform interface with the Bluetooth HOST stack provided by Ericsson.
Put shortly it allows the customer to focus on the application level and system aspects of hisBluetooth solution.
Bluetooth PC Reference Stack by Ericsson
Page 2
1.3 Deliverables
1.3.1 Delivery objects
A delivery contains the following objects:
• Users Manual (This document)
• Bluetoooth PC Reference Stack
1. A Bluetoooth PC Reference Stack. Executable of a COM-server, containing theBluetooth HOST Stack.
2. TestSample application suite:This suite contains 3 separate applications that work together as an applicationover RFCOMM, showing the basic use of the Stack. This application can be usedas an example when wrting non-windows based programs on top of the Stack.This PC-reference Stack delivery is then used only as a developmentenvironment for other environments.
3. Chat application suite.This suite contains 3 separate applications that work together as an applicationover RFCOMM, showing the basic use of the Stack. This application can be usedas an example when writing windows specific programs on top of the Stack.
For the structure of the delivery see section 8 - Appendix 1 - Delivery structure.
Bluetooth PC Reference Stack by Ericsson
Page 3
1.4 System Level Description
Windows COM server
Windows - COM client framework
Application
HCI Driver
RFCOMM
L2CAP
SDP
HCI-Firmware
Link Manager
Application
Bluetooth PC Refernce Stack
Serial Interface
Bluetooth Module
Bluetooth Host Stack by Ericsson
ApplicationProgrammers Interface(API)
Host Stack by Ericsson
Radio
Base Band
COMServerInterface
Figure 1-1 An overview of the PC Reference Stack and its components.
Bluetooth PC Reference Stack by Ericsson
Page 4
1.5 Supported Bluetooth Adapted Protocol Layers
The Stack containing the following higher layers/Interfaces of the Bluetooth protocol stack,compliant to the Bluetooth foundation specification:
• RFCOMM
• SDP
• L2CAP
• HCI Driver (Host side Interface driver)
RFCOMM - is a transport protocol, with additional provisions for emulating RS-232 serial ports.The RFCOMM-protocol supports up to 60 simultaneous connections between two BT devices.For the purposes of RFCOMM, a complete communication path involves two applications runningon different devices with a communication segment between them. RFCOMM is able tostransmit/receive data packets of up to 32 KB over such a link. In this context, the termapplication may mean other things than end-user application, e.g. higher layer protocols or otherservices acting on behalf of end-user applications.
SDP Service Discovery Protocol - Discovery of services is a crucial part of the Bluetoothframework. Service discovery is fundamental for all the usage models. The SDP provides ameans for applications to discover which services are available and to determine thecharacteristics of those available services using an existing L2CAP connection. After that, anappropriate separate connection between two or more Bluetooth devices can be establishedusing information obtained via SDP.The service discovery application does not make use of SDP as a means of accessing a service,but rather as a means of informing the user of a Local Device the services that are available tohis/her device by (and possibly via) Remote Device(s).
L2CAP Logical Link Control and Adaptation Protocol - provides connection-oriented andconnectionless data services to upper layer protocols with protocol multiplexing capability,segmentation and reassemble operation, and group abstractions. L2CAP permits higher levelprotocols and applications to transmit and receive L2CAP data packets up to 64 KB in length.
HCI Driver Host Controller Interface - The HCI Interface establishes the communication betweenthe Stack and the HCI Firmware in the Bluetooth hardware connected to the equipment runningthe Stack. The HCI Interface ensures that the Stack can run over a generic hardware. The HCIInterface is standardised by the Bluetooth SIG. The HCI driver, as developed in this software, issplit into a Generic Component (GC) and an Environment Dependent Component (EDC).
Bluetooth PC Reference Stack by Ericsson
Page 5
1.6 Conceptual description of the PC Reference Stack
The PC Reference Stack is the Ericsson generic HOST stack applied to a Win32 environment. Itworks on Windows NT, 98 and 2000. This makes it an ideal tool when developing and testingBluetooth applications.
The PC Reference Stack could also be used as a building block developing BT application in aWin32 environment.
Bluetooth PC Reference Stack by Ericsson
Page 6
1.7 Supported Bluetooth Profiles & Roles
A profile defines a selection of messages and procedures from the Bluetooth specifications andgives an unambiguous description of the air interface for specified services and use cases.
A Bluetooth Profile
Defines how to implementspecific use cases.
Defines which provided andadapted protocols to use.
“Sometimes” defines whichapplication to use.
Puts requirements on eachindividual protocol.
Defines which options areconsidered mandatory.
Defines parameter ranges.
VCARD
SDP
L2CAP
RadioBaseLM
BasicProtocols
AdaptedProtocols
RFCOM TCS
OBEX ProvidedProtocols
Applications
Protocol LayerMandatoryFunctions
Optional Functions ParametersParameter X: Y
Figure 1-2. What is a Bluetooth profile?
Bluetooth PC Reference Stack by Ericsson
Page 7
Device A Device B
Serial Port Profile
Local Remote
Service DiscoveryApplication Profile
Terminal Gateway
CordlessTelephonyProfile
Terminal
Intercom Profile
DT LAN Acc P
LAN Access Profile
Client Server
Generic ObjectExchange
Audio GW Headset
Headset Profile
DT Gateway
Dial-up Networking
DT Gateway
Fax Profile
A-Party B-Party
Generic Access Profile(MANDATORY)
Push Client Push
Object Push Profile
Client Server
File Transfer Profile
IrMC Client IrMC Server
Synchronisation
BluetoothProtocols
BluetoothProfiles
Based onAT Commands
SDRFCOMML2CAP
SDRFCOMML2CAP
TCS BinaryL2CAP
Figure 1-3. Supported profiles and roles.
The Stack supports all profiles coloured in the schematics above but any restriction imposed onthe current release is listed in the release notes.
Note:The current release of the Stack does not contain the TCS Binary protocol; thus neither theintercom profile nor the cordless profile is supported.LAN access profile requires master slave switch that is not supported in current Bluetoothhardeware.
Bluetooth PC Reference Stack by Ericsson
Page 8
1.8 Bluetooth Applications
A number of usage models are identified by the Bluetooth SIG as fundamental and are thereforehighlighted in the Bluetooth documentation. These user models indicate what kind of applicationsBluetooth is intended for. The user models that are applicable to the Stack are described in thissection.
The four general profiles defined; Generic Access Profile (GAP), the Serial Port Profile, theService Discovery Application Profile (SDAP) and the Generic Object Exchange Profile (GOEP),are the base for all user models and their profiles.
File Transfer - The File Transfer usage model offers the capability to transfer data objects fromone Bluetooth device to another. Files, entire folders, directories and streaming media formats aresupported in this usage model. This usage model also offers a possibility to browse the contentsof the folders on a remote device. Furthermore, push and exchange operations are covered in thisusage model, e.g., business card exchange using the vCard format.
Internet Bridge - The Internet Bridge usage model describes how a mobile phone or cordlessmodem provides a PC with dial-up networking capabilities without need for physical connection tothe PC. This networking scenario needs a two-piece protocol stack, one for AT-commandsneeded to control the mobile phone and another stack to transfer payload data.
LAN Access - The LAN Access usage model is similar to the Internet Bridge user model. Thedifference is that the LAN Access usage model does not use the protocols for AT-commands. Theusage model describes how data terminals use a LAN access point as a wireless connection to aLocal Area Network. When connected, the data terminals operate as if it they were connected tothe LAN via dialup networking.
Synchronisation - The synchronisation usage model provides means for automaticsynchronisation between for instance a desktop PC, a portable PC, a mobile phone and anotebook. The synchronisation requires business card, calendar and task information to betransferred and processed by computers, cellular phones and PDAs utilising a common protocoland format.
Three-in-One Phone - The Three-in-One Phone usage model describes how a telephonehandset may connect to three different service providers. The telephone may act as cordlesstelephones connecting to the public switched telephone network at home charged at a fixed linecharge. This scenario includes making calls via a voice base station, and making direct callsbetween two terminals via the base station. The telephone can also connect directly to othertelephones acting as a “walkie-talkie” or handset extension i.e. no charging. Finally, the telephonemay act as a cellular telephone connecting to the cellular infrastructure. The cordless andintercom scenarios use the same protocol stack.
Ultimate Headset - The Ultimate Headset usage model defines how a Bluetooth equippedwireless headset can be connected to act as a remote unit’s audio input and output interface. Theunit is probably a mobile phone or a PC for audio input and output. As for the Internet Bridge usermodel, this model requires a two-piece protocol stack; one for AT-commands needed to controlthe mobile phone and another stack to transfer payload data, i.e. speech. The AT commandscontrols the telephone regarding for instance answering and terminating calls.
Bluetooth PC Reference Stack by Ericsson
Page 9
1.9 An Introduction to the API
The API to the stack is an Ericsson proprietary API, which is designed to be as environmentindependent and flexible as possible.
For example, the API allows the customer to:
• Establish and tear down data/voice connections
• Send and receive data
• Perform specific Bluetooth functions (often mapped directly to the HCI specification) such asperforming inquiries and page function and changing between different power save modes,select encryption, etc.
• Dynamically load a profile
• Add his own API complement suitable for his needs and the selected environment. This couldfor example be a socket interface in the UNIX world.
• Access the L2CAP layer directly in order to be able to implement new protocols on top ofL2CAP by yourself.
1.10 Quality and Interoperability
1.10.1 Two Different Architectures
1.10.1.1 In the Bluetooth Specifications
The Bluetooth specification specifies two fundamentally different solutions, which can roughly bedescribed as below:
• The One Processor Architecture
The application resides together with the Bluetooth protocols (RFCOMM, SDP, L2CAP, LM,BB and RF) in the same hardware.
• The Two Processor Architecture
The application resides together with the higher level Bluetooth protocols (RFCOMM, SDPand L2CAP) in one piece of hardware. The HCI Driver is also present in order tocommunicate with a second piece of hardware.
The second piece of hardware contains the lower level Bluetooth protocols (LM, BB and RF).This piece of hardware has a corresponding HCI Interpreter that handles the communicationwith the first piece of hardware.
Bluetooth PC Reference Stack by Ericsson
Page 10
1.10.1.2 In Ericsson’s Implementation
Ericsson has developed the protocol layers in the Stack keeping the above in mind. The sameimplementation of the protocol layers RFCOMM, SDP and L2CAP will be part of a variety ofEricsson Bluetooth products, either in the one processor architecture or the two processorarchitecture.
1.10.2 Summary
Ericsson will guarantee that the Stack as well as the individual protocol layers are following thespecifications and that the concerned Ericsson products are participating in interoperability tests,with Ericsson products as well as third party products, on a regular basis.
This ensures that the quality and interoperability of the Stack will be kept on the highest possiblelevel. And that the product is a living product that will be enhanced and supported by Ericssoncontinuously.
Bluetooth PC Reference Stack by Ericsson
Page 11
1.11 Abbreviations used in this document
Abbreviations Explanation
ACL Asynchronous Connection
BT Bluetooth
COD Class Of Device
DBM Database Manager
DLCI Data Link Connection Identifier
EDC Environment Dependent Component
GC Generic Component
HAL Hardware Abstraction Layer
HCI Host Controller Interface
L2CAP Logical Link Control and Adaptation Protocol
OS Operating System
PIN Personal Identification Number
RFCOMM Serial cable emulation protocol based on ETSI TS 07.10
SCO Synchronous Connection
SDC Service Discovery Client
SDP Service Discovery Protocol
SDS Service Discovery Server
SIG Special Interest Group
USB Universal Serial Bus
VOS Virtual Operating System
Table 1-1 Abbreviations
1.12 References
[1] Title : BLUETOOTH SPECIFICATION Version 1.0BTitle : BLUETOOTH BASEBAND SPECIFICATION Version 1.0BAuthor : Bluetooth SIG
1.13 Glossary
• AttributeIDIdentifierpart of an attribute in a service record
• AttributeValueValuepart of an attribute in a service record. There are different kinds of attributevalues. Avalue can be a regular value like an integer or a string, but also a structure, a so-calleddataelement sequence with UUID’s (descriptors)
• ComponentA component can either be a hardware or a software component. In the scope of thisdocument the term component is used for a software component. The component is thelowest level of detail described in this document. A further decomposition of the component
Bluetooth PC Reference Stack by Ericsson
Page 12
and a detailed design is done in the Software Design Documents (SDD, one for eachcomponent).
• Data Element SequenceSee [1].
• DescriptorUUID (Universally Unique Identifier) In a sense, this could be seen as some sort of afilestructure with directories being the descriptors and the descriptorvalues (parameters)being the files. A UUID is actually 128 bits long, but using shortcuts it can also be 16 or 32bits. See also AttributeValue above.
• ModuleA software module contains a set of (one or more) software functions. Usually a module isstored in a file on the software development system. A module is the lowest level ofconfiguration item within the configuration management system.
• ServiceA service is any entity that can provide information, performan action, or control a resource on behalf of another entity.
• SystemA system can either be a hardware or a software system. In the scope of this document theterm system is used for a software system. A software system is composed out of one ormore software components.
Bluetooth PC Reference Stack by Ericsson
Page 13
2. INSTALLATION AND SET-UP
2.1 Introduction
This chapter describes installation procedure of the Bluetooth PC Reference Stack.
2.2 Installation procedure
This release is delivered as an install shield, where you have to run ‘setup’ after unpacking thezip-file. This setup will also install the PC reference stack as a COM-server to your PC. Thestructure of the delivery is described in section 8-Appendix 1 - Delivery structure
Figure 2-1. Select destination folder
Bluetooth PC Reference Stack by Ericsson
Page 14
Figure 2-2. Select components
Figure 2-3. Select Program Folder
Bluetooth PC Reference Stack by Ericsson
Page 15
Figure 2-4 Current settings information
Figure 2-5 Setup procedure complete
Bluetooth PC Reference Stack by Ericsson
Page 16
3. GUIDE LINES – COM SERVER INTERFACE
This chapter describes the interface to the COM server.
Because of crossing process boundaries and the usage of COM techniques the interface towardsthe HOST Stack have to be altered in a Windows environment.
3.1 COM-Server Specific METHODS
All methods implemented that are related to the inter-process communication in the HOST Stack.
Currently there is no unique initialisation method; all initialisation is done automatic when statingan application that is accessing the Bluetooth PC Reference Stack.
3.1.1 COM-Server Methods – Overview
The following list contains the methods towards the Bluetooth Stack.
COM Server Method Comment(s)
SendMsg () This method is used to send a message.
MsgReceived () The receive functionality is event driven.
GetCurrentProcessID () The method returns the ID of the current BT protocolStack Process
GetExternalProcessID () This methods returns the ID of a process specified by it’sname in ‘ProcessName (Safe Arrays).
Table 3-1 COM Server Methods.
Memory allocation is done automatically when messages are send/received.
3.1.2 COM-Server Methods – Interface description
SendMsg
Method: void SendMsg (Message, ReceiverID)
Description:This method is used to send a message to a BT protocol stack Process. This methods crossesthe process boundaries, PC boundaries are not excluded.Parameters:Message is the actual message (a Safe Arrays) and not a pointer to a message.ReceiverID The receiving process ID
Bluetooth PC Reference Stack by Ericsson
Page 17
MsgReceived
Event: void MsgReceived (Message, SenderID)
Description:This is not a method but an event. The client is notified when a message arrives. The event isimplemented as a publisher subscriber pattern with connection points.Parameters:Message contains the actual message (Safe Arrays).SenderID contains the process ID from the sender of the message.
GetCurrentProcessID
Method: void GetCurrentProcessID ()
Description:The method returns the ID of the current BT Process.
GetExternalProcessID
Method: void GetExternalProcessID (ProcessName)
Description:This method returns the ID of a process specified by its name in ‘ProcessName’. When the nameis not found, 0 is returned.Parameters:ProcessName contains the process name as a string (Safe Arrays).
Bluetooth PC Reference Stack by Ericsson
Page 18
4. GUIDE LINES – WRITING BLUETOOTH APPLICATIONS
This chapter describes the interface used by an application that uses the services provided by theStack.
4.1 Introduction
HC I Drive r - G C
RFC O M M
L2C AP
SDP
OS A
daptation
HC I Drive r - EDC
A p p lic a t io n
ApplicationProgrammersInterface
VOSInterface
SILInterface
SC M
Figure 4-1 The API will give access to the services provided by the protocols in the Stack.
RFCOMM, SDP L2CAP and HCI are the OSI stack components described by the Bluetooth SIGsee section 1.5.
SCM Stack Connection Manager – The Stack Connection Manager, that is an Ericssonproprietary component, handles and administrates the bluetooth baseband connection.
Bluetooth PC Reference Stack by Ericsson
Page 19
5. API DESCRIPTIONS
5.1 Global API DescriptionsThe next figure shows the general message traffic of the BT Stack layers.
Layer B
AIR
Layer A Layer B Layer A
Request (Req)
Confirm (Cnf/CnfNeg)
Indication (Ind)
Response (Rsp/RspNeg)
FunctionMessage
Figure 2: MSC of general messages
Basically layer A (higher layer) communicates with layer B (lower layer) to send control messagesor communicates peer to peer for data messages. A control message exchanges information toanother layer. A data message passes through the stack, where each layer adds its header to thedata packet. On the other side the header is removed in each layer.Note: If a layer component sends a request it may not send another request to the same layerbefore receiving the reply belonging to the first request.In the chapter Data elements an explanation is given how the multiple responses are indicated.
The messages in Figure 2 have the following notation:
Type Short Function/Message
Request Req Function
Confirm Cnf Message
Response Rsp Function
Indication Ind Message
Table 2: General Messages
Event (Evt)
Layer A Layer B
Command (Cmd)
Layer A Layer B
Figure 3: Command and event messages
Command messages are sent from a higher layer to a lower layer. A command message is arequest message without a corresponding confirm.
Bluetooth PC Reference Stack by Ericsson
Page 20
An event message is sent from a lower layer to a higher layer. An event message is an Indicationwithout a corresponding response.These messages have the following notation:
Type Short Function/Message
Command Cmd Function
Event Evt Message
Table 3: Command and event messages
5.1.1 Interface Overview
Table 4 states all the interfaces that are present in BT Stack. For all of the Interfaces a single IDDis written. Each document describes its interface to a higher layer.
Interface Document Description Reference
To HCI IDD HCI Interface description of HCI (layer and driver) 5.6
To L2CAP IDD L2CAP Interface description of L2CA 5.5
To SDC IDD SDC Interface description of SDC 5.4.1
To RFCOMM IDDRFCOMM
Interface description of RFCOMM 5.3
To SCM IDD SCM Interface description of Stack Connection Manager 5.2
To DBM IDD DBM Interface description of DBM 5.4.2
Table 4: BT Stack Interface Overview
5.1.2 Layer to LayerThe next section describes the communication between two protocol layers.
5.1.2.1 Message layoutThe messages are defined in the components IDD’s. But all the protocol components have thesame kind of messages. The next table shows these messages that are used in every protocolcomponent. For the layer specific messages look in the specific IDD of the component. See Table4: BT Stack Interface Overview.
Bluetooth PC Reference Stack by Ericsson
Page 21
5.1.2.1.1 A2BThis section describes the standard message that can be called by another layers. (A - > B).
Name Parameters Function Description
B_ReqStart uint16 uiSeqNr, Start message to start component
B_ReqRegister uint16 uiSeqNr, seeIDD’s
Control function for set up control connection between twolayers
B_ReqDeRegister uint16 uiSeqNr, seeIDD’s
Control function for control disconnection between twolayers
B_ReqConnect uint16 uiSeqNr,
int16 iResult,
see IDD’s
Control function for set up connection with task B (peer topeer)
B_RspConnect uint16 uiSeqNr, seeIDD’s
Control function for set up connection successful with peer
B_ReqDisconnect uint16 uiSeqNr, seeIDD’s
Control function for disconnection with task B (peer to peer)
B_RspDisconnect uint16 uiSeqNr, seeIDD’s
Control function for disconnection successful with task B
B_DataSend Uint8 uiSeqNr,uint8 *pucData,
uint16 uiLengthsee IDD’s
Data function for sending data to the other peer
B_RspData Uint8 uiSeqNr,
int16 iResult
Data function for successfully sending data to peer
B_DataAlloc uint16 uiLength Allocates a buffer containing a MSG_TDataMsg and aLength in bytes.
B_DataFree uint8 *pucData Frees buffer created with B_DataAlloc. Pointer is a bytearray to the data buffer
B_DataExtract MSG_TDataMsg*ptDataInd,
uint16 *puiLength,See IDD’s
Extract the header information and data from ptDataInd.Function returns length and pointer to the start of the data
Table 5: Interface between Layer A to B
The parameters in Table 5 are explained in Table 10.If a layer wants to make use of the services of another layer it has to register itself to it. This canbe done with the request register function that is present in every protocol layer. If this is done thetwo layers have an interface with each other. Registration must be done before a connectionacceptance can be attempted. If a layer doesn’t want to make use of another layer anymore, itcan call the request de-registration function.
When a layer offers a connection-oriented service, another layer can set up a connection with thislayer via the request connect function. The connection is then set up peer to peer. There can be anumber of connections between two layers and peers. There is not a function for responsenegative disconnect because a disconnect should always succeed.The length in B_DataAlloc defines the number of bytes the requester wants to put into this buffer,where this routine adds enough header and trailer space for a copy less transfer of the data buffer
Bluetooth PC Reference Stack by Ericsson
Page 22
through the stack. The returned data pointer, points to the start location in this buffer where therequester can put its data.If a data buffer is allocated, data can be sent peer to peer. With the Data Send function data canbe sent. This function also has a Length parameter that defines the number of bytes the requesterhas put into the buffer. This Length should be less than the original requested Length in the DataAlloc function. Where Length = 0 is interpreted as being equal to the original requested Length.When the Length is not equal to 0, the new Length will be placed in the message; but only whenthe new length is shorter than the requested length. Otherwise this will result in a negative reply.
Bluetooth PC Reference Stack by Ericsson
Page 23
5.1.2.1.2 B2AThis section states the standard messages that are sent by another task.(B - > A). Each message has a standard message header as explained in Table 8
Name Contents Message Description
B_TstartCnf see IDD’s Start message confirm for start component
B_TregisterCnf see IDD’s Control message for confirm set up control connection
B_TregisterCnfNeg see IDD’s Control message for negative confirm set up control connection
B_TdeRegisterCnf see IDD’s Control message for confirm control disconnection
B_TdeRegisterCnfNeg see IDD’s Control message for negative confirm control disconnection
B_TconnectCnf see IDD’s Control message for confirm set up connection with task B
B_TconnectCnfNeg see IDD’s Control message for negative confirm set up connection withtask B
B_TconnectInd see IDD’s Control message for set up connection at peer side
B_TdisconnectCnf see IDD’s Control message for confirm disconnection with task B
B_TdisconnectCnfNeg see IDD’s Control message for negative confirm disconnection with task B
B_TdisconnectInd see IDD’s Control message for disconnection at peer side
B_TDataCnf see IDD’s Data message for confirm sending data to the other peer
B_TdataCnfNeg see IDD’s Data message for negative confirm sending data to the otherpeer
B_TdataInd see IDD’s Data message for sending data at peer side
Table 7: Interface between Layer B and A
5.1.2.2 Data elementsThe next section describes the Data elements used in the functions and messages. It alsoexplains the different message headers. Each message has a General header. When themessage is a control message, a Control header follows the General header. If the message is adata message, a Data header follows the General header.
Bluetooth PC Reference Stack by Ericsson
Page 24
5.1.2.2.1 General HeaderMessages can be split up into two groups: control and data messages. These two have a differentmessage header, but also have a common first 32 bit. These first 32 bits header are calledMsgID.
Name Size(bits)
Value/
Range
Description
MSG 1 1 Static bit, This bit is always 1 because some Operating Systems usethis 16 bit value and do not expect that this value can be zero
MsgType 15 0-0x7FFF This field defines the several message types (Connect, Register, etc).supported by its component.
CmpID 8 0-0xFF Identification of a component in the stack. This depends on theproduct (this determents the number of components used). In aglobal header file all the components will be given a uniquecomponent identifications.
C 1 0-1 Continuation bit,
0 - last message in a sequence (also if there is only one response)
1 - message is part of a multiple response message
Spare 3 0 These bits are for future use, Default Spare will be set to all 0’s
4 0-7 0b0000 = MSG_OSI_REQ, Request Message0b0001 = MSG_OSI_CNF, Confirm Message0b0010 = MSG_OSI_IND, Indication Message0b0011 = MSG_OSI_RSP, Response Message0b0100 = MSG_OSI_CMD, Command Message0b0101 = MSG_OSI_CNF_NEG, Negative Confirm Message0b0110 = MSG_OSI_EVT Event Message0b0111 = MSG_OSI_RSP_NEG Negative Response Message
Table 8: General Message Header
5.1.2.2.2 Defines
typedef uint32 MSG_TMsgID;
typedef struct{ MSG_TMsgID tID; /* Unique identification of the msg. */} MSG_TMsgHdr;
typedef struct{ MSG_TMsgHdr tHdr;
} MSG_TMsg;
Bluetooth PC Reference Stack by Ericsson
Page 25
5.1.2.2.3 Control Message
The first 32 bits represent a unique identification for the message as described in 5.1.2.2.1
5.1.2.2.4 General Header (MsgID)
Name Size(bits)
Value/
Range
Description
MsgID 32 - See Table 8: General Message Header
uiSeqNr 16 0-0xFFFF Sequence number. The reply of a message must always have thesame sequence number as the received message. This can be used tomatch multiple outstanding messages (Req/Ind) with the responses(Cnf/Rsp).
iResult 16 0-0xFFFF Result values, can be given here depending on a specific message.See IDD of a specific component and message.
Result > 0 indicates a positive reply
Result = 0 a positive reply (MSG_POS_RESULT)
Result < 0 indicates a negative reply
Table 9: Control Message
5.1.2.2.5 Defines
typedef struct{MSG_TControlHdr tHdr; /* Common header for a control msg. */
} MSG_TControlMsg;
typedef struct{MSG_TMsgID tID;uint16 uiSeqNr;int16 iResult;
} MSG_TControlHdr;
5.1.2.3 Data Message
The first 32 bits represent a unique identification for the message as described in 5.1.2.2.1
5.1.2.4 General Header
Bluetooth PC Reference Stack by Ericsson
Page 26
General Header (MsgID)
Name Size(bits)
Value/
Range
Description
MsgID 32 - See Table 8: General Message Header
ucSeqNr 8 0-0xFF Sequence number. The reply of a message must always have thesame sequence number as the received message. This can be used tomatch multiple outstanding messages (Req/Ind) with the responses(Cnf/Rsp).
ucOffset 8 0-0xFF Offset of the Data value. If the offset is 0 the data begins at thebeginning of the Data field. Else there is an offset of x bytes.
ucData - - Data values, can be of any type, or can contain no data. See IDD of aspecific component and message.
Table 10: Data Message
5.1.2.4.1 Definestypedef struct{MSG_TDataHdr tHdr; /* Common header for a data msg. */uint8 ucData; /* Start of the data area containing */
/* the data packet. (Byte array) */
} MSG_TDataMsg;
typedef struct{MSG_TMsgID tID;uint8 ucSeqNr;uint8 ucOffset;
} MSG_TDataHdr;
5.1.2.4.2 Parameters of interface
Name Type Description
ucSeqNr uint8 Sequence number. Can be used to match multipleoutstanding messages (Req/Ind) with the responses(Cnf/Rsp). In the Data function Calls for Req/Ind theucSeqNr is the first parameter.
uiSeqNr Uint16 Sequence number. Can be used to match multipleoutstanding messages (Req/Ind) with the responses(Cnf/Rsp). In the function calls for Req/Ind the uiSeqNr isthe first parameter.
*ptDataInd MSG_TDataMsg Pointer to message data of a Data Indication.
*pucData uint8 Data values, can be of any type, or can contain no data. SeeIDD of a specific component and message.
tHandle Local type see IDD’s THandle can be the instance or channel where the datamust be send over or to.
Bluetooth PC Reference Stack by Ericsson
Page 27
uiLength uint16 Length in bytes indicates the length of the data.
iResult int16 Result values, can be given here depending on a specificmessage. See IDD of a specific component and message.
Result > 0 indicates a positive replay
Result = 0 a positive replay (MSG_POS_RESULT)
Result < 0 indicates a negative replay
Table 10: Parameters of interface between Layer A to Layer B
5.1.2.4.3 Communication procedures
5.1.2.4.4 Start
Layer CLayer A Layer B Layer D
D_ReqStart
C_TStartCnf
B_ReqStartC_ReqStart
B_TStartCnfD_TStartCnf
Figure 4: Start up MSC
Before making use of a component the B_ReqStart is sent to the component. The componentsends a positive B_TstartCnf message back. After this a Register and any other function can becalled. When a component uses lower layer components (in this case C and D) it has to startthem as well before send the B_TstartCnf back. No other messages may be send to the Stackbefore the B_ReqStart function.
5.1.2.4.5 Registration
AIR
Layer A Layer B Layer B Layer A
B_ReqRegister
B_TRegisterCnfRegistration successful
B_TRegisterCnfNegRegistration unsuccessful
Client Server
Bluetooth PC Reference Stack by Ericsson
Page 28
Figure 5: Registration MSC
A Server must register to a lower level with B_ReqRegister. This is done because the lower layerthen knows where to send his received messages. A Client layer does not need to register itself,because it receives messages from a higher layer and thereby knows were to send his responseback to. Only for some asynchronous messages, typically connect indication all connectionoriented messages have a destination as defined during connection set-up/acceptance.If the registration is successful B_TRegisterCnf the two layers can set-up connections and senddata. When the registration fails, B_TRegisterCnfNeg, layer B can probably not handle moreregistration.Server Registration has no effect on the Client side.This registration contains also an implicit subscription to all or some Indication/Event messagesgenerated by the lower layer. If this subscription must be changed there is a subscription requestfunction in most of the protocol layers. (See the IDD of the specific component).
5.1.2.4.6 De-Registration
AIR
Layer A Layer B Layer B Layer A
B_ReqDeRegister
B_TDeRegisterCnf
Client Server
Figure 6: De-Registration MSC
When a Server does not want to use a lower layer any more it can de-register itself withB_ReqDeRegister. If the de-registration is done, there can not be a connection set up and datatransfer on the Client side any more. A B_TDeRegisterCnf message is always successful even ifthere is no registration at all. De-registration has no effect on the Client.
5.1.2.4.7 Connection Set up
Bluetooth PC Reference Stack by Ericsson
Page 29
AIR
Layer A Layer B Layer B Layer A
B_ReqConnect
B_TConnectCnf
B_TConnectInd
B_RspConnect(positive result)
Connection Successful
B_TConnectCnfNeg B_RspConnect(negative result)
Connection Unsuccessful
Client Server
Figure 7: Connection Set-up MSC
A Client can set up a connection with a Server by calling the B_ReqConnect function of theprotocol layer it wants to use. If the Server has done a registration a B_TConnectInd is received.The layer A, at the Server side, can decide if a connection is accepted and then send aB_TConnectCnf. Also layer B of the Client can decide if a connection can be set up, because theServer Bluetooth device can be out of range. This will return a B_RspConnect with a negativeresult as parameters, which results in a B_TconnectCnfNeg message.
5.1.2.4.8 Disconnect
AIR
Layer A Layer B Layer B Layer A
B_ReqDisconnect
B_TDisconnectCnfB_TDisconnectEvt
Client/Server Client/Server
Figure 8: Disconnect MSC
When a connection is established and there is no more use of it, the connection can bedisconnected. The Client or Server must send a B_ReqDisconnect to the lower layer, layer Bbreaks down the connection with the Server. At the other side a B_TDisconnectEvt is sent to letlayer A know that the connection is no longer there. A B_TDisconnectEvt can also be sent whenthe other device is out of range. A disconnection is always successful (B_DisconnectCnf), exceptfor HCI. Because a disconnect on ACL connections can be done, when a SCO connection is stillactive. This then results in a HCI_TdisconnectCnfNeg message.
5.1.2.4.9 Data Transmission
Bluetooth PC Reference Stack by Ericsson
Page 30
AIR
Layer A Layer B Layer B Layer A
B_DataSend
B_TDataCnf
B_TDataInd
B_RspData(positive result)
B_DataAlloc
Data Send Successful
B_TDataNegCnf B_RspData(negative result)
Data Send Unsuccessful
Client/Server Client/Server
B_DataExtract
B_DataAlloc
B_DataFree
Layer A Alloc's data but desides not tosend the message
Figure 9: Data Transmission MSC
When a Client or Server wants to send data to the other peer it has to have a connection, beforedata can be sent. The highest layer (the Application or layer) must call the B_DataAlloc function,this allocates memory in the stack and the highest layer can put its data in there. After this, aB_DataSend can be called to a lower layer. This function call has a pointer to allocated memoryas parameter. If there is a lower layer the B_DataSend function of this layer can be called, etc. Inthis way the data will not copied in the stack, but only the pointer is passed trough the stack. Atthe peer side a B_TdataInd delivers the data to layer A. This layer can then call theB_DataExtract function to retrieve a pointer to the data block and the length of it.If the data is received correctly a B_RspData, with a positive result as parameter, is sent back tothe other side. If the Data is incorrect a negative result is sent in the B_RspData function.If the highest layer allocates data and sends a data message the memory is freed by the stack itself (lowest possible layer). At the other side the lowest layer allocates memory for the incomingmessage. The layer that receives the message (the highest layer) frees this memory.When the highest layer allocates data, but later decides not to send this data it can free the datawith the B_DataFree function.
5.1.2.5 Interface specific itemsNaming convention of Message and functions
Name Description Function name Message name
Req Request Cmp_ReqFunctionName -
Cnf Confirm - CMP_MESSAGENAME_CNF
CnfNeg Negative Confirm - CMP_MESSAGENAME_CNF_NEG
Rsp Response Cmp_RspFunctionName -
RspNeg Negative Response Cmp_RspNegFunctionName -
Ind Indication - CMP_MESSAGENAME_IND
Bluetooth PC Reference Stack by Ericsson
Page 31
Cmd Command Cmp_CmdFunctionName -
Evt Event - CMP_MESSAGENAME_EVT
Table 12: Function and Message naming
For more information about specific messages of a component, see IDD of this component.
5.1.3 Layer to MSG
The next section describes the communication between a layer and the Message library. Thisinterface is a function interface, which means that the message function runs in the layer task.
5.1.3.1 Message layout
5.1.3.1.1 Layer2MsgThis section describes the standard functions that can be called by any layer to the messagelibrary. (Layer -> Msg). All the functions and macros are there to help the layer handle andmanipulate a message.
Function Names Description
MSG_TMsg *MSG_Alloc(int16 iLength, MSG_TMsgID tID)
Function allocates Length bytes of memory from the heap and fillsthe message header with the ID tID. The function returns a pointerof MSG_TMsg to the message.
extern uint8 *MSG_DataMap(MSG_TDataMsg *ptDataMsg)
This routine returns a byte-pointer to that location of the Data in aData Message. This is the place where the actual data starts.
void MSG_Reply(MSG_TMsg **pptMsg, int16 iResult)
Function replies to the sender of a received message. The resultcode determines if the reply is negative or positive.
MSG_ID(ucCmpID, uiMsgType, ucOSI) This macro creates a message ID. It shifts the parameters to therecorrect position within the message ID.
MSG_DATA_CLEAR_HDR(ptDataReq, ucHdrLength)
This macro clears the bytes in ptDataReq->ucData. It starts withthe first byte and sets them to zero until the byte number indicatedby 'HdrLength'
MSG_DATA_ADD_HEADER(ptDataReq, ucHdrLength)
This macro adds data bytes to a Data Request message bydecreasing the Offset parameter in MSG_TdataMsg withHdrLength.
MSG_DATA_STRIP_HEADER(ptDataInd, ucHdrLength)
This macro strips data bytes to a Data Request message byincreasing the Offset parameter in MSG_TdataMsg withHdrLength.
Table 13: Interface between any Layer to Msg
5.1.3.2 Data elementsThe Msg functions have the following data elements.
Name Type Description
iLength int16 The length (in bytes) of the allocated message
Bluetooth PC Reference Stack by Ericsson
Page 32
tID MSG_TMsgID The ID of the message. See Table 8
*ptDataMsg MSG_TDataMsg The pointer that holds the Data message. See Table 10
**pptMsg MSG_TMsg The address of the pointer that holds the message. See Table 8
iResult int16 The Result of the message. See Table 9
ucCmpID uint8 This parameter defines the component. See Table 8
uiMsgType uint16 This parameter defines the message within the component. See Table 8
ucOSI uint8 This parameter holds the OSI command. See Table 8
*ptDataReq Data Request msg This pointer holds a data request
*ptDataInd Data Indication msg This pointer holds a data indication
ucHdrLength uint8 This parameter hold a length in bytes
Table 14: Parameters of interface between any Layer to Msg
5.1.3.3 Communication proceduresNot applicable.
5.1.4 Layer to State
The next section describes the communication between a layer and the State library. Thisinterface is a function interface, which means that the state function runs in the task of acomponent. The State library implements a state machine, which can be used to call functionsdepending on an incoming message. It is up to the application or component to use this statemachine library.If an incoming message is received by a component it can be given to the state machine. Thestate machine determines in which function the message must be handled. This function is calledto perform actions on the message. Also certain states can be set so the same message can behandled differently in a different state.
5.1.4.1 Message layout
5.1.4.1.1 Layer2StateThis section describes the standard functions that can be called by any layer to the state library.(Layer - > State). The state functions and macros are there to help the Layer to create andmanipulate the state machine. It is possible to use multiple State machines in one task.
Function Names Description
void STATE_Machine(MSG_TMsg **pptMsg, void**ppAdmin)
This function is the actual state machine and call's the statehandling functions. If the state has changed, it will check forentry and exit functions that belong to that state.
Void STATE_SetNext (STATE_TState tState, void *pAdmin) This function will bring the state machine to the specified a
State, when the current state is completed.
STATE_TState STATE_GetNext (void *pAdmin) This function returns the next state of the state machine
Bluetooth PC Reference Stack by Ericsson
Page 33
STATE_TState STATE_GetPrevious (void *pAdmin) This function returns the state prior to the current state of thestate machine.
STATE_TState STATE_GetCurrent (void *pAdmin) This function returns the current state of the state machine
void *STATE_CreateInstance (STATE_TMachineAdmin *ptAdmin, uint16 uiSize)
This function creates and initialises an instance. It allocatesthe amount of memory for the user as specified by
uiSize. A pointer to this memory is passed to the statehandling functions when called.
void STATE_DeleteInstance (void **ppAdmin) This function frees the allocated instance
void STATE_SetInitialState (void *pAdmin,
STATE_TState TInitialState)
This function sets the initial state of the state machine
and calls the entry function when present
STATE_NR_EVENTS(a) Calculate nr of events from event table
STATE_NR_STATES(a,b) Calculate nr of states from event and state table
Table 15: Interface between any Layer to State
5.1.4.2 Data elementsThe State (STATE) functions have the following data elements.
Name Type Description
**ppMsg MSG_TMsg pointer pointer to the received message. See 5.1.2.2.2
**ppAdmin Void pointer pointer to instance of the administration
tState STATE_TState State of a state machine, defined by user
*pAdmin Void pointer to administration of the instance
*ptAdmin STATE_TMachineAdmin holds the pointer to administration of state machine
uiSize uint16 Size in bytes of administration
tInitialState STATE_TState Initial State of a state machine, defined by user
Table 16: Parameters of interface between any Layer to State
5.1.4.2.1 Definestypedef const struct /* Administration for the state machine */{
uint32 uiNrOfEvents;uint32 uiNrOfStates;const MSG_TMsgID *ptEventTable;const STATE_THandler *ptStateTable;
} STATE_TMachineAdmin;
typedef uint16 STATE_Tstate;
5.1.4.3 Communication proceduresThe communication procedure is very simple always from the layer to the State library. Anexample how to set-up a state table is given here to show the communication procedure.First the state table must be implemented. The state table of a component can be found in thecomponents SDD. The state table consists of rows and columns. The rows exist of the messages
Bluetooth PC Reference Stack by Ericsson
Page 34
the layer expects. The next bit of code shows an example how to fill the atMyEvents array withmessages.
static MSG_TMsgID atMyEvents[] = {EVENT1_EVT,COMMAND1_CMD,
COMMAND2_CMD,COMMAND3_CMD};
The columns of the table are made up of functions that handle a message in a specific state.static STATE_THandler atMystates[] = {/* First State */handle1 /* EVENT1_EVT */handle2 /* COMMAND1_CMD */handle3 /* COMMAND2_CMD */handle4 /* COMMAND3_CMD */handle5 /* enter */handle6 /* leave */
/* Second State */handleA /* EVENT1_EVT */handleB /* COMMAND1_CMD */handleC /* COMMAND2_CMD */handleD /* COMMAND3_CMD */handleE /* enter */handleF /* leave */ }
The initialisation function of a layer must fill in the following statements before the state machineis initialised.
STATE_TMachineAdmin tStateTable = {NR_EVENTS(atMyEvents),NR_STATES(atMyEvents,atMystates), atMyEvents, atMystates};
5.2 Stack Connection Manager Interface (SCM)
HC I Drive r
RFC O M M
L2C AP
SDP
OS A
daptation
Se ria l Line In te rfa c e
A p p lic a t io n
ApplicationProgrammersInterface
VOSInterface
SILInterface
SC M
The SCM component is part of the Ericsson Bluetooth stack. The SCM component handles andadministrates the bluetooth baseband connection. This section describes the Interface Designand the environment of the SCM software in the BT-Stack.
5.2.1 General description
GeneralGeneral
SCM is one of the components in the BT-Stack. SCM handles the control of the radio links.
• SCM has to be used for creating data links & voice links.• SCM takes care of the storage of link keys in case of paired links.
Bluetooth PC Reference Stack by Ericsson
Page 35
• SCM enables multiple applications on top of the Bluetooth stack setting up data & voice linksindependent from each other.
• SCM enables local routing in L2CAP, by generating a local handle when setting up a localdata link with the local bluetooth address.
Clients & ServersIn the context of this document a client device initiates the data & voice link set up(SCM_ReqConnect, SCM_ReqAddSco).In the context of this document a server device accepts or rejects the data & voice link set up(SCM_CONNECT_ACCEPT_IND, SCM_ADD_SCO_IND).
In the Bluetooth concept it is possible to have multiple clients and servers on top of the Bluetoothstack. Multiple clients can communicate with multiple servers using multiple protocol channelssharing the same data link.
Server3Client3
SCM L2CAP
RFCOMM
SCM L2CAP
RFCOMM
Client2Client1
HCI HCI
Server2Server1
Radio Link
Security handler
Security handler
VOICE HANDLER
SCM handles the data links as well as voice links. Sharing data links using protocol channels on adata link can not be done with voice links.In a multiple application situation one application has to handle the voice links. This application iscalled the voice handler. The voice handler is the only application able to do operations regardingvoice links.
Server3Client3
SCM L2CAP
RFCOMM
SCM L2CAP
RFCOMM
Client2Client1
HCI HCI
Server2Server1
Radio Link
Security handler
Security handler
Voice handler
Voice handler
A bluetooth piconet can contain a maximum of three voice links.• MASTER A has three SCO links with SLAVE B;
Bluetooth PC Reference Stack by Ericsson
Page 36
• MASTER A has two SCO links with SLAVE B and one SCO links with SLAVE C;• MASTER A has one SCO link with SLAVE B, one SCO link with SLAVE C and one SCO link
with SLAVE D.
Device AMASTER
Device BSLAVE
Device AMASTER
Device BSLAVE
Device CSLAVE
Device AMASTER
Device BSLAVE
Device CSLAVE
Device DSLAVE
Security handler
One of the applications on top of the stack will always be the security handler. The securityhandler is responsible for the following issues:• Pin-code handling. In case pairing is requested the security handler will be indicated to give a
pin-code.• Accepting or rejecting data link set up request. At connection set-up the security handler in
the Slave device will be indicated to accept or reject an incoming link request.• The data and voice links contains several configuration parameters. These parameters can
not be configured by several applications since these will lead to conflicting situations.Therefore it is only the security handler, which is able to change these parameters.
Overview
• Start Procedure (5.2.2)• Data & Voice Link Set up (5.2.3)• Data & Voice Link Disconnect Procedure (5.2.4)• Pairing Control Procedure (5.2.5)• Result Codes (5.2.6)
5.2.2 Start procedure
5.2.2.1 OverviewSCM has to be started in order to become operational.In order for the application to receive asynchronous events from SCM, SCM has to be informedabout the application. Therefore the application has to register to SCM.Following section describes the interface of the start procedure and registration procedure.
5.2.2.2 Function Interface
Name Parameters Function Description
Bluetooth PC Reference Stack by Ericsson
Page 37
SCM_ReqStart uiSeqNr This function has to be called to start theSCM component
SCM_ReqRegister uiSeqNr
tMessageGroup
This function will registrate theprocess to the requestedmessage group.
SCM_ReqDeRegister uiSeqNr
tMessageGroup
This function will de-registratethe process to the requestedmessage group.
Table 17 : Function Interface of the start Procedure
5.2.2.3 Message Interface
Name Contents Message Description
SCM_START_CNF tHdr SCM indicates it has been started.
SCM_REGISTER_CNF tHdr Succesfull registration to the requestedmessage group
SCM_REGISTER_CNF_NEG tHdr Registration not succesfull. Process notregistrated. Cause: process tried toregistrate to a one process only groupand the group is already occupied.
possible result code:
SCM_REGISTERED_ALREADY
SCM_DEREGISTER_CNF tHdr Successful de-registration
SCM_DEREGISTER_CNF_NEG tHdr Unsuccessful de-registration
Table 18 : Message Interface of start Procedure
Bluetooth PC Reference Stack by Ericsson
Page 38
5.2.2.4 Data elements
Name Type Value Description
tHdr MSG_TControlHdr - Holds MessageID of the messageand result value.
uiSeqNr uint16 - Sequence number. The reply of amessage must always have the samesequence number as the receivedmessage. This can be used to matchmultiple outstanding messages(Req/Ind) with the responses(Cnf/Rsp). In the function calls forReq/Ind the SeqNr is the firstparameter.
tMessageGroup SCM_TMessageGroup SCM_SECURITY_HANDLER
SCM_VOICE_HANDLER
SCM_MONITOR_GROUP
Table 19 : Data Elements of start Procedure
5.2.2.5 Communication procedures
SCM_ReqStartSCM_ReqStart
SCM_START_CNFSCM_START_CNF
SCM_ReqStart SCM_ReqStart
SCM_START_CNF SCM_START_CNF
SCM_ReqRegister(SCM_MONITOR_GROUP)SCM_ReqRegister(SCM_MONITOR_GROUP)
SCM_REGISTER_CNFSCM_REGISTER_CNF
SCM_ReqRegister(SCM_VOICE_HANDLER) SCM_ReqRegister(SCM_VOICE_HANDLER)
SCM_REGISTER_CNF SCM_REGISTER_CNF
SCM_ReqRegister(SCM_SECURITY_HANDLER) SCM_ReqRegister(SCM_SECURITY_HANDLER)
SCM_REGISTER_CNF SCM_REGISTER_CNF
Client SCM SecuritySCM ServerSecurity
Figure 1: MSC Start & Registration Procedure
Description
An application has to start SCM before using it.This is also the case in a multiple application situation. Each application has to call theSCM_ReqStart function. After receiving the SCM_TStartCnf message SCM is operational and isready to process further commands. All requests will be replied negative (result code:SCM_NEG_NOT_STARTED([see appendix for a result code description]) in case SCM has notbeen started.
Bluetooth PC Reference Stack by Ericsson
Page 39
In order to receive asynchrony messages like indications and events, registration is necessary.An application is able to register as:• SCM_MONITOR_GROUP;• SCM_VOICE_HANDLER;• SCM_SECURITY_HANDLER;
SCM_MONITOR_GROUP
Applications, which register as the SCM_MONITOR_GROUP, will be notified about created ordestroyed links(SCM_CONNECT_EVT, SCM_DISCONNECT_EVT).Exception:If an application is registered as SCM_MONITOR_GROUP and the application acts as a client bysetting up a link, then this application will not receive the SCM_CONNECT_EVT message. Theapplication already receives the link handle in the SCM_CONNECT_CNF message.
SCM_VOICE_HANDLER
Only one application can register as SCM_VOICE_HANDLER. Only the voice handler is grantedto call voice commands at client side. Only the voice handler will receive voice-related messagesat server side (SCM_ADD_SCO_ACCEPT_IND, SCM_ADD_SCO_EVT).
SCM_SECURITY_HANDLER
One of the applications on top of the BT-Stack is always registered asSCM_SECURITY_HANDLER. The security handler accepts or rejects data links and handles thepin-codes during pairing.
COMBINATIONS
It is possible to have combination of previous mentioned registration groups. For instance oneprocess can register to all groups.
5.2.3 Data & voice link set up procedure
5.2.3.1 OverviewFollowing section describes the interface of the Data & Voice link set up procedure.
5.2.3.2 Function InterfaceName Parameters Function DescriptionSCM_ReqConnect uiSeqNr
tAddresstPacketTypetPageScanRepModetPageScanModetClockOffsettAcceptRoleSwitch
This function is used to set up a dataconnection with an other Bluetoothdevice.
Bluetooth PC Reference Stack by Ericsson
Page 40
SCM_RspConnectAccept pptMsg
iResult
tAddress
tRole
This function is used by the securityhandler to accept or reject an incomming
connection request(SCM_TConnectAcceptInd). The securityhandler is able to indicate the role in thecreated piconet.
For negative response use result codes:
SCM_OE_USER_ENDED_CONNECTION
SCM_OE_LOW_RESOUCES
SCM_OE_POWER_OFF
SCM_ReqAddSco uiSeqNr
tHandle
tPacketType
This function is used to add a voiceconnection to an existing dataconnection.
SCM_RspPincode pptMsg
iResult
tAddress
tPincode
tPincodeLength
This function is used to response on theSCM_TPincodeInd message.
Pin-code exists:
iResult = SCM_POS_RESULT
No pin-code:
iResult =SCM_PAIRING_NO_ALLOWED
SCM_RspAddScoAccept pptMsg
iResult
tAddress
tRole
This function used by the voice handlerto accept or reject an incomming SCOconnection request(SCM_TAddScoAcceptInd)
The voice handler is able to indicate therole in the created piconet.
For negative response use result codes:
SCM_OE_USER_ENDED_CONNECTION
SCM_OE_LOW_RESOUCES
SCM_OE_POWER_OFF
Table 20 : Function Interface of Data & Voice link set up procedure
5.2.3.3 Message Interface
Name Contents Message Description
SCM_PINCODE_IND tHdr,
tAddress
This message will be send to the securityhandler if no link key is available andauthentication is requested.
Bluetooth PC Reference Stack by Ericsson
Page 41
SCM_CONNECT_CNF tHdr
tAddress
tHandle
tEncryptionMode
This message will be send to the initiatorin case a the link set up was successful.
SCM_CONNECT_CNF_NEG tHdr
tAddress
This message will be send to the initiatorin case a the link set up was notsuccessful.
SCM_CONNECT_ACCEPT_IND tHdr
tAddress
tCod
This message will be send to the securityhandler in case an other device tries toconnect. The security handler will acceptor reject the connection(SCM_RspConnectAccept)
SCM_CONNECT_EVT tHdr
tAddress
tHandle
tEncryptionMode
This message will be send to the monitorgroup in case the link set up wassuccessful.
SCM_ADD_SCO_CNF tHdr
tAddress
tHandle
This message will be send to theapplication which initiated the voice linkin case the set up was successful.
SCM_ADD_SCO_CNF_NEG tHdr
tAddress
This message will be send to theapplication which initiated the voice linkin case the link set up was not successful.
SCM_ADD_SCO_ACCEPT_IND tHdr
tAddress
tCod
This message will be send to the voicehandler in case another device tries toconnect. The voice handler needs toaccept or reject the connection(SCM_RspAddScoAccept)
SCM_ADD_SCO_EVT tHdr
tAddress
tHandle
tEncryptionMode
This message will be send to the monitorgroup in case a the link set up wassuccessful.
Table 21 : Message Interface of Data & Voice link set up procedure
5.2.3.4 Data elements
Name Type Value Description
Bluetooth PC Reference Stack by Ericsson
Page 42
uiSeqNr uin16 0..uint16 max. Holds the sequence number.The sequence number can beused for mapping REQ/CNF,IND/RSP messages.
tHdr MSG_TControlHdr - Holds Message ID of themessage.
thandle BT_THandle - The link handle is used toidentify a connection betweentwo Bluetooth devices.
tAddress BD_TAddress - See [4 ] Section:
13.1. BLUETOOTH DEVICEADDRESS
tPacketType SCM_TPacketType SCM_DM1
SCM_DH1
SCM_AUX1
SCM_DM3
SCM_DH3
SCM_DM5
SCM_DH5
SCM_HV1
SCM_HV2
SCM_HV3
SCM_DV
See [2] section:
4.4.2 SCO Packets
4.4.3. ACL Packets
tPageScanRepMode SCM_TPageScanRepMode SCM_R0
SCM_R1
SCM_R2
See [2] section:
10.6.2. Page Scan
tPageScanMode SCM_TPageScanMode SCM_MANDATORY_PAGE_SCAN_MODESCM_OPTIONAL_PAGE_SCAN_MODE_ISCM_OPTIONAL_PAGE_SCAN_MODE_IISCM_OPTIONAL_PAGE_SCAN_MODE_III
See [2] Section:
10.6. ACCESS PROCEDURES
Appendix VII :
OPTIONAL PAGINGSCHEMES
tRole SCM_TRole SCM_MASTER
SCM_SLAVE
See [2] Section:
10.2. Master-Slave Definition
Bluetooth PC Reference Stack by Ericsson
Page 43
tEncryptionMode SCM_TEncryptionMode SCM_ENCRYPTION_OFFSCM_ENCRYPTION_POINT_TO_POINTSCM_ENCRYPTION_POINT_TO_MULTI_POINT
See [2] Section:
14.3.2. Encryption Modes
tCod SCM_TCod - Class of Devices
See [3] Section:
1. Bluetooh BaseBand
Table 22 : Data Elements for Data & Voice link set up procedure
5.2.3.5 Communication procedures
Bluetooth PC Reference Stack by Ericsson
Page 44
Setup data linkNo AuthenticationServer registrated to SCM_MONITOR_GROUPVoice handler registrated to SCM_MONITOR_GROUP
SCM_ReqConnectSCM_CONNECT_ACCEPT_INDSCM_RspConnectAccept
SCM_CONNECT_CNFSCM_CONNECT_EVT
SCM_CONNECT_EVT SCM_CONNECT_EVT
Client does setup data linkNo AuthenticationVoice handler does setup data linkVoice handler adds voice
SCM_ReqConnectSCM_CONNECT_ACCEPT_INDSCM_RspConnectAccept
SCM_CONNECT_CNF
SCM_ReqConnectSCM_CONNECT_CNF
SCM_ReqAddScoSCM_ADD_SCO_ACCEPT_INDSCM_RspAddScoAccept
SCM_ADD_SCO_CNF SCM_ADD_SCO_EVT
Setup data linkWith AuthenticationServer registrated to SCM_MONITOR_GROUPVoice handler registrated to SCM_MONITOR_GROUP &SCM_VOICE_HANDLER & SCM_MONITOR_GROUPSecurity handler registered to SCM_MONITOR_GROUP
SCM_ReqConnectSCM_CONNECT_ACCEPT_INDSCM_RspConnectAccept
SCM_PINCODE_IND SCM_PINCODE_INDSCM_RspPincode SCM_RspPincode
SCM_CONNECT_CNF SCM_CONNECT_EVTSCM_CONNECT_EVT SCM_CONNECT_EVT
SCM_CONNECT_EVT SCM_CONNECT_EVT
Setup data linkWith AuthenticationClient and Server registrated as SCM_SECURITY_HANDLER &
SCM_ReqConnectSCM_CONNECT_ACCEPT_INDSCM_RspConnectAccept
SCM_PINCODE_IND SCM_PINCODE_INDSCM_RspPincode SCM_RspPincodeSCM_CONNECT_CNF
SCM_ReqAddScoSCM_ADD_SCO_ACCEPT_INDSCM_RspAddScoAccept
SCM_ADD_SCO_CNF SCM_ADD_SCO_EVT
Client SCM SecurityHandler
SCM ServerSecurity Handler
Voice Handler
VoiceHandler
Figure 10 : MSC for Data & Voice link set up procedure
Descriptions
SINGLE PROCESS APPLICATION
Registration
In order to use the voice functionality the application registers as SCM_VOICE_HANDLER.In order to be able to handle pincode indications the application registers also asSCM_SECURITY_HANDLER.
Bluetooth PC Reference Stack by Ericsson
Page 45
Data & Voice link set up with authentication: Client Side
To set up a data link the application calls the SCM_ReqConnect function. When the serveraccepts the data link set up the client will receive the SCM_PINCODE_IND message. The Clientthen responses the pin-code using the SCM_RspPincode function. On succesful authenticationthe client will receive the SCM_CONNECT_CNF message. The SCM_CONNECT_CNF_NEGmessage will be received in case the server rejected the data link or something when wrong atradio level. The result parameter in the MSG_TControlHdr type will contain the error code([seeappendix for a result code description]).To set up a voice link the application calls the SCM_ReqAddSco function. When the serveraccepts the voice link to be created, the client will receive the SCM_ADD_SCO_CNF message.The SCM_ADD_SCO_CNF_NEG message will be received when the server rejected the voicelink or something when wrong at radio level. The result parameter in the MSG_TControlHdr typecontains the error code ([see appendix for a result code description]).
Data & Voice link set up with authentication: Server Side
A remote device trying to set up a data link will result in receiving aSCM_TCONNECT_ACCEPT_IND at server side . The link set up can be accepted by calling theSCM_RspConnectAccept function with result parameter value SCM_POS_RESULT. Calling theSCM_RspConnectAccept function using result parameter value SCM_REJECT_PERSONAL willreject the link set up. After accepting the link set up the SCM_PINCODE_IND message will bereceived by the security handler in case of a not paired device. The SCM_RspPincode functionhas to be used to give a positive (pin-code included) or negative response.Local HandleIn case L2CAP local routing is required a data link has to be set up using the local bluetooth IEEEaddress. It is not possible to add a voice link to this data link.
MULTIPLE APPLICATIONSClients and Servers applications, which have to be notified about a newly created or ended datalink, need to register as SCM_MONITOR_GROUP. These client and server processes will receivea SCM_CONNECT_EVT message in case a data link has been created. TheSCM_DISCONNECT_EVT message will be received in case a link has ended.
Data & Voice link set-up with authentication in a multiple application environment
In a multiple application environment, client applications as well as server applications can existon the same stack. Each application can set-up a data link to the same remote devicesimultaneously. They all will receive the same data link handle on a successful link set-up. Whenauthentication is active, the SCM_PINCODE_IND message will only be send to the securityhandler.On data link set up every client and server application, which is part of the monitor group (exceptthe application which started the link set-up (SCM_ReqConnect)), will be notified(SCM_CONNECT_EVT).Servers, which are not in the monitor group, will not be notified about newly created data link.They will, if addressed, receive their XXX_CONNECT_IND from the protocol layer on protocolchannel set-up.Only the application, which is registered as SCM_VOICE_HANDLER, is able to create and endvoice links.
Bluetooth PC Reference Stack by Ericsson
Page 46
5.2.4 Data & voice link disconnect procedure
5.2.4.1 OverviewFollowing section describes the interface of the Data & Voice links disconnect procedure.
5.2.4.2 Function Interface
Name Parameters Function Description
SCM_ReqDisconnect uiSeqNr
tHandle
This function is used to end a data link withan other Bluetooth device.
SCM_ReqRemoveSco uiSeqNr
tHandle
This function is used to end a voice link withan other Bluetooth device.
Table 23 : Function Interface of Data & Voice link disconnect procedure
5.2.4.3 Message Interface
Name Contents Message Description
SCM_DISCONNECT_CNF tHdr
tHande
This message will be send to theinitiator in case a the link wasended successfully.
SCM_DISCONNECT_CNF_NEG tHdr
tHandle
This message will be send to theinitiator in case a the link was notended successfully.
SCM_REMOVE_SCO_CNF tHdr
tHandle
This message will be send to theinitiator in case a voice link wasended successfully.
SCM_REMOVE_SCO_CNF_NEG tHdr
tHandle
This message will be send to theinitiator in case a voice link wasnot ended successfully.
SCM_DISCONNECT_EVT tHdr
tHandle
This message will be send to themonitor group (except initiator) incase a link was endedsuccessfully.
In a link lost situation this eventwill be send to all the member ofthe link and to the monitor group.If the link member (link initiator) isalso in the monitor group thismessage will be send only ones.
Bluetooth PC Reference Stack by Ericsson
Page 47
SCM_REMOVE_SCO_EVT tHdr
tHandle
This message will be send to thevoice handler (except initiator) incase a voice link was endedsuccessfully.
In a link lost situation this eventwill be send to the voice handler.
Table 24 : Message Interface of Data & Voice link disconnect procedure
5.2.4.4 Data elements
Name Type Value Description
uiSeqNr uin16 0..uint16 max. Holds the sequence number.The sequence number can beused for mappingREQ/CNF, IND/RSPmessages.
tHdr MSG_TControlHdr See [6] Holds MessageID of themessage.
tHandle BT_THandle See [6] The link handle is used toidentify a connectionbetween two Bluetoothdevices.
Table 25 : Data Elements for Data & Voice link disconnect procedure
Bluetooth PC Reference Stack by Ericsson
Page 48
5.2.4.5 Communication procedures
V oice con ne ctio n e xis tsC lie nt1 h as p ro tocol link w ith Se r ve r 2C lie nt2 h as p ro tocol link w ith Se r ve r 1Se r ve r 2 r e g is te re d SCM _M ONITOR_GROUPV oice Han dle r r e g is te re d SCM _M ONITOR_GROUPC lie nt1 e n ds pr oto co l co nn e ction + d ata lin k w ith Se r ve r 1
SCM_ReqDis c onnec tSCM_DISCONNECT_CNFres ult c ode <==> SCM_DA TA _LINK_STILL_EXISTS
Se r ve r 1 e nd pr o to co l + d ata lin kSCM_ReqDis connectSCM_DISCONNECT_CNFres ult code <==> SCM_DA TA _LINK_STILL_EXISTS
V oice Han dle r r e m ove s coV oice han dle r e nd s d ata lin k
SCM_ReqRemoveSc oSCM_REMOV E_SCO_EV T
SCM_REMOV E_SCO_CNF
SCM_ReqDisc onnec tSCM_DISCONNECT_CNF SCM_DISCONNECT_EV Tres ult c ode <==> SCM_POS_RESULT SCM_DISCONNECT_EV T
C lie nt1 h as p ro tocol link w ith Se r ve r 1C lie nt2 h as p ro tocol link w ith Se r ve r 2C lie nt1 e n ds pr oto co l co ne ctio n + d ata lin k w ith Se r ve r1
SCM_ReqDis c onnec tSCM_DISCONNECT_CNFres ult c ode <==> SCM_DA TA _LINK_STILL_EXISTS
Se r ve r 2 e nd pr o to co l lin k + data link w ith Clie nt2
SCM_ReqDisc onnectSCM_DISCONNECT_EV T SCM_DISCONNECT_CNF
result c ode <==> SCM_POS_RESULTSCM_DISCONNECT_EV T SCM_DISCONNECT_EV T
C lient2 SC M SecurityH andle r
SC M Serve r1Secu rity H and ler
Voice H and ler
Vo iceH andle r
C lient1 Se rve r2
Figure 11 : MSC for Data & Voice link disconnect procedure
Descriptions
When ending a data link the following statements should be considered:A data link will be ended by SCM when:• All applications which created the link (SCM_ReqConnect) requested to end the specified
data link (SCM_ReqDisconnect).• No L2CAP channels exist using the specified data link.• No voice link(s) exist on the specified data link.• The link is lost due to link failure.
important:Each application should perform a disconnect command on protocol level before giving adisconnect command on SCM.
In a multiple application situation it is possible for each application to have a data link with deviceX. One of the application ending a data link must not influence the other applications. Asuccessful disconnect request will be have a SCM_TDisconnectCnf message as result.The possible result codes in the SCM_TDisconnectCnf are:• SCM_POS_RESULT: The data link with the addressed device has been ended;
• SCM_DATA_LINK_REMAINS_ACTIVE: The SCM administration has been modified but thedata link still exists (Other application still are using the data link).
Bluetooth PC Reference Stack by Ericsson
Page 49
5.2.5 Pairing control procedure
5.2.5.1 OverviewFollowing section describes the interface of the pairing control procedure.
5.2.5.2 Function Interface
Name Parameters Function Description
SCM_ReqDevicesPaired uiSeqNr
tAddress
tSelectionType
With this function an applicationcan check whether a device ispaired or not. Further it is possibleto query all paired devices.
SCM_ReqUnPairDevices uiSeqNr
tAddress
tSelectionType
With this function an applicationcan
unpair one or more device(s).
Table 26 : Function Interface of the Pairing Control Procedure
5.2.5.3 Message Interface
Name Contents Message Description
SCM_DEVICES_PAIRED_EVT tHdr
tAddress
information of one of thepaired devices
SCM_DEVICES_PAIRED_CNF tHdr,
uiMaxNrOfDevices,
uiNrOfDevicesRead
End of device pairedsequence plus result
SCM_UNPAIR_DEVICES_CNF tHdr,
tAddress
The specified device hasbeen unpaired.
SCM_UNPAIR_DEVICES_CNF_NEG tHdr The specified device hasnot been unpaired.
Table 27 : Message Interface of the Pairing Control Procedure
5.2.5.4 Data elements
Name type Value Description
uiSeqNr uin16 0..uint16 max. Holds the sequence number. Thesequence number can be used formapping REQ/CNF, IND/RSPmessages.
Bluetooth PC Reference Stack by Ericsson
Page 50
uiSeqNr uint16 -
tHdr MSG_TControlHdr See [6] Holds MessageID of the message.
tHandle BT_THandle See [6] Holds the handle to an data or voicelink
uiNrOfDevicesRead uint16 Number of paired device read
uiMaxNrOfDevices uint16 Max number of devices that can bestored non-volatile
tControlType SCM_TControlType SCM_ON
SCM_OFF
type used to control on/off selections
tSelectionType SCM_TSelectionType SCM_SPECIFIC_DEVICE
SCM_ALL_DEVICES
Selection type parameter is used tospecify one(specific) or more devices
tAddress BD_TAddress See [6] Hold the bluetooth IEEE address
Table 28 : Data Elements for the Pairing Control Procedure
5.2.5.5 Communication procedures
Check specific deviceSCM_ReqDevicesPairedSCM_DEVICE_PAIRED_EVTSCM_DEVICE_PAIRED_CNF
Unpair deviceSCM_ReqUnpairDevicesSCM_UNPAIR_DEVICES_CNF
Application SCM SCM
Figure 12 : MSC for the Pairing Control Procedure
Description
For checking devices being paired or not paired the SCM_ReqPairedDevices function has to beused.• For specific queries use a SCM_SPECIFIC_DEVICE;• Total query use SCM_ALL_DEVICES;
After successful pairing the link key information will be stored non-volatile automatically. Theapplication is responsible for the available space in the pairing storage. Using the functionSCM_ReqUnpairDevices an application can delete pairing relations.• Specific queries use a SCM_SPECIFIC_DEVICE;
Total query use SCM_ALL_DEVICES;
Bluetooth PC Reference Stack by Ericsson
Page 51
5.2.6 Result CodesMost of the result codes of SCM are directly derived from the HCI result codes.
Error result codes Value DescriptionSCM_POS_RESULT 0x0000 no error detectedSCM_DATA_LINK_REMAINS_ACTIVE 0x0001 Disconnect was requested and confirmed but
more application are using the data link, so thedata link remains active.
SCM_NEG_UNKNOWN_COMMAND 0x8001 Unknown SCM CommandSCM_NEG_NO_CONNECTION 0x8002 No ConnectionSCM_NEG_HW_FAILURE 0x8003 Hardware FailureSCM_NEG_PAGE_TIMEOUT 0x8004 Page TimeoutSCM_NEG_AUTH_FAILURE 0x8005 Authentication FailureSCM_NEG_KEY_MISSING 0x8006 Key MissingSCM_NEG_MEMORY_FULL 0x8007 Memory FullSCM_NEG_CONNECTION_TIMEOUT 0x8008 Connection TimeoutSCM_NEG_MAX_NUM_CONNECTIONS 0x8009 Max Number Of ConnectionsSCM_NEG_MAX_SCO 0x800A Max Number Of SCO Connections To A
DeviceSCM_NEG_MAX_ACL 0x800B Max Number Of ACL Connections To A
DeviceSCM_NEG_COMMAND_DISALLOWED 0x800C Command DisallowedSCM_NEG_REJECT_LIM_RESOURCE 0x800D Host Rejected due to limited resourcesSCM_NEG_REJECT_SECURITY 0x800E Host Rejected due to security reasonsSCM_NEG_REJECT_PERSONAL 0x800F Host Rejected due to remote device is only a
personal deviceSCM_NEG_HOST_TIMOUT 0x8010 Host TimeoutSCM_NEG_UNSUPPORTED 0x8011 Unsupported Feature or Parameter ValueSCM_NEG_INVALID_PARAMETERS 0x8012 Invalid SCM Command ParametersSCM_NEG_OE_USER_ENDED_CONNECTION 0x8013 Other End Terminated Connection: User
Ended ConnectionSCM_NEG_OE_LOW_RESOURCES 0x8014 Other End Terminated Connection: Low
ResourcesSCM_NEG_OE_POWER_OFF 0x8015 Other End Terminated Connection: About to
Power OffSCM_NEG_CONNECTION_TERMINATED 0x8016 Connection Terminated by Local HostSCM_NEG_REPEATED_ATTEMPS 0x8017 Repeated AttemptsSCM_NEG_PAIRING_NOT_ALLOWED 0x8018 Pairing Not AllowedSCM_NEG_UNKNOWN_LMP_PDU 0x8019 Unknown LMP PDUSCM_NEG_UNSUP_REMOTE_FEATURE 0x801A Unsupported Remote FeatureSCM_NEG_SCO_OFFSET_REJECTED 0x801B SCO Offset RejectedSCM_NEG_SCO_INTERVAL_REJECTED 0x801C SCO Interval RejectedSCM_NEG_AIR_MODE_REJECTED 0x801D SCO Air Mode RejectedSCM_NEG_INVALID_LMP 0x801E Invalid LMP ParametersSCM_NEG_UNSPECIFIED_ERROR 0x801F Unspecified ErrorSCM_NEG_UNSUP_LMP_VALUE 0x8020 Unsupported LMP Parameter ValueSCM_NEG_ROLE_CHANGE_NOT_ALLOWED 0x8021SCM_NEG_LMP_RESPONSE_TIMEOUT 0x8022SCM_NEG_LMP_ERROR_TRANSACTION_COLLISION 0x8023SCM_NEG_LMP_PDU_NOT_ALLOWED 0x8024SCM_NEG_LMP_DATA_FLUSHED 0x8025SCM_NEG_REGISTERED_ALREADY 0x8101 Client already register. Security handler
already registered.SCM_NEG_NOT_REGISTERED 0x8102 Tried to remove a not registered customerSCM_NEG_NOT_SCO_HANDLER 0x8103 An illegal action has be tried to perform on a
local data link handle.SCM_NEG_NOT_SECURITY_HANDLER 0x8104 Client performs a voice action but is not
granted to does so. An other process hasbeen registrated being the voice handler.
SCM_NEG_LOCAL_HANDLE 0x8105 Client performs a voice action but is notgranted to does so. An other process hasbeen registrated being the voice handler.
SCM_NEG_NOT_STARTED 0x8106 application performs a request command onSCM and SCM has not been started yet.
Table 29 : General Result Codes
Bluetooth PC Reference Stack by Ericsson
Page 52
Bluetooth PC Reference Stack by Ericsson
Page 53
5.3 RFCOMM protocol Interface (RFCOMM)
HC I Drive r
RFC O M M
L2C AP
SDP
OS A
daptation
Se ria l Line In te rfa c e
A p p lic a t io n
ApplicationProgrammersInterface
VOSInterface
SILInterface
SC M
RFCOMM is a complete communication path that involves two applications running on differentdevices with a communication segment between them. In this context, the term application maymean other things than end-user application, e.g. higher layer protocols or other services actingon behalf of end-user applications.The interface of the RFCOMM-protocol layer (the COM component) is logical grouped infunctional blocks. The following blocks are identified:• Start procedure
• Connection procedure
• Collective interface
• Data exchange interface
• Serial port emulation interface
RFCOMM is a simple transport protocol, with additional provisions for emulating RS-232 serialports. The protocol supports up to 60 simultaneous connections between two BT devices. Itsconnections are client-server based.
5.3.1 ContextThe COM component exports services to one or more applications. (In this context, the termapplication may mean other things than end-user application, e.g. higher layer protocols or otherservices acting on behalf of end-user applications.) Connection related services are uniquelyidentified with a ‘Handle’. It expects services from the following components (processes):
• L2CA: Offering a data transfer service to the BT-baseband.• VOS: Offering an OS-independent shell to the real OS.• TIM: Offering a timer service.• DBM: Offering a database interface for storage/retrieval of COM data that is shared with 2 or
more other components.
The COM has the following context:
Bluetooth PC Reference Stack by Ericsson
Page 54
E N D I A NA N S I - C
V O S
T I M
S T A N D A R D
D B M
L 2 C A
C O M
A P P L I C A T I O N P R O D U C TB T
M S G
Figure 5-13 COM context
The other environment components (dotted line boxes) represent libraries/types/constants theCOM component is using. None of them are processes like the previous mentioned components:
• BT: Bluetooth specific definitions.• MSG: Definitions and functionality (library) applicable to all components exchanging
messages according.• PRODUCT: Product specific definitions. The unique identification of COM (COM_CMP) is
defined here.• STANDARD: Basic types used in the COM implementation (uint8, boolean, NULL, etc.)• ENDIAN: Endian support functions.
5.3.2 Implementation restrictionsNumber of COM instances is restricted to 8.Number of server applications is restricted to 30.
Bluetooth PC Reference Stack by Ericsson
Page 55
5.3.3 Start procedure
5.3.3.1 OverviewThe start procedure, including the registration of a server (application) must be the first actionperformed on the COM component before actual interfacing can be handled between theapplication and the COM component. Furthermore information about data-sizes could beretrieved, intended for the initialisation of specific applications.
5.3.3.1.1 Function Interface
Name Parameters Function Description
COM_ReqStart uiSeqNr Start the COM component to be able to communicate to it.
COM_ReqRegister uiSeqNr,ucServerChannel
Register a server (application) on the COM component to beable to receive indications and events.
COM_ReqFillPdl uiSeqNr,ucServerChannel,uiServiceRecordID
Fill the DBM component with protocol specific parameters ofthe COM component.
COM_ReqDeRegister uiSeqNr,ucServerChannel
De-register a server (application) from the COM component.
COM_ReqDataInfo uiSeqNr Requesting header and tail sizes of data-buffer from alllower layers.
Table 5-30 Function Interface of COM’s start procedure
5.3.3.1.2 Message Interface
Name ID/Type Contents Result MessageDescription
COM_START_CNFCOM_TStartCnf
tHdr COM_POS_RESULT Reply messageconfirms theReqStart.
COM_START_CNF_NEGCOM_TStartCnfNeg
tHdr COM_NEG_RESULT Reply messagerejects the ReqStart.
COM_REGISTER_CNFCOM_TRegisterCnf
tHdr,ucServerChannel COM_POS_RESULT
Reply messageconfirms theReqRegister.
COM_REGISTER_CNF_NEGCOM_TRegisterCnfNeg tHdr COM_NEG_CHANNEL_OCCUPIED
COM_NEG_ALL_CHANNELS_OCCUPIEDReply messagerejects theReqRegister.
COM_FILL_PDL_CNFCOM_TFillPdlCnf tHdr COM_POS_RESULT
Reply messageconfirms theReqFillPdl.
COM_FILL_PDL_CNF_NEGCOM_TFillPdlCnfNeg tHdr COM_NEG_SERVICE_RECORD_ID
COM_NEG_RESULTReply messagerejects theReqFillPdl.
COM_DEREGISTER_CNFCOM_TDeRegisterCnf
tHdr COM_POS_RESULT Reply messageconfirms theReqDeRegister.
COM_DEREGISTER_CNF_NEGCOM_TDeRegisterCnfNeg
tHdr COM_NEG_RESULT Reply messagerejects theReqDeRegister.
Bluetooth PC Reference Stack by Ericsson
Page 56
COM_DATA_INFO_CNFCOM_TDataInfoCnf
tHdr,ucNrOfHdrBytes,ucNrOfTrailerBytes
COM_POS_RESULT Reply from COMcomponent onDataInfoReq.
Table 5-31 Message Interface of COM’s start procedure
5.3.3.1.3 Data elements
Name Type Value Description
tHdr MSG_TControlHdr - Common MSG message header.
ucNrOfHdrBytes uint8 >= 4 Defines the total data header length of a data-packet on top of COM.
ucNrOfTrailerBytes uint8 >= 1 Defines the total data tail length of a data-packet on top of COM.
ucServerChannel uint8
1 .. 30
COM_ReqRegister:0:automatic selection
The server-channel which is used by the server(application).
uiServiceRecordID uint16 0x0000 .. 0xFFFF The reference to a service-record.
uiSeqNr uint16 0x0000 .. 0xFFFF The sequence-number that must be replied inthe corresponding confirm-message.
Table 5-32 Data elements of COM’s start procedure
5.3.3.2 Communication procedures
5.3.3.2.1 Start COM componentTo be able to communicate to the COM component, the application has to start to the COM
component as visualised below.
COM_ReqStartCOM_START_CNF
APPLICATION COM
Figure 5-14 Start COM component.
COM_ReqStartTo be able to communicate to the COM component, the application has to start to the componentprior to all other communication to it. Invoking this function will cause COM and all thecomponents needed by COM to start.
COM_TStartCnf/COM_TStartCnfNegThis reply-message confirms the start request of the application. If positive, the application mayuse the COM component interface now. A negative reply may have resulted from a short ofresources in the lower layers.
5.3.3.2.2 Sign-up to COM component
Bluetooth PC Reference Stack by Ericsson
Page 57
To be able to accept connections, a server (application) has to sign up to the COM component asvisualised in below.
COM_ReqRegisterCOM_REGISTER_CNF
COM_ReqFillPdlCOM_FILL_PDL_CNF
SERVERAPPLICATION
COM
Start COM component
Figure 5-15 Sign-up to the COM component.
COM_ReqRegisterThe multiplex channel to be used by the server (application) can be indicated by ‘ServerChannel’or automatically assigned by the COM component. Automatically assigning a multiplex channel tothe server is achieved by giving the ‘ServerChannel’ a zero value. The registration contains alsoan implicit subscription to all indication- and event-messages related to the ‘ServerChannel’ andgenerated by the COM component.
COM_TRegisterCnf/COM_TRegisterCnfNegThis reply-message confirms, if positive, the subscription of the server to all indication- and event-messages related to the returned ‘ServerChannel’.
COM_ReqFillPdlWith use of this function, the ‘ServiceRecordID’, a reference to the service-record in the DBMcomponent, must be filled with protocol specific parameters of the COM component(‘ServerChannel’). A remote client (application) to connect to the server can use this information.
COM_TFillPdlCnf/COM_TFillPdlCnfNegThis reply-message confirms, if positive, the local registration of the protocol specific parametersof the COM component in the DBM component, referenced by ‘ServiceRecordID’.
5.3.3.2.3 De-registration of a serverRecalling a registered server (application) is visualised in below.
COM_ReqDeRegisterCOM_DEREGISTER_CNF
SERVERAPPLICATION
COM
Sign-up COM component
Figure 5-16 De-registration of a server(application).
COM_ReqDeRegisterThis request asks the COM component to recall the user its own registration of the indicated'ServerChannel' by removing the subscription of the server (application) from the administration.
Bluetooth PC Reference Stack by Ericsson
Page 58
COM_TDeRegisterCnf/COM_TDeRegisterCnfNegIf positive, this reply tells the server (application) that the indicated registration is recalled and the'ServerChannel', in the corresponding COM_ReqDeRegister, is available for re-use.
5.3.3.2.4 Information about data-sizeRequesting the data header- and tail-sizes is visualised below.
COM_ReqDataInfoCOM_DATA_INFO_CNF
APPLICATION COM
Start COM component
Figure 5-17 Information about data-size.
COM_ReqDataInfoThe data info request is used to request the total data header- and tail-sizes of the exchangeddata-packets. This function will be used mainly by transport protocols on top of the COMcomponent, to determine the necessary OS-buffer size it has to allocate for data-packets.
COM_TDataInfoCnfThis positive confirm-message is the reply on the data info request.
5.3.4 Connection procedure
5.3.4.1 OverviewThe connection procedure must be used to create a RFCOMM connection between the remoteRFCOMM its application and the application running on the COM component.
Bluetooth PC Reference Stack by Ericsson
Page 59
5.3.4.1.1 Function Interface
Name Parameters Function Description
COM_ReqConnect
uiSeqNr,uiServiceRecordIDtIeeeHandle,uiMaxFrameSize
Request a connection to a remotedevice.
COM_RspParameterNegotiation pptParameterNegotiationInd,iResult,uiMaxFrameSize
Reply on the parameter negotiationindication-message.
COM_RspConnect pptConnectInd,iResult,uiMaxFrameSize
Reply on the connect indication-message.
Table 5-33 Function Interface of COM’s connection procedure
5.3.4.1.2 Message Interface
Name ID/Type Contents Result MessageDescription
COM_CONNECT_CNFCOM_TConnectCnf
tHdr,uiHandle COM_POS_RESULT
Reply messageconfirms theReqConnect.
COM_CONNECT_CNF_NEGCOM_TConnectCnfNeg
tHdr,uiMaxFrameSize
COM_NEG_NO_INSTANCECOM_NEG_CONNECTINGCOM_NEG_CHANNEL_OCCUPIEDCOM_NEG_SERVICE_RECORD_IDCOM_NEG_SYSTEM_PARAMETERSCOM_NEG_LOSS_OF_SIGNALCOM_NEG_NSC_RESPONSECOM_NEG_DM_RESPONSECOM_NEG_RESULT_REMOTE
Reply messagerejects theReqConnect.
COM_PARAMETER_NEGOTIATION_INDCOM_TParameterNegotiationInd
tHdr,uiHandle,uiMaxFrameSize
- Indication for anew parameternegotiationsequence.
COM_CONNECT_INDCOM_TConnectInd
tHdr,uiHandle,uiMaxFrameSize,tIeeeHandle,ucServerChannel
- Indication tellsthe server(application) aclient wants toconnect.
Table 5-34 Message Interface of COM’s connection procedure
5.3.4.1.3 Data elements
Name Size Value Description
tHdr MSG_TControlHdr - Common MSG message header.
tIeeeHandle BT_THandle 0x0000 .. 0xFFFF Connection handle related to IEEE-address of the remote device.
uiHandle uint16 0x0001 .. 0x07FF Unique connection handle to the COMcomponent.
uiMaxFrameSize uint16 23 .. 32767 Defines the maximum number of octetsthat may be contained in a single datafield (Table 5-45).
Bluetooth PC Reference Stack by Ericsson
Page 60
uiServiceRecordID uint16 0x0000 .. 0xFFFFThe reference to a service-record that isfilled with SDP information about therequested connection.
uiSeqNr uint16 0x0000 .. 0xFFFFThe sequence-number that must bereplied in the corresponding confirmmessage.
ucServerChannel uint8 1 .. 30 The server-channel which is used by theserver (application).
iResult int16 The reply result on the correspondingindication-message.
pptConnectInd MSG_TMsg ** Replying the same buffer containing theoriginal connect indication.
pptParameterNegotiationInd MSG_TMsg ** Replying the same buffer containing theoriginal parameter negotiation indication.
Table 5-33 Data elements of COM’s connection procedure
5.3.4.2 Communication procedures
Setting-up a connection is visualised below.
optional parameter negotiationCOM_ReqConnect COM_PARAMETER_NEGOTIATION_IND
COM_RspParameterNegotiation
COM_CONNECT_INDCOM_RspConnect
COM_CONNECT_CNF
CLIENTAPPLICATION
COM COM SERVERAPPLICATION
Start COM component
Sign-up COM component
Figure 5-18 Setting up connection.
COM_ReqConnectThis function tells the COM Component that the client wants to communicate to the indicatedremote server (application), referenced with the ’ServiceRecordID’ and ‘IeeeHandle’. The‘ServiceRecordID’ is a reference to the service-record, in the DBM component, that is filled withthe protocol specific parameters of the RFCOMM entity of the remote device. The specified‘MaxFrameSize’ is negotiated with the remote server. The connection request contains also animplicit subscription to all indication- and event-messages, related to the requested connectionand generated by the COM component.
COM_TConnectCnf/COM_TConnectCnfNegThis confirm-message is the reply on the COM_ReqConnect.If positive, it contains the unique connection 'Handle' of the requesting client (application) and itsCOM component to be used when, for instance, exchanging data packets.Return values of ‘Result’ can be:• COM_POS_RESULT: positive result.• COM_NEG_NO_INSTANCE: no local COM instance is available.
Bluetooth PC Reference Stack by Ericsson
Page 61
• COM_NEG_CONNECTING: the requested connection is already requested by anotherapplication or a pending connection set-up of the control-channel of the COM instance. Priorto setting-up any channel one control-channel has to be connected on RFCOMM level.
• COM_NEG_CHANNEL_OCCUPIED: Another client already allocated the requested channel.• COM_NEG_SERVICE_RECORD_ID: negative response on the request to read the protocol
specific parameters using the given ‘ServiceRecordID’.• COM_NEG_SYSTEM_PARAMETERS: the requested maximum number of octets that may
be contained in a single data field is too large. A new revised value of the ‘MaxFrameSize’ isreturned.
• COM_NEG_LOSS_OF_SIGNAL: the requested device, referenced by IeeeHandle, is notresponding.
• COM_NEG_NSC_RESPONSE: the remote device does not support theParameterNegotiation command. A new connect request with the default ‘MaxFrameSize’value could be send (the request with the default ‘MaxFrameSize’, Table 5-45, will not invokea ParameterNegotiation command).
• COM_NEG_DM_RESPONSE: the remote device rejects the requested connection.• COM_NEG_RESULT_REMOTE: The result is determined in the remote device.
COM_TParameterNegotiationIndThe parameter negotiation indication-message is issued, by the remote RFCOMM entity, torequest the change of parameters on a specific connection, identified by ‘Handle’. This indicationis optional, but if received, it is always previous to the ‘COM_TConnectInd’ indication.
COM_RspParameterNegotiationThis response function is the reply on the parameter negotiation indication-message. Returnvalues of ‘Result’ can be:• COM_POS_RESULT: the requested system-parameters are accepted.• COM_NEG_SYSTEM_PARAMETERS: the requested maximum number of octets that may
be contained in a single data field is too large. A new revised value of the ‘MaxFrameSize’must be returned.
• COM_NEG_RESULT: negative reason unknown: defined in upper-layer.
COM_TConnectIndThis message tells the server (application) that a client (application) wants to communicate to theindicated server, identified with 'Handle'.
COM_RspConnectThe server (application) uses the response function to either accept or reject the proposedconnection, referenced by ‘Handle’, with its system parameters. Return values of ‘Result’ can be:• COM_POS_RESULT: the requested channel (‘Handle’) and system-parameters accepted.• COM_NEG_SYSTEM_PARAMETERS: the requested maximum number of octets that may
be contained in a single data field is too large. A new revised value of the ‘MaxFrameSize’must be returned.
• COM_NEG_RESULT: negative reason unknown: defined in upper-layer.
5.3.5 Collective interface
5.3.5.1 OverviewSupport services on RFCOMM protocol level, used by either a server or client application, aredescribed in this section.
5.3.5.1.1 Function Interface
Name Parameters Function Description
COM_ReqDisconnect uiSeqNr,uiHandle Request disconnection of the remote device.
Bluetooth PC Reference Stack by Ericsson
Page 62
COM_ReqTestuiSeqNr,tIeeeHandle,uiLength,pucTestDataStart
Test the connection with the other device.
COM_CmdAggregateFlow tIeeeHandle,tFlowState
Request permission for a data flow change of the whole COMinstance.
COM_CmdFlow uiHandle,tFlowState Request permission for a data flow change of one COM channel.
Table 5-34 Function Interface of COM’s collective interface
5.3.5.1.2 Message Interface
Name ID/Type Contents Result Message Description
COM_DISCONNECT_CNFCOM_TDisconnectCnf tHdr COM_POS_RESULT Reply message confirms the
ReqDisconnect.
COM_DISCONNECT_CNF_NEGCOM_TDisconnectCnfNeg tHdr COM_NEG_NO_INSTANCE
COM_NEG_CONNECTINGReply message rejects theReqDisconnect.
COM_DISCONNECT_EVTCOM_TDisconnectEvt
tHdr,uiHandle
COM_DISC_COMMANDCOM_LOSS_OF_SIGNAL
This message tells the application theindicated connection is disconnected.
COM_TEST_CNFCOM_TTestCnf
tHdr,uiLength,ucTestData
COM_POS_RESULT Reply message confirms theReqTest.
COM_TEST_CNF_NEGCOM_TTestCnfNeg
tHdr COM_NEG_NSC_RESPONSE Reply message rejects the ReqTest.
COM_FLOW_EVTCOM_TFlowEvt
tHdr,uiHandle,tFlowState
-The message tells the application theindicated connection has had flowchange.
Table 5-35 Message Interface of COM’s collective interface
5.3.5.1.3 Data elements
Name Size Value Description
tHdr MSG_TControlHdr - Common MSG message header.
tFlowState COM_TFlowState see Table 5-45
The state of the aggregate flow of the local COMinstance.The state of the flow of a local RFCOMM channelcorresponding with ‘Handle’.The state of the flow of the remote RFCOMMchannel identified with ‘Handle’.
tIeeeHandle BT_THandle 0x0000 .. 0xFFFF Connection handle related to IEEE-address of theremote device.
uiHandle uint16 0x0001 .. 0x07FF Unique connection handle to the COM component.
uiLength uint16 23 .. 32767 Indicates the test-data length in bytes.
uiSeqNr uint16 0x0000 .. 0xFFFF The sequence-number that must be replied in thecorresponding confirm-message.
ucTestData uint8 - The first byte of the returned test data.
pucTestDataStart uint8 * - Pointer to data to be transferred as a test pattern.
Table 5-36 Data elements of COM’s collective interface
Bluetooth PC Reference Stack by Ericsson
Page 63
5.3.5.2 Communication proceduresDisconnecting a RFCOMM connection can be initiated from either the client- or the server-side.
COM_ReqDisconnectCOM_DISCONNECT_EVT
COM_DISCONNECT_CNF
APPLICATION COM COM APPLICATION
Set-up a connection
Figure 5-19 Disconnecting a connection.
COM_ReqDisconnectThe request function is used by the application in the transmitting device to initiate close down ofthe selected channel, referenced by 'Handle', in COM component.
COM_TDisconnectCnf/COM_TDisconnectCnfNegThis confirm is the reply on the COM_ReqDisconnect.
COM_TDisconnectEvtThis message tells the application that the indicated connection 'Handle' is disconnected. Afterthe disconnection, the 'Handle' is available for re-use, but in case a server is disconnected, theregistered server-channel is still allocated to this server and must be de-registered to be availablefor re-use. Return values of ‘Result’ can be:• COM_DISC_COMMAND: the indicated connection is disconnected as result of a DISC
command by the remote device.• COM_LOSS_OF_SIGNAL: the indicated connection is disconnected as result of a device
disconnection.
5.3.5.2.1 RFCOMM’s flow controlChanges of the flow, on a channel or complete instance, can be send and initiated from either theclient- or the server-side.
COM_FLOW_EVT COM_CmdAggregateFlowCOM_FLOW_EVT
COM_CmdFlow COM_FLOW_EVT
APPLICATION COM COM APPLICATION
Set-up a connection
Figure 5-20 RFCOMM’s flow control.
COM_CmdAggregateFlowThis command function is used to set the aggregate flow. This is the flow-control of a total COMinstance effecting all the channels of that instance. When the COM instance is not able to receiveinformation it uses COM_CmdAggregateFlow with ‘State’ = COM_FLOW_OFF. The oppositeentity is not allowed to transmit data frames. When the COM instance is able to receive newinformation it uses COM_CmdAggregateFlow with ‘State’ = COM_FLOW_ON.The initial state of the COM instance is with aggregate flow enabled.
COM_CmdFlowThe command function with ‘State’ = COM_FLOW_OFF disables the issuing of data-indications(COM_TDataInd) by the local COM instance. The request function with ‘State’ =
Bluetooth PC Reference Stack by Ericsson
Page 64
COM_FLOW_ON enables the issuing of data-indications (COM_TDataInd) by the local COMinstance.These commands may or may not result in the remote RFCOMM entity issuing a‘COM_TFlowEvt’ to the remote application, depending on the states of the buffers in theRFCOMM entities.The initial state of the COM instance is with flow enabled.
COM_TFlowEvtThe message with ‘State’ = COM_FLOW_OFF disables the processing of data-requests(COM_TDataSend) by the application. Sending data-requests when the flow is off, will result in anegative confirm on the request. The indication-message with ‘State’ = COM_FLOW_ON enablesthe processing of data-requests (COM_TDataSend) by the application.These indications may or may not have resulted from the receipt of a flow command function(COM_CmdFlow) from the remote application. They may have been issued by the local COMinstance as a result of its buffer state.
5.3.5.2.2 Test RFCOMM connectionTesting a COM connection can be initiated from either the client- or the server-side
COM_ReqTest
COM_TEST_CNF
APPLICATION COM COM
Start COM component
Figure 5-21 Test RFCOMM connection.
COM_ReqTestThe function is used to request a test of the RFCOMM communication link. The data is sent to theremote entity, which should bounce it back. It is not necessary to set-up a channel connectionfirst.
COM_TTestCnf/COM_TTestCnfNegThis is the reply on the COM_ReqTest, if positive, it should hold the same data as send with therequest.
5.3.6 Data interface
5.3.6.1 OverviewTransferring data-packets over a RFCOMM connection must be handled with the data interface ofthe COM component, as described in this section.
5.3.6.1.1 Function Interface
Name Parameters Function Description
*COM_DataAlloc uiLength Allocate a data-buffer for transmitting data.
COM_DataFree pucData Freeing an allocated data-buffer, which is not send.
Bluetooth PC Reference Stack by Ericsson
Page 65
COM_DataSenducSeqNr,pucData,uiHandle,uiLength
Sending a data-buffer
COM_RspDataucSeqNr,iResult,uiHandle
Reply on a received data indication message.
*COM_DataExtractptDataInd,puiLength,puiHandle
Extract header information from a received data indication message.
Table 5-37 Function Interface of COM’s data interface
5.3.6.1.2 Message Interface
Name ID/Type Contents Result Message Description
COM_DATA_CNFCOM_TDataCnf
tHdr,uiHandle COM_POS_RESULT Positive reply from COM component on
DataSend.
COM_DATA_CNF_NEGCOM_TDataCnfNeg
tHdr,uiHandle
COM_NEG_FLOW_FAILURECOM_NEG_RESULT
Negative reply from COM component onDataSend.
COM_DATA_INDCOM_TDataInd
tHdr,ucData - Indication of received data message.
Table 5-38 Message Interface of COM’s data interface
5.3.6.1.3 Data elements
Name Size Value Description
tHdr MSG_TControlHdr - Common MSG message header.
COM_DataAlloc uint8 * - Points at the start location in the data-buffer wherethe requester can put its data.
COM_DataExtract uint8 * - Points at the start location in the data-buffer wherethe user-data begins.
uiHandle uint16 0x0001 .. 0x07FF Unique connection handle to the COM component.
uiLength uint16 1 .. 32767 Indicates the number of data bytes in the data-buffer.
ucSeqNr uint8 0x00 .. 0xFF The sequence-number to be replied in thecorresponding message.
pucData uint8 * - Points at the start location of the data-buffer wherethe user-data begins.
iResult int16 - The reply result on the DataInd.
ptDataInd MSG_TDataMsg * - Pointer to the received data message.
puiHandle uint16 * 0x0001 .. 0x07FF Indicates the unique connection handle to the COMcomponent.
puiLength uint16 * 1 .. 32767 Indicates the number of bytes in the data-buffer.
Table 5-39 Data elements of COM’s data interface
5.3.6.2 Communication procedures
5.3.6.2.1 Data transfer
Bluetooth PC Reference Stack by Ericsson
Page 66
Transferring data over a RFCOMM connection can be initiated from either the client- or theserver-side.
COM_DataAlloc
COM_DataSendCOM_DATA_CNF COM_DATA_IND
COM_RspDataCOM_DataExtract
COM_DataAlloc
COM_DataSendCOM_DATA_IND COM_DATA_CNFCOM_RspDataCOM_DataExtract
CLIENTAPPLICATION
COM COM SERVERAPPLICATION
Set-up a connection
Sign-up COM
Figure 5-22 Transferring data.
COM_DataAllocAllocate an OS-buffer containing a MSG_TDataMsg structure. The ‘Length’ defines the number ofbytes the requester wants to put into this buffer, where this routine adds enough header andtrailer space for a copyless transfer of the data buffer through the BT-stack.Note that the returned byte pointer points to the first user data byte and not to the allocated OS-buffer
COM_DataFreeSuppose the application has allocated a data buffer for transmission by using the COM_DataAllocfunction. Now the application decides fnot to send this packet. In that case the corresponding OS-buffer needs to be released. The application however is not able to determine this buffer pointer,so therefore this routine must be used. The ‘Data’ pointer points at the start of the application datain the OS-buffer as returned by COM_DataAlloc.ATTENTION: This function may only be used for this purpose. So not for releasing a receivedDataInd buffer !!
COM_DataSendSend the filled data-message to the COM component, the ‘Handle’ defines the connection handleto the COM component. The ‘Length’ defines the number of bytes the requester has put into thisbuffer; this ‘Length’ must be less then the original requested ‘Length’ (see COM_DataAlloc),where ‘Length’ = 0 is interpreted as being equal to the original requested ‘Length’. When the‘Length’ is not equal to 0, the new ‘Length’ will be placed in the message; but only when the new‘Length’ is shorter then the requested ‘Length’, otherwise a negative reply will be returned. Thismeans it’s allowed to send a smaller data-packet then originally requested via theCOM_DataAlloc function. Within the COM component there is only 1 outstanding data-packet perconnection handle, which means the requester has to wait for the confirm-message beforesending the next data-packet.
COM_TDataCnf/COM_TDataCnfNegThis message is the reply on the COM_DataSend.If positive, the COM component has processed the earlier send data-packet, belonging to theindicated 'Handle'.
COM_TDataInd
Bluetooth PC Reference Stack by Ericsson
Page 67
The indication-message delivers received data. The application should always respond on aDataInd as fast as possible.
COM_RspDataThe receiving device of a data indication-message processed the data and replies by returningthe response-message to its COM component, with the use of the response function and thecorresponding ‘Handle’.Return values of ‘Result’ can be:• COM_POS_RESULT: the requested data is accepted.• COM_NEG_RESULT: negative reason unknown: defined in upper-layer.
COM_DataExtractExtract the header information and data from the just received COM_TDataInd. The header items‘Handle’ and ‘Length’ are returned, together with the pointer to the start of the ‘Data’.With this action also the header of the COM-message is stripped from the data-packet! So thisroutine must only be used once for each received COM_TDataInd !!
5.3.7 Serial port emulation interface
5.3.7.1 OverviewThe provisions to emulate a serial port, using a port emulation entity, are described in this section.When no port emulation is used, all described default values are chosen, for instance no V24signals flow-control, so this interface section is not to be used.
5.3.7.1.1 Function Interface
Name Parameters Function Description
COM_ReqRetrieveRemotePort uiSeqNr,uiHandle Retrieve remote port parameter settings.
COM_ReqRemotePortNegotiation
uiSeqNr,uiHandle,tPortSpeed,tDataBits,tStopBits,tParity,tParityType,ucXonCharacter,ucXoffCharacter
Negotiate remote port parametersettings.
COM_RspRemotePortNegotiation pptRemotePortNegotiationInd,tPortMask
Reply on the remote port negotiationindication-message.
COM_ReqRetrievePortFlowDirection uiSeqNr,uiHandle
Retrieve remote port flow-parametersettings.
COM_ReqPortFlowDirectionNegotiationuiSeqNr,uiHandle,tFlowDirection
Negotiate the remote port flow-parametersettings.
COM_RspPortFlowDirectionNegotiation pptPortFlowDirectionNegotiationInd,tFlowMask
Reply on the remote port flow directionnegotiation indication-message.
COM_CmdModemStatusuiHandle,tModemSignals,tModemBreak
Send new modem status information.
COM_CmdLineStatus uiHandle,tLineStatus Send new line status information.
Table 5-40 Function Interface of serial port emulation interface
5.3.7.1.2 Message Interface
Bluetooth PC Reference Stack by Ericsson
Page 68
Name ID/Type Contents Result MessageDescription
COM_RETRIEVE_REMOTE_PORT_CNFCOM_TRetrieveRemotePortCnf
tHdr,uiHandle,tPortSpeed,tDataBits,tStopBits,tParity,tParityType,ucXonCharacter,ucXoffCharacter
COM_POS_RESULTReply onReqRetrieveRemotePort.
COM_RETRIEVE_REMOTE_PORT_CNF_NEGCOM_TRetrieveRemotePortCnfNeg
tHdr,uiHandle
COM_NEG_NO_INSTANCECOM_NEG_LAST_COMMAND_ PENDINGCOM_NEG_NSC_RESPONSECOM_LOSS_OF_SIGNAL
Reply onReqRetrieveRemotePort.
COM_REMOTE_PORT_NEGOTIATION_CNFCOM_TRemotePortNegotiationCnf
tHdr,uiHandle COM_POS_RESULT
Reply onReqRemotePortNegotiation.
COM_REMOTE_PORT_NEGOTIATION_CNF_NEGCOM_TRemotePortNegotiationCnfNeg
tHdr,uiHandle,tPortMask
COM_NEG_NO_INSTANCECOM_NEG_LAST_COMMAND_ PENDINGCOM_NEG_NSC_RESPONSECOM_NEG_PORT_PARAMETERSCOM_LOSS_OF_SIGNAL
Reply onReqRemotePortNegotiation.
COM_REMOTE_PORT_NEGOTIATION_INDCOM_TRemotePortNegotiationInd
tHdr,uiHandle,tPortSpeed,tDataBits,tStopBits,tParity,tParityType,ucXonCharacter,ucXoffCharacter
-
Indication fora new remoteportparameternegotiationsequence.
COM_RETRIEVE_PORT_FLOW_DIRECTION_CNFCOM_TRetrievePortFlowDirectionCnf
tHdr,uiHandle,tFlowDirection
COM_POS_RESULTReply onReqRetrievePortFlowDirection.
COM_RETRIEVE_PORT_FLOW_DIRECTION_CNF_NEGCOM_TRetrievePortFlowDirectionCnfNeg
tHdr,uiHandle
COM_NEG_NO_INSTANCECOM_NEG_LAST_COMMAND_ PENDINGCOM_NEG_NSC_RESPONSECOM_LOSS_OF_SIGNAL
Reply onReqRetrievePortFlowDirection.
COM_PORT_FLOW_DIRECTION_NEGOTIATION_CNFCOM_TPortFlowDirectionNegotiationCnf
tHdr,uiHandle COM_POS_RESULT
Reply onReqPortFlowDirectionNegotiation.
COM_PORT_FLOW_DIRECTION_NEGOTIATION_CNF_NEGCOM_TPortFlowDirectionNegotiationCnfNeg
tHdr,uiHandle,tFlowMask
COM_NEG_NO_INSTANCECOM_NEG_LAST_COMMAND_ PENDINGCOM_NEG_NSC_RESPONSECOM_NEG_FLOW_PARAMETERSCOM_LOSS_OF_SIGNAL
Reply onReqPortFlowDirectionNegotiation.
COM_PORT_FLOW_DIRECTION_NEGOTIATION_INDCOM_TPortFlowDirectionNegotiationInd
tHdr,uiHandle,tFlowDirection
-
Indication fora new remoteport flow-parameternegotiationsequence.
Bluetooth PC Reference Stack by Ericsson
Page 69
COM_MODEM_STATUS_EVTCOM_TModemStatusEvt
tHdr,uiHandle,tModemSignals,tModemBreak
-
This messagetells theapplication themodem statushas changed.
COM_LINE_STATUS_EVTCOM_TLineStatusEvt
tHdr,uiHandle,tLineStatus
-
This messagetells theapplication theline status haschanged.
Table 5-41 Message Interface of serial port emulation interface
5.3.7.1.3 Data elements
Name Size Value Description
tHdr MSG_TControlHdr - Common MSG messageheader.
uiSeqNr uint16 0x0000 .. 0xFFFF
The sequence-number thatmust be replied in thecorresponding confirmmessage.
uiHandle uint16 0x0001 .. 0x07FF Unique connection handle tothe COM component.
tPortSpeed COM_TPortSpeed see Table 5-45 Indicates the baudrate.
tDataBits COM_TDataBits see Table 5-45 Indicates the number of databits.
tStopBits COM_TStopBits see Table 5-45 Indicates the number of stopbits.
tParity COM_TParity see Table 5-45 Indicates the parity.
tParityType COM_TParityType see Table 5-45 Indicates the parity type.
ucXonCharacter uint8 see Table 5-45 Indicates the XON character.
ucXoffCharacter uint8 see Table 5-45 Indicates the XOFF character.
tPortMask COM_TPortMask see Table 5-45 Parameter mask of negotiatedport parameters.
tFlowDirection COM_TFlowDirection see Table 5-45 Settings of retrieved port flowparameters.
tFlowMask COM_TFlowMask see Table 5-45 Parameter mask of negotiatedflow parameters.
tModemSignals COM_TModemSignals see Table 5-45Transmitted control-signals toa data stream.Received control signals to adata stream.
tModemBreak COM_TModemBreak see Table 5-45 Break signals in a data stream.
tLineStatus COM_TLineStatus see Table 5-45 Remote port line status.
pptRemotePortNegotiationInd MSG_TMsg ** -
pptPortFlowDirectionNegotiationInd MSG_TMsg ** -
Table 5-42 Data elements of serial port emulation interface
Name Contents Value Description
Bluetooth PC Reference Stack by Ericsson
Page 70
COM_TPortSpeed
COM_ BAUDRATE_2400,COM_ BAUDRATE_4800,COM_ BAUDRATE_7200,COM_ BAUDRATE_9600,COM_ BAUDRATE_19200,COM_ BAUDRATE_38400,COM_ BAUDRATE_57600,COM_ BAUDRATE_115200,COM_BAUDRATE_230400
0,1,2,3,4,5,6,7,8
Baudrate in port settings.Default: COM_ BAUDRATE_9600
COM_TDataBitsCOM_5_DATA_BITS,COM_7_DATA_BITS,COM_6_DATA_BITS,COM_8_DATA_BITS
0,2,1,3
Number of data bits in port settings.Default: COM_8_DATA_BITS
COM_TStopBits COM_1_STOP_BITS,COM_1_5_STOP_BITS
0,1
Number of stop bits in port settings.Default: COM_1_STOP_BITS
COM_TParity COM_NO_PARITY,COM_PARITY
0,1
Parity in port settings.Default: COM_NO_PARITY
COM_TParityTypeCOM_ODD_PARITY,COM_MARK_PARITY,COM_EVEN_PARITY,COM_SPACE_PARITY
0,1,2,3
Parity type in port settings.Default: -
COM_TFlowState COM_FLOW_ON,COM_FLOW_OFF
0,1
Flow state of COM channel or instance.Default: COM_FLOW_ON
COM_DC1 constant uint8 0x11 Default XON character.
COM_DC3 constant uint8 0x13 Default XOFF character.
COM_DEFAULT_MFS constant uint16 127 Default ‘maximum frame size’.
COM_MIN_MFS constant uint16 23 Minimal ‘maximum frame size’.
COM_MAX_MFS constant uint16 32767 Maximal ‘maximum frame size’.
COM_TPortMask
bPortSpeed,
bDataBits,
bStopBits,
bParity,
bParityType,
bXonCharacter,
bXoffCharacter
boolean Response mask of port settings. TRUE isaccepted and/or used.
COM_TFlowDirection
bXonXoffInput,
bXonXoffOutput,
bCtsRtsInput,
bCtsRtsOutput,
bDtrDsrInput,
bDtrDsrOutput
boolean State of the different port flow settings.TRUE is active and/or used.
COM_TFlowMask
bXonXoffInput,
bXonXoffOutput,
bCtsRtsInput,
bCtsRtsOutput,
bDtrDsrInput,
bDtrDsrOutput
boolean Response mask of port flow settings.TRUE is accepted and/or used.
Bluetooth PC Reference Stack by Ericsson
Page 71
COM_TModemSignals
bDsrDtr,
bCtsRts,
bRi,
bDcd
boolean State of the different modem signals.TRUE is active.
COM_TModemBreakbBreakEncode,
ucBreakLength
boolean,
uint8: 0 .. 16State of the break signal and its length.
COM_TLineStatus
bOverrunError,
bParityError,
bFramingError
boolean State of the port line. TRUE is errordetected.
Table 5-45 Defined Constants/Types within the COM component.
5.3.7.2 Communication procedures
5.3.7.2.1 Remote port-settingsRetrieval of remote port settings and negotiation of those settings can be initiated from either theclient- or the server-side.
COM_ReqRetrieveRemotePort
COM_RETRIEVE_REMOTE_PORT_CNF
COM_ReqRemotePortNegotiationCOM_REMOTE_PORT_NEGOTIATION_INDCOM_RspRemotePortNegotiation
COM_REMOTE_PORT_NEGOTIATION_CNF
APPLICATION COM COM APPLICATION
Set-up COM connection
Figure 5-23 Remote port settings.
COM_ReqRetrieveRemotePortThe request function is used to retrieve the current port parameter settings of a channel, indicatedby ‘Handle’, of the remote RFCOMM entity.
COM_TRetrieveRemotePortCnf/COM_TRetrieveRemotePortCnfNegThe confirm-message informs the requester about the current port parameter settings of thechannel of the remote RFCOMM entity, identified by ‘Handle’.
COM_ReqRemotePortNegotiationThe request function is used to request the remote RFCOMM entity to change specific port-parameter settings. All devices must assure that the communication port settings are correctlyset, prior sending data. There are default values assigned on all parameters, if no negotiation isperformed, the default value is chosen.
COM_TRemotePortNegotiationCnf/COM_TRemotePortNegotiationCnfNegIf the sender of the port parameter negotiation request considers the response to be acceptable,
Bluetooth PC Reference Stack by Ericsson
Page 72
that is, the parameter(s) are accepted (TRUE), the sender will start to use the ‘Handle’ accordingto the requested port parameter setting. All parameters, which are negotiated and accepted by theremote device, will be used immediately.If the response (or a part of it) is not acceptable the sender may initiate another remote portnegotiation request with revised parameters until a final agreement is reached or pass the failureinformation to a higher layer.
COM_TRemotePortNegotiationIndThis message tells the application that the port settings of the indicated connection 'Handle' is tobe changed. Note: the indication can be received before a connection is set-up. This is a validnegotiation request and must be responded to as normal, however the used ‘Handle’ has nomeaning.
COM_RspRemotePortNegotiationWhen the remote port negotiation indication is received, the responding station replies accordingto the following rules with this function.The receiver may accept the new port settings proposed by the sender, and reply with a responsewith the parameter mask set to TRUE for all the parameters accepted. If the receiver does notsupport any of the proposed values, it replies with the parameter mask set to FALSE for theparameters not supported. For those parameters with the parameter mask set to TRUE, the newvalue is accepted and used immediately.
5.3.7.2.2 Port-flow direction settings
Retrieval of port-flow direction settings and negotiation of those settings can be initiated fromeither the client- or the server-side.
COM_ReqRetrievePortFlowDirection
COM_RETRIEVE_PORT_FLOW_DIRECTION_CNF
COM_ReqPortFlowDirectionNegotiationCOM_PORT_FLOW_DIRECTION_NEGOTIATION_INDCOM_RspPortFlowDirectionNegotiation
COM_PORT_FLOW_DIRECTION_NEGOTIATION_CN
APPLICATION COM COM APPLICATION
Set-up COM connection
Figure 5-24 Port-flow direction settings.
COM_ReqRetrievePortFlowDirectionThe request function is used to retrieve the current flow direction settings of a channel, indicatedby ‘Handle’, of the remote RFCOMM entity.
COM_TRetrievePortFlowDirectionCnf/ COM_TRetrievePortFlowDirectionCnfNegThe confirm-message informs the requester about the current port flow settings of the channel ofthe remote RFCOMM entity, identified by ‘Handle’.
COM_ReqPortFlowDirectionNegotiationThe request function is used to request the remote RFCOMM entity to change specific channelport flow parameters.
Bluetooth PC Reference Stack by Ericsson
Page 73
All devices must assure that the communication flow settings are correctly set, prior sending data.There are default values assigned on all parameters, if no negotiation is performed, the defaultvalue is chosen.
COM_TPortFlowDirectionNegotiationCnf/COM_TPortFlowDirectionNegotiationCnfNegIf the sender of COM_ReqPortFlowDirectionNegotiation considers the response to be acceptable,that is, the parameter(s) are accepted (TRUE), the sender will start to use the ‘uiHandle’according to the requested port parameter setting. If the response is not acceptable the sendermay initiate another remote port negotiation request with revised parameters until a finalagreement is reached or pass the failure information to a higher layer.
COM_TPortFlowDirectionNegotiationIndThis message tells the application that the port flow settings of the indicated connection 'Handle'is to be changed. Note: the indication can be received before a connection is set-up. This is avalid negotiation request and must be responded to as normal, however the used ‘Handle’ has nomeaning.
COM_RspPortFlowDirectionNegotiationWhen the port flow negotiation indication is received, the responding station replies according tothe following rules with COM_RspPortFlowDirectionNegotiation.The receiver may accept the new port flow settings proposed by the sender, and reply with aresponse with the parameter mask set to TRUE for all the parameters accepted. If the receiverdoes not support any of the proposed values, it replies with the parameter mask set to FALSE forthe parameters not supported. For those parameters with the parameter mask set to TRUE, thenew value is accepted and used.
5.3.7.2.3 Send modem-status signalsChanges of the modem-status can be send and initiated from either the client- or the server-side.
COM_CmdModemStatus COM_MODEM_STATUS_EVT
APPLICATION COM COM APPLICATION
Set-up COM connection
Figure 5-25 Send modem-status signals.
COM_CmdModemStatusThe modem status command function is used to convey control information to the remote port.Every time the signals change, the server or client sends this command to indicate the currentstatus of each signal.The ‘ModemBreak’ carries information about a break signal detected in the data stream for the‘Handle’.
COM_TModemStatusEvtThis message tells the application that the modem signal(s) have changed.
5.3.7.2.4 Send line-status signalsChanges of the line-status can be send and initiated from either the client- or the server-side.
Bluetooth PC Reference Stack by Ericsson
Page 74
COM_CmdLineStatus COM_LINE_STATUS_EVT
APPLICATION COM COM APPLICATION
Set-up COM connection
Figure 5-26 Send line-status signals.
COM_CmdLineStatusThis command function is used for indicating the remote device the port line status. During aconnection, a device must send the ‘COM_CmdLineStatus’ whenever the port line status ischanged.
COM_TLineStatusEvtThis event-message tells the application that the port line status has changed.
5.4 Service Discovery Protocol Interface (SDP)
HC I Drive r
RFC O M M
L2C AP
SDP
OS A
daptation
Se ria l Line In te rfa c e
A p p lic a t io n
ApplicationProgrammersInterface
VOSInterface
SILInterface
SC M
Discovery of services is a crucial part of the Bluetooth framework. Service discovery isfundamental for all the usage models. The service discovery protocol (SDP) provides a means forapplications to discover which services are available and to determine the characteristics of thoseavailable services using an existing L2CAP connection. After that, an appropriate separateconnection between two or more Bluetooth devices can be established using information obtainedvia SDP.
The service discovery application does not make use of SDP as a means of accessing a service,but rather as a means of informing the user of a Local Device (LocDev) the services that areavailable to his/her device by (and possibly via) Remote Device(s) (RemDev).
The DataBase Manager (DBM) is a mechanism to provide access to data from services. TheDBM contains an interface that lets the user maintain its data. First, Service Discovery Data(service records) should be added by the application. Second, when Bluetooth connectionsalready exist and an actual “ReqServiceData” (by SDC) has been performed, the application canadd this retrieved ‘peerdata’ to the DBM too, so the DBM can behave also like a stack forpeerdata, the StackDB.
Bluetooth PC Reference Stack by Ericsson
Page 75
Other protocol layers like RFCOMM and L2CAP can add their own parameters to theServiceDiscoveryDB and read the retrieved protocol parameters from the StackDB (from thecorresponding protocols RFCOMM and L2CAP) to setup an actual connection.
The most important user of DBM however is SDS (Service Discovery Server) to obtain or querythe DBM for data to send back to the SDC who asked for it, and the application that maintains theDBM.
The application interface (API) acts as a software building block, connecting the implemented BT-stack to an unknown application environment. The designated interfacing to a service database,in which certain service record values are administered, is described in this chapter.
For example, the following databases can be administered through DBM:
• Service Discovery Database – Database of the SDP server itself• Stack Database - retrieved from the remote SDP server database. Eg. one particular remote
service record value that should be cached by the client and read by the stack layers will bethe ProtocolDescriptorList attribute.
The Service Discovery Protocol Interface contains the following main chapters :• SDC (5.4.1)
contains chapters :- Connect Procedure (5.4.1.1)- Service Discovery Procedure 1 (5.4.1.2)- Service Discovery Procedure 2 Combination (5.4.1.3)- Disconnect Procedure (5.4.1.4)- Support Procedures (5.4.1.5)
• DBM (5.4.2)contains chapters :- Start Procedure (5.4.2.1)– Write Actions (5.4.2.2)– Read Actions (5.4.2.3)– Miscellenaneous Actions (5.4.2.4)
• SDS (5.4.3)contains chapter :- Start Procedure (5.4.3.1)
5.4.1 SDC
Discovery of services is a crucial part of the Bluetooth framework. Service discovery isfundamental for all the usage models. The service discovery protocol (SDP1) provides a meansfor applications to discover which services are available and to determine the characteristics ofthose available services using an existing L2CAP connection. After that, an appropriate separateconnection between two or more Bluetooth devices can be established using information obtainedvia SDP.
The service discovery application (SDAP) does not make use of SDP as a means of accessing aservice, but rather as a means of informing the user of a Local Device (LocDev) the services thatare available to his/her device by (and possibly via) Remote Device(s) (RemDev).
Note : To get a better understanding of the SDP and SDAP in the BT framework please read [1].
1 The process of informationdiscovery is within Bluetooth-SDP a Client-Server principle. Based on that perspective,our implementation contains a Client (SDC) and a Server (SDS). Implementations from other companies, might give ita different name, but should be based on the same perspective.
Bluetooth PC Reference Stack by Ericsson
Page 76
See figure of Protocol Interface Overview of SDC:
Figure 5-27 : SDC Protocol Interface Overview
The application interface (API) connects the implemented Stack to an unknown applicationenvironment. The designated interfacing of an SDP client (SDC) application (i.e.messages/functions for searching services, searching attributes, browsing services) , running ontop of the SDP-protocol, is described in this section.
Implementation restrictions
In the SDP Spec is stated that SDP must be able to handle datablocks (like AttributeLists) of asize of uint32 (BT Spec version 1.0 Draft page 340 table 3.2). In our software stack we do notmeet that requirement. It is highly unlikely that datablocks for SDC with such a size, bigger than64K, will be used.
5.4.1.1 CONNECT PROCEDURE
5.4.1.1.1 OverviewThe Connect Procedure must be the first action performed on SDC before actual data can bediscovered and obtained between the Client and the Server.
5.4.1.1.2 Function Interface
SD_ReqServiceAttribute
SD_ServiceAttributeCnf
SD_ReqServiceSearchAttribute
SD_ServiceSearchAttributeCnf
SD_GetServiceRecordValue
SD_GetAttributeValue
SD_ReqConnectSD_ConnectCnf
SD_ReqDisconnect
SD_ServiceSearchCnf
SD_ReqServiceSearch
Application
SD Client(SDC)
SD_DisConnectCnf
Bluetooth PC Reference Stack by Ericsson
Page 77
Name Parameters Function Description
SD_ReqStart uiSeqNr This function makes sure that the SDCcomponent is started in order to send andreceive messages. The application on topof SDC should execute this function onlyonce.
SD_ReqConnect uiSeqNr,uiMaxFrameSize,BT_THandle
This function will start an SDP connection /instance using the handle (IEEE) to acertain SDP server belonging to one BT-device in order to send requests (maximumlength of requests is indicated byMaxFrameSize) for obtaining specific SDPServer Database values on that particularBT-device.
Table 5-44 : Function Interface of Connect Procedure
5.4.1.1.3 Message Interface
Name Contents Message Description
SD_START_CNF(SD_TStartCnf)
MSG_TControlHdr Means that the SDC has been started.
SD_CONNECT_CNF(SD_TConnectCnf)
MSG_TControlHdr,uiSdcHandle
Includes a newly obtained handle, theHandle, representing one instance out ofmultiple instances (connections to multipleSDP servers). The application is now readyto send requests to a specific SDP ServerDatabase identified by the Handle ( thatparticular BT-device )
SD_CONNECT_CNF_NEG(SD_TConnectCnfNeg)
MSG_TControlHdr,uiMaxFramesize
Negative reply on the SD_ReqConnectcommand. A connection could for somereason not be set-up. MaxFrameSizecontains the Datasize that the server wantsto use.
Table 5-45 : Message Interface of Connect Procedure
5.4.1.1.4 Data elements
Name Size Value Description
MSG_TControlHdr - - Holds MessageID of the message.
uiSeqNr uint16 - Sequence number. The reply of a messagemust always have the same sequence numberas the received message. This can be used tomatch multiple outstanding messages (Req/Ind)with the responses (Cnf/Rsp). In the functioncalls for Req/Ind the SeqNr is the firstparameter.
uiSdcHandle uint16 - Handle to SDC Client Instance representing oneinstance out of multiple instances (connectionsto multiple SDP servers).
uiMaxFrameSize uint16 SD_DEFAULT_MFS Maximum Frame Size of a sent datapacket. Thisparameter in the negative reply will show theMaxFrameSize from the Server.
Bluetooth PC Reference Stack by Ericsson
Page 78
BT_Handle - - HCI Handle obtained by the application (eg.SDAP) through the Stack Connection Manager(SCM) to set-up an SDP connection (IEEE).
Table 5-46 : Data Elements of Connect Procedure
Error Name Value Description
SD_POS_RESULT 0 Everything went alright
SD_NEG_RESULT -1 SDC is probably not started, or SDC is notconnected yet.
SD_NEG_TX_FAILED -2 Unable to send data through L2CAP orL2CAP did not get a response fromserverside
SD_NEG_NO_FREE_HANDLE -3 All SDC handles are used
SD_NEG_BUSY_L2CAP -4 Unable to send data through L2CAP.
SD_NEG_INVALID_ATTRIBUTE_ID -6 Attribute(s) have not been found.
SD_NEG_NO_MATCHING_SEARCH_PATTERN -7 Means that the service(s) have not beenfound on that particular bluetooth devicegiven the requested searchpattern.
SD_NEG_NO_RESPONSE_FROM_SERVER -8 Something went wrong. Eg. the connectiongot lost or a servererror
SD_NEG_DISCONNECTED -9 Something went wrong. Eg. The link got lost
SD_NEG_ERROR_UNSUPPORTED_SDP_VERSION -10 Name says it all.
SD_NEG_ERROR_INVALID_SERVICE_RECORD_HANDLE -12 The handle of the Service Record was notfound on the server, which means theservice record handle is not valid or theservice record does not exist (anymore).
SD_NEG_ERROR_INVALID_REQUEST_SYNTAX -13 Somehow the SDP Server did not receive acorrect Pdu syntax.
SD_NEG_MTU_NOT_ACCEPTED -14 Maximum Frame Size not accepted
Table 5-47 : General Error Codes
Bluetooth PC Reference Stack by Ericsson
Page 79
5.4.1.1.5 Communication procedures
Before an application can discover services of bluetooth devices in proximity, the application mustfirst set-up a connection to that particular device. To do that, the application should always makesure that SDC is started, using SD_ReqStart. It needs to execute this function only once. Afterstart-up, the application should call the function SD_ReqConnect.If this succeeded, the application can now perform queries on the device’s Service Discoverydatabase.
The Message Sequence Chart for Connect Procedure is defined below:
Figure 5-28 : MSC for Connect Procedure
Descriptions
Function SD_ReqStart makes sure that the SDC component has been started. This function willalways succeed, so there’s no negative reply.Message SD_TStartCnf tells the application that SDC has been started and that it can be used toexchange messages.Function SD_ReqConnect starts an SDP connection / instance using the handle to a certain SDPserver belonging to one BT-device in order to send requests for obtaining specific SDP ServerDatabase values on that particular BT-device. Reply Cnf/Pos. An SDC Handle will be obtainedrepresenting one instance out of multiple instances (connections to multiple SDP servers).Message SD_TConnectCnf is the positive reply on SD_ConnectReq including a newly obtainedhandle, the SDCHandle, representing one instance out of multiple instances (connections tomultiple SDP servers). The application is now ready to send requests to a specific SDP ServerDatabase identified by the Handle ( that particular BT-device )Message SD_TConnectCnfNeg is the negative reply on the SD_ReqConnect command.Errorcodes (see Table 5-47 : General Error Codes) :The tHeader.iResult can be :SD_NEG_NO_FREE_HANDLESD_NEG_MFS_NOT_ACCEPTEDSD_NEG_DISCONNECTED
5.4.1.2 SERVICE DISCOVERY PROCEDURE 1
5.4.1.2.1 Overview
SD ServerSDC
Client Server
AIR
Application
SD_TConnectCnfNeg
SD_TConnectCnf (SDCHandle)
Connection Succesfulll
Connection Unsuccesfulll
SD_ReqConnect
Connect Procedure SDC
SD_TStartCnf
SD_ReqStart
Bluetooth PC Reference Stack by Ericsson
Page 80
With the Service Discovery Procedure 1 data can be discovered and obtained from the Server ofanother Bluetooth Device using the SDCHandle. The application can now perform queries on thedevice’s Service Discovery database.
5.4.1.2.2 Function Interface
Name Parameters Function Description
SD_ReqServiceSearch uiSeqNr, uiSdcHandle,uiMaxServiceRecordCount,ucNrOfUuids,SD_TUuid *ptSearchPatternList
Used to locate service records (andget its handles) at the Serverside ofthe BluetoothUnit that match thisSearchPatternList. (Appendix 10.3 )
SD_ReqServiceAttribute uiSeqNr, uiSdcHandle,ulServiceRecordHandle,ucNrOfAttributes,*puiAttributeIDList
Retrieves specified attribute valuesfrom a specific service record (usingits handle) from the Serverside.
Table 5-48 : Function Interface of Service Discovery Procedure 1
5.4.1.2.3 Message Interface
Name Contents Message Description
SD_SERVICE_SEARCH_CNF(SD_TServiceSearchCnf)
MSG_TControlHdr,uiSdcHandle,uiNrOfMatchingServiceRecords,uiCurrentServiceRecordCount,ulServiceRecordHandleList
Contains a list of service recordhandles for service records thatmatch the SearchPatternList given inthe request.
SD_SERVICE_SEARCH_CNF_NEG(SD_TServiceSearchCnfNeg)
MSG_TControlHdr Negative reply on theSD_ReqServiceSearch command.Possible cause could be that noservice records were found.
SD_SERVICE_ATTRIBUTE_CNF(SD_TServiceAttributeCnf)
MSG_TControlHdr,uiSdcHandle,uiAttributeListByteCount,ucAttributeData
Contains a list of attributes (bothattribute id and attribute value) fromthe requested service record. Note :This atributelist is in Little Endianformat!
SD_SERVICE_ATTRIBUTE_CNF_NEG(SD_TServiceAttributeCnfNeg)
MSG_TControlHdr Negative reply on theSD_ReqServiceAttribute command.Possible cause could be that noattributes were found.
Table 5-49 : Message Interface of Service Discovery Procedure 1
5.4.1.2.4 Data elements
Name Size Value Description
MSG_TControlHdr - - Holds MessageID of the message.
puiAttributeIDList uint16 Pointer to a list of 16-bit AttributeId’s.These attributeId’s can be found in[1] and are used to obtainattributevalues from the server inanother Bluetooth unit. TheattributeId’s must be in chronologicalsequence in the list !
SD_TDataElement uint8 - See Table 9
Bluetooth PC Reference Stack by Ericsson
Page 81
SD_TUuid - SD_TDataElement,union { uint16 uiUuid16; uint32 ulUuid32; uint8 ucUuid128[16]; } TUuid;
The SearchPatternList (UUID List) isa data element sequence whereeach element in the sequence is aUUID. The sequence must containat least one UUID. The maximumnumber of UUIDs in the sequence is12. The list of UUIDs constitutes aservice search pattern (See alsoAppendix 10.3 for an example)
UcAttributeData uint8 - The first byte contains the beginningof a data element sequencecontaining attribute ids and attributevalues. The first element in thesequence contains the attribute id ofthe first attribute to be returned. Thesecond element in the sequencecontains the corresponding attributevalue. Successive pairs of elementsin the list contain additional attributeid and value pairs. Only attributesthat have non-null values within theservice record and whose attributeids were specified in theSD_ReqServiceAttribute arecontained in the AttributeData.Neither an attribute id nor an attributevalue is placed in the AttributeDatafor attributes in the service recordthat have no value. The attributesare listed in ascending order ofattribute id value. Note : Thisatributelist is in Little Endian format!Example : See Appendix 10.1
ucNrOfAttributes uint8 - Number of attributes in theattributelist
ucNrOfUuids uint8 0x1-0xC Number of UUID elements in theSearchPatternList with a maximum of12
uiAttributeListByteCount uint16 - The AttributeListByteCount containsa count of the number of bytes in thedatablock the AttributeDataparameter points to.
uiCurrentServiceRecordCount uint16 - Indicating the number of servicerecord handles that is contained inthe confirm. If no service recordsmatch the requested service searchpattern, this parameter is set to 0.Number should never be larger thanthe UiNrOfMatchingServiceRecordsvalue specified in the currentresponse.
uiMaxServiceRecordCount uint16 - 16-bit count specifying the maximumnumber of service record handles tobe associated with this request. Ifmore than N service records matchthe request, the SDP serverdetermines which matching servicerecord handles to associate with thisrequest
Bluetooth PC Reference Stack by Ericsson
Page 82
uiNrOfMatchingServiceRecords uint16 - Number of service recordsdiscovered on the server that matchthe requested service search pattern.If no
service records match the requestedservice search pattern, thisparameter is set to 0. N should neverbe larger than theuiMaxServiceRecordCount valuespecified in theSD_ReqServiceSearch.
uiSdcHandle uint16 - Handle to SDC Client Instancerepresenting one instance out ofmultiple instances (connections tomultiple SDP servers).
uiSeqNr uint16 - Sequence number. The reply of amessage must always have thesame sequence number as thereceived message. This can be usedto match multiple outstandingmessages (Req/Ind) with theresponses (Cnf/Rsp). In the functioncalls for Req/Ind the SeqNr is the firstparameter.
ulServiceRecordHandle uint32 - 32-bitparameter specifies the servicerecord from which attribute valuesare to be retrieved. The handle isobtained via a previousSD_ReqServiceSearch transaction
ulServiceRecordHandleList uint32 - First handle in the list, contains a listof service record handles. Thenumber of handles in the list is givenin the CurrentServiceRecordCountparameter. Each of the handles inthe list refers to a service record thatmatches the requested servicesearch pattern. Note that this list ofservice record handles does not havethe format of a data element. Itcontains no header fields, only the32-bit service record handles.
Table 5-50 : Data Elements for Service Discovery Procedure 1
Bluetooth PC Reference Stack by Ericsson
Page 83
Name Type Value Description
SD_DET_NULL 0x00 Null type
SD_DET_UINT8 0x08 Unsigned Integer 8 bits
SD_DET_UINT16 0x09 Unsigned Integer 16 bits
SD_DET_UINT32 0x0A Unsigned Integer 32 bits
SD_DET_UINT64 0x0B Unsigned Integer 64 bits
SD_DET_UINT128 0x0C Unsigned Integer 128 bits
SD_DET_INT8 0x10 Signed twos-compl. Integer 8 bits
SD_DET_INT16 0x11 Signed twos-compl. Integer 16 bits
SD_DET_INT32 0x12 Signed twos-compl. Integer 32 bits
SD_DET_INT64 0x13 Signed twos-compl. Integer 64 bits
SD_DET_INT128 0x14 Signed twos-compl. Integer 128 bits
SD_DET_UUID16 0x19 Universally Unique Identifier 16 bits
SD_DET_UUID32 0x1A Universally Unique Identifier 32 bits
SD_DET_UUID128 0x1C Universally Unique Identifier 128 bits
SD_DET_STRING8 0x25 0-terminated string 8 bits
SD_DET_STRING16 0x26 0-terminated string 16 bits
SD_DET_STRING32 0x27 0-terminated string 32 bits
SD_DET_BOOLEAN 0x28 Boolean, 1 byte
SD_DET_SEQUENCE8 0x35 Sequence of data elements 8 bits
SD_DET_SEQUENCE16 0x36 Sequence of data elements 16 bits
SD_DET_SEQUENCE32 0x37 Sequence of data elements 32 bits
SD_DET_ALTERNATIVE8 0x3D Selection from Sequence 8 bits
SD_DET_ALTERNATIVE16 0x3E Selection from Sequence 16 bits
SD_DET_ALTERNATIVE32 0x3F Selection from Sequence 32 bits
SD_DET_URL8 0x45 0-terminated string 8 bits
SD_DET_URL16 0x46 0-terminated string 16 bits
SD_TDataElement
SD_DET_URL32 0x47 0-terminated string 32 bits
Table 5-51 : Struct TDataElement in SDC
The table above contains type-identifiers for dataelements thatare commonly used in SDP and therefor also stored in SDC for correct dataexchange. The typesfor Strings, Sequences, Alternatives and URLs imply that the actual data for these types arepreceded by an 8, 16 or 32 bit field in which the length of the actual data is stored.
5.4.1.2.5 Communication procedures
If a connection to a particular has been performed, the application can now perform queries onthe device’s Service Discovery database. In principal, there are 2 procedures that the applicationmay follow, both with same result. The first procedure is to look for a particular service with thefunction SD_ReqServiceSearch and after the service record handle is obtained the application
Bluetooth PC Reference Stack by Ericsson
Page 84
can perform a SD_ReqServiceAttribute based on this service record handle to obtaine therequested attributevalues. The second procedure is to combine the two functions of procedure 1into one function called SD_ReqServiceSearchAttribute having the same result, but having lessmessages over the air.
Finally, if the application got its service information it asked for, it may do whatever it wants withthe data. The application may use the Database Manager (DBM) to store the data in a StackDatabase of retrieved ‘peerdata’ (See DBM). It may also use the support functions to filter theretrieved service data.
Figure 5-29 : MSC for Service Discovery Procedure 1
Descriptions
Function SD_ReqServiceSearch : The SDP client generates an SD_ReqServiceSearch to locateservice records that match the SearchPatternList. Upon receipt of this request, the SDP server(SDS) will examine the service record data base .Message SD_ServiceSearchCnf : Containing the service record handles of service records thatmatch the given SearchPatternList.Message SD_ServiceSearchCnf is the positive reply on the SD_ReqServiceSearch command.The reply contains a list of service record handles for service records that match theSearchPatternList given in the request.Message SD_ServiceSearchCnfNeg is the negative reply on the SD_ReqServiceSearchcommand.The tHeader.iResult can be :
SD ServerSDC
Client Server
AIR
Application
SD_TServiceSearchCnf(ServiceRecordHandle)
SD_ReqServiceAttribute(ServiceRecordHandle)
Service Discovery Procedure 1SDC
SD_ReqServiceSearch(SDCHandle)
SD_ServiceAttributeCnf(Requested Attribute values)
Search Succesfulll
Search Unsuccesfulll(eg. Services not found, perhaps try another
bluetooth device)
SD_ReqServiceSearch(Another SDCHandle)
etc.
Bluetooth PC Reference Stack by Ericsson
Page 85
Errorcodes (see Table 5-47 : General Error Codes) :SD_NEG_TX_FAILEDSD_NEG_BUSY_L2CAPSD_NEG_NO_RESPONSE_FROM_SERVERSD_ERROR_UNSUPPORTED_SDP_VERSIONSD_NEG_NO_MATCHING_SEARCH_PATTERNSD_ERROR_INVALID_REQUEST_SYNTAXSD_NEG_DISCONNECTED
Function SD_ReqServiceAttribute retrieves specified attribute values from a specific servicerecord, from the Server database, via the SDCHandle.Message SD_ServiceAttributeCnf is the positive reply on SD_ReqServiceAtribute. It contains alist of attributes (both attribute id and attribute value) from the requested service record.Message SD_ServiceAttributeCnfNeg is the negative reply on the SD_ReqServiceAttributecommand.Errorcodes (see Table 5-47 : General Error Codes ) :The tHeader.iResult can be :SD_NEG_TX_FAILEDSD_NEG_BUSY_L2CAPSD_NEG_NO_RESPONSE_FROM_SERVERSD_ERROR_UNSUPPORTED_SDP_VERSIONSD_ERROR_INVALID_SERVICE_RECORD_HANDLESD_NEG_INVALID_ATTRIBUTE_IDSD_ERROR_INVALID_REQUEST_SYNTAXSD_NEG_DISCONNECTED
5.4.1.3 SERVICE DISCOVERY PROCEDURE 2
5.4.1.3.1 OverviewWith the Service Discovery Procedure 2 data can be discovered and obtained from the Server ofanother Bluetooth Device using the SDCHandle. The application can now perform queries on thedevice’s Service Discovery database using only 1 function, which is a combination of thefunctions, mentioned in 2.3.
5.4.1.3.2 Function Interface
Name Parameters Function Description
SD_ReqServiceSearchAttribute uiSeqNr,uiSdcHandle,ucNrOfUuids,SD_TUuid *ptSearchPatternList,bGetAllAttributes,ucNrOfAttributes,*puiAttributeIDList
Combines the capabilities of theSD_ReqServiceSearch and theSD_ReqServiceAttribute into a singlerequest. More complex, but can reducethe number of messages sent over theair.
Table 5-52 : Function Interface of Service Discovery Procedure 2
5.4.1.3.3 Message Interface
Name Contents Message Description
Bluetooth PC Reference Stack by Ericsson
Page 86
SD_SERVICE_SEARCH_ATTRIBUTE_CNF(SD_TServiceSearchAttributeCnf)
MSG_TControlHdr,uiSdcHandle,uiAttributeListsByteCountucServiceRecordData
Contains the first byte of adatablock with a list of servicerecord handles andcorresponding attributes (bothattribute id and attribute value)that match the requestedSearchPatternList andattributelist contained inSD_ReqServiceSearchAttribute.Note : These atributelists are inLittle Endian format!. See alsoAppendix 10.2.
SD_SERVICE_SEARCH_ATTRIBUTE_CNF_NEG(SD_TServiceSearchAttributeCnfNeg)
MSG_TControlHdr Negative reply on theSD_ReqServiceSearchAttributecommand. Possible cause couldbe that no service records werefound.
Table 5-53 : Message Interface of Service Discovery Procedure 2
5.4.1.3.4 Data elements
Name Size Value Description
bGetAllAttributes uint8 True/False Boolean specifying the retrieval of allattributes (from 0x0000 - 0xFFFF)and its values of a service record. Ifit is set to False, you should specifywhich specific attributes to retrieveusing parameters ucNrOfAttributesand puiAttributeIDList. If it is set toTrue, you do not have to fill theseparameters ucNrOfAttributes andpuiAttributeIDList.
MSG_TControlHdr - - Holds MessageID of the message.
puiAttributeIDList uint16 Pointer to a list of 16-bitAttributeId’s. These attributeId’s canbe found in [3] and are used toobtain attributevalues from theserver in another Bluetooth unit. TheattributeId’s must be in chronologicalsequence in the list !
SD_TDataElement uint8 - See Table 5-51 : StructTDataElement in SDC
SD_TUuid - SD_TDataElement,union { uint16 uiUuid16; uint32 ulUuid32; uint8 ucUuid128[16]; } TUuid;
The SearchPatternList (UUID List) isa data element sequence whereeach element in the sequence is aUUID. The sequence must containat least one UUID. The maximumnumber of UUIDs in the sequence is12. The list of UUIDs constitutes aservice search pattern
ucNrOfAttributes uint8 - Number of attributes in theattributelist
ucNrOfUuids uint8 0x1-0xC Number of UUID elements in theSearchPatternList with a maximumof 12
Bluetooth PC Reference Stack by Ericsson
Page 87
ucServiceRecordData uint8 - First byte of a data elementsequence where each element inturn is a data element sequencerepresenting an attribute list. Eachattribute list contains attribute idsand attribute values from oneservice record. The first element ineach attribute list contains theattribute id of the first attribute to bereturned for that service record. Thesecond element in each attribute listcontains the corresponding attributevalue. Successive pairs of elementsin each attribute list containadditional attribute id and valuepairs. Only attributes that have non-null values within the service recordand whose attribute ids werespecified in theSDP_ReqServiceSearchAttributeare contained in the AttributeLists.Neither an attribute id or attributevalue is placed in AttributeLists forattributes in the service record thathave no value. Within each attributelist, the attributes are listed inascending order of attribute id value.The lists are distinguished throughthe ServiceRecord handle attribute.Note : These atributelists are in LittleEndian format!Example : See Appendix 10.2
uiAttributeListsByteCount uint16 - The AttributeListsByteCountcontains a count of the number ofbytes in the datablock theServiceRecordData parameterpoints to.
uiSdcHandle uint16 - Handle to SDC Client Instancerepresenting one instance out ofmultiple instances (connections tomultiple SDP servers).
uiSeqNr uint16 - Sequence number. The reply of amessage must always have thesame sequence number as thereceived message. This can be usedto match multiple outstandingmessages (Req/Ind) with theresponses (Cnf/Rsp). In the functioncalls for Req/Ind the SeqNr is thefirst parameter.
Table 5-54 : Data Elements for Service Discovery Procedure 2
5.4.1.3.5 Communication procedures
If a connection to a particular has been performed, the application can now perform queries onthe device’s Service Discovery database. In principal, there are 2 procedures that the applicationmay follow, both with same result. The first (Figure 3, paragraph 2.3) is to look for a particularservice with the function SD_ReqServiceSearch and after the service record handle is obtainedthe application can perform a SD_ReqServiceAttribute based on this service record handle toobtaine the requested attributevalues. The second (Figure 4 below) is to combine the twofunctions of procedure 1 into one function called SD_ReqServiceSearchAttribute having the sameresult, but having less messages over the air.Finally, if the application got its service information it asked for, it may do whatever it wants withthe data. The application may use the Database Manager (DBM) to store the data in a Stack
Bluetooth PC Reference Stack by Ericsson
Page 88
Database of retrieved ‘peerdata’. It may also use the support functions to filter the retrievedservice data.
Figure 5-30 : MSC for Service Discovery Procedure 2 Combination
Descriptions
Function SD_ReqServiceSearchAttribute combines the capabilities of the SD_ReqServiceSearchand the SD_ReqServiceAttribute into a single request. As parameters, it contains both aSearchPatternList and a list of attributes to be retrieved from service records that match theSearchPatternList. The SD_ReqServiceSearchAttribute and its reply are more complex and mayrequire more bytes than separate SD_ReqServiceSearch and SD_ReqServiceAttributetransactions. However, using SD_ReqServiceSearchAttribute may reduce the total number ofSDP transactions, particularly when retrieving multiple service records.Message SD_ServiceSearchAttributeCnf is the positive reply that contains the first byte of adatablock with a list of service record handles and corresponding attributes (both attribute id andattribute value) that match the requested SearchPatternList and attributelist contained inSD_ReqServiceSearchAttribute. With this pointer you can use specific functions likeSD_ReqValue to obtain the data in a decent manner.Message SD_ServiceSearchAttributeCnfNeg is the negative reply on theSD_ReqServiceSearchAttribute command.Errorcodes (see Table 5-47 : General Error Codes) :The tHeader.iResult can be :SD_NEG_TX_FAILEDSD_NEG_BUSY_L2CAPSD_NEG_NO_RESPONSE_FROM_SERVERSD_ERROR_UNSUPPORTED_SDP_VERSIONSD_NEG_NO_MATCHING_SEARCH_PATTERNSD_NEG_INVALID_ATTRIBUTE_IDSD_NEG_DISCONNECTED
5.4.1.4 DISCONNECT PROCEDURE
5.4.1.4.1 Overview
SD ServerSDC
Client Server
AIR
Application
SD_ReqServiceSearchAttribute(SDCHandle)
Service Discovery Procedure 2SDC (Combination procedure)
SD_TServiceSearchAttributeCnf(Requested Attribute values for
each found Service Record)
Search Succesfulll
Search Unsuccesfulll(eg. Services not found, perhaps try another
bluetooth device)
etc.
SD_ReqServiceSearchAttribute(Another SDCHandle)
Bluetooth PC Reference Stack by Ericsson
Page 89
If the application knows the characteristics of the services on that particular bluetooth device, theapplication can close the connection for that device with SD_ReqDisconnect: the DisconnectProcedure.
5.4.1.4.2 Function Interface
Name Parameters Function Description
SD_ReqDisconnect uiSeqNr,uiSdcHandle
Closedown of the SDP connection forexchanging data for this particular SDC-handle (IEEE).
Table 5-55 : Function Interface of Disconnect Procedure
5.4.1.4.3 Message Interface
Name Contents Message Description
SD_DISCONNECT_CNF
(SD_TDisconnectCnf)
MSG_TControlHdr, The connection to the SDP server device isnow disconnected for exchanging data andavailable for re-use. No NegCnf, this willalways succeed, even when theSDCHandle in the request did not exist.
Table 5-56 : Message Interface of Disconnect Procedure
5.4.1.4.4 Data elements
Name Size Value Description
MSG_TControlHdr - - Holds MessageID of the message.
uiSeqNr uint16 - Sequence number. The reply of a message mustalways have the same sequence number as thereceived message. This can be used to matchmultiple outstanding messages (Req/Ind) with theresponses (Cnf/Rsp). In the function calls forReq/Ind the SeqNr is the first parameter.
uiSdcHandle uint16 - Handle to SDC Client Instance representing oneinstance out of multiple instances (connections tomultiple SDP servers).
Table 5-57 : Data Elements of Disconnect Procedure
5.4.1.4.5 Communication proceduresIf the application knows the characteristics of the services on that particular bluetooth device, theapplication can close the connection for that device with SD_ReqDisconnect.
DescriptionsFunction SD_ReqDisconnect is used by the upper layer in the SDP Client device to initiateclosedown of the SDP connection for exchanging data.Message SD_TDisconnectCnf is the only reply on the disconnect request primitive. Theconnection to the SDP server device is now disconnected for exchanging data and available forre-use. No NegCnf, this will always succeed, even when the SDCHandle in the request did notexist !
5.4.1.5 SUPPORT PROCEDURES
Bluetooth PC Reference Stack by Ericsson
Page 90
5.4.1.5.1 OverviewIf the application discovered the characteristics of the services on that particular bluetooth device,the application might use the support procedures explained in this chapter to filter out the valuesof the retrieved block of Service Data.
5.4.1.5.2 Function Interface
Name Parameters Function Description
SD_GetValue pucAttributeList,ucNrOfQueryElements,SD_TQuery *,ppucResultValue,puiLength
This SUPPORT function retrieves values fromspecified attributes as given by the SD_TQueryparameter and ucNrOfQueryElements. The parameterpucAttributeList is the datablock retrieved bySD_TServiceAttributeCnf. The pointerppucResultValue indicates the position in thepucAttributeList where to find the queried attributevaluewith puiLength to read.
SD_GetNrOfAttributeLists pucServiceRecordData,puiNrOfLists
This SUPPORT function retrieves the number ofattributelists from a datablock wherepucServiceRecordData points to. This datablock isretrieved using the SD_ReqServiceSearchAttributefunction.The parameter pucServiceRecordData is the datablockretrieved by SD_TServiceSearchAttributeCnf.
SD_GetAttributeList pucServiceRecordData,uiAttributeListNumber,ppucAttributeList,puiAttributeListLength
This SUPPORT function retrieves anattributelist indicated by uiAttributeListNumber from adatablock where pucServiceRecordData points to. Thisdatablock is retrieved using theSD_ReqServiceSearchAttribute function.The parameter pucServiceRecordData is the datablockretrieved by SD_TServiceSearchAttributeCnf. Thepointer ppucAttributeList indicates the position in thepucServiceRecordData where to find the ServiceRecord with the Attributelist indicated byulServiceRecordHandle using puiAttributeListLength toread.
SD_GetServiceRecord pucServiceRecordData,ulServiceRecordHandle,ppucAttributeList,puiAttributeListLength
This SUPPORT function retrieves an attributelist from aspecific service record. The parameterpucServiceRecordData is a datablock sorted onservice recordhandles2. This datablock is retrievedusing the SD_ReqServiceSearchAttribute function.The parameter pucServiceRecordData is the datablockretrieved by SD_TServiceSearchAttributeCnf. Thepointer ppucAttributeList indicates the position in thepucServiceRecordData where to find the ServiceRecord with the Attributelist indicated byulServiceRecordHandle using puiAttributeListLength toread.
Table 5-58 : Function Interface of Support Procedures
5.4.1.5.3 Data elementsName Size Value Description
pucAttributeList uint8 - The parameter pucAttributeList is the datablockretrieved by SD_TServiceAttributeCnf includingattributeID’s and attributevalues
2 The function supposes that the ServiceRecord handle attribute is part of the SD_ReqServiceSearchAttribute function and it istherefore only intended to be used for this SD_ReqServiceSearchAttribute function. Note : Record handles can also be retrieved bySD_ReqServiceSearch.
Bluetooth PC Reference Stack by Ericsson
Page 91
ucNrOfQueryElements uint8 1-3 The number of queryelements to search for
SD_TQuery * - See Table 5-60 This is an array of query elements. Each queryelement is used to determine what to look for inpucAttributeList. The first query element mustalways indicate an attribute ID, the secondmust indicate a UUID and the third indicatesthe parameter number. the first is mandatory.The second is optional, but if the parameternumber is specified, it too becomes mandatory.Thus it has to be filled in like this: attribute IDOR attribute ID + UUID OR attribute ID + UUID+ param number
puiLength uint16 - Length to read from the ppucResultValue; It isalso a return value. It contains the length of thefound value, including Data Element Type(DET).
pucServiceRecordData uint8 - The parameter pucServiceRecordData is thedatablock retrieved by SD_TServiceSearchAttributeCnf including lists of attributeID’s andattributevalues
ulServiceRecordHandle uint32 - Record handle used to query the list indicatedby pucServiceRecordData
ppucAttributeList uint8 - This is a return value. When a requestedservicerecord is found, it points to the memorylocation within pucServiceRecordData wherethe attributelist lives. This attributelist can bequeried for attributevalues using the functionSD_GetValue with this ppucAttributeList as thefirst parameter pucAttributeList (seeSD_GetValue)
puiAttributeListLength uint16 - Length to read from the ppucAttributeList; It isalso a return value. It contains the length of thefound attributelist.
puiNrOfLists uint16 - Number of lists in the datablock wherepucServiceRecordData points to ; It is a returnvalue.
uiAttributeListNumber uint16 0.. (puiNrOfLists -1)
This list should be a list in the datablock wherepucServiceRecordData points to. Throughparameter puiNrOfLists in functionSD_GetNrOfAttributeLists you know if thereare any lists in the datablock. Example : IfpuiNrOfLists is 3, then attributelists can beretrieved, by using an uiAttributeListNumberwith value 0,1 or 2.
ppucResultValue uint8 - This is a return value. When a requested valueis found, it points to the memory location withinpucAttributeList where it lives. Note that italways points to the Data Element Type (DET)that is placed before the actual value,indicating what this value is ( a byte, string,whatever). For example, 0x08, 0x00 means anuint8 (DET = 8) with value 0x00. Anotherexample: 0x25, 0x06, 0x61, 0x62, 0x63, 0x64,0x65, 0x66 means a 8-bit string (DET=0x25),with length 0x06 and has the value of abcdef.
Table 5-59 : Data Elements of Support Procedure
Name Size Value Description
Bluetooth PC Reference Stack by Ericsson
Page 92
SD_TQuery uint8 SD_TQueryType tQueryType;uint16 uiAttribId;SD_TUuid tUuid;uint8 ucParam;
Query to search for inucAttributeData (to beused for functionSD_GetValue).See alsoSD_TServiceAttributeCnf
SD_TQueryType - typedef enum{ SD_ATTRIBUTE, SD_UUID, SD_PARAM} SD_TQueryType;
Type of query elementto search for (to be usedfor functionSD_GetValue)
SD_TGetValueResultCode - typedef enum{SD_VALUE_VALID,SD_VALUE_ATTRIBUTE_NOT_FOUND,SD_VALUE_UUID_NOT_FOUND,SD_VALUE_PARAM_NOT_FOUND,SD_NO_VALID_QUERY} SD_TGetValueResultCode;
Result Codes (to beused for functionSD_GetValue)
SD_TGetServiceRecordResultCode - typedef enum{SD_SERVICE_RECORD_VALID,SD_ SERVICE_RECORD_NOT_FOUND,} SD_TGetValueResultCode;
Result Codes (to beused for functionSD_GetServiceRecord)
Table 5-60 : Structs for Support Procedures
5.4.1.5.4 PrimitivesSD_GetValue
(uint8 *pucAttributeList, uint8 ucNrOfQueryElements,
SD_TQuery *patQuery,uint8 **ppucResultValue,uint16 *puiLength)
boolean SD_GetNrOfAttributeLists (uint8 *pucServiceRecordData, uint16 *puiNrOfLists);boolean SD_GetAttributeList (uint8 *pucServiceRecordData, uint16 uiAttributeListNumber, uint8 **ppucAttributeList, uint16 *puiAttributeListLength);SD_TGetServiceRecordResultCode SD_GetServiceRecord
(uint8 *pucServiceRecordData, uint32 ulServiceRecordHandle,
uint8 **ppucAttributeList,uint16 *puiAttributeListLength)
5.4.1.5.5 Communication proceduresIf the application discovered the characteristics of the services on that particular bluetooth device,the application might use the support procedures explained in this chapter to filter out the valuesof the retrieved block of Service Data (however, developers might also use its ownimplementations). Since these procedures are support functions, no messages will be sent overthe air or between the application and SDC.
Descriptions
Function SD_GetValue :
The function returns several possible values:SD_VALUE_VALID
Bluetooth PC Reference Stack by Ericsson
Page 93
The requested attribute, UUID or parameter value has been found, ppucResultValue points to thisvalue. SD_VALUE_ATTRIBUTE_NOT_FOUNDThe requested attribute has not been found. ppucResultValue is the same as pucAttributeValue.SD_VALUE_UUID_NOT_FOUNDThe requested UUID has not been found. ppucResultValue points to the location behind theattribute value, which was found.SD_VALUE_PARAM_NOT_FOUNDThe requested parameter has not been found. ppucResultValue points to the location behind theUUID, which was found.SD_NO_VALID_QUERYThis was an invalid query.
Function SD_GetServiceRecord :
This function returns the following possible values:SD_SERVICE_RECORD_VALIDThe requested service record has been found; ppucAttributeList points to this value.SD_SERVICE_RECORD_NOT_FOUNDThe requested service record has not been found. ppucAttributeList is the same aspucServiceRecordData.
Function SD_GetNrOfAttributeLists :
This function returns the following possible values:TRUEAt least 1 attributelist has been found.FALSEAttributeLists has not been found.
Function SD_GetAttributeList :
This function returns the following possible values:TRUEThe requested attributelist has been found indicated by ppucAttributeList. ParameterpuiAttributeListLength contains the length of this attributelist.FALSEThe requested attributelist has not been found.
5.4.2 DBM
The DataBase Manager (DBM) is a mechanism to provide access to data from services. TheDBM contains interfaces that let the user maintain its data. First, Service Discovery Data (servicerecords) should be added by the application. Second, when Bluetooth connections already existand an actual “ReqServiceData” (by SDC) has been performed, the application can add thisretrieved ‘peerdata’ to the DBM too, so the DBM can behave also like a stack for peerdata, theStackDB. Other protocol layers like RFCOMM, L2CAP and TCS Bin can add their ownparameters to the ServiceDiscoveryDB and read the retrieved protocol parameters from theStackDB (from the protocol layers, with L2CAP being the lowest layer) to set-up an actualconnection.The most important users however are SDS (Service Discovery Server3) to obtain or query theDBM for data to send back the SDC who asked for it, and the application that maintains the DBM.To get a clear overview of how an example Service Record in DBM is created (C-code) seeAppendix 11.
3 The process of informationdiscovery is within Bluetooth-SDP a Client-Server principle. Based on that perspective,our implementation contains a Client (SDC) and a Server (SDS). Implementations from other companies, might give ita different name, but should be based on the same perspective.
Bluetooth PC Reference Stack by Ericsson
Page 94
See the following figures, Protocol Overview and Interface Overview for a general overview:
Figure 5-31 : Protocol overview DBM
Figure 5-32: Protocol Interface overview DBM
The application interface (API) connects the implemented Stack to an unknown applicationenvironment. The designated interfacing to a service database in which certain service recordvalues are administered is described in the following chapters.
Database division
The DBM can currently handle two types of databases. The current interface functions arecompatible with both databases:
• Service Discovery Database – Database of the SDP server itself. This database shouldcontain one or more specific service records defined in the several Bluetooth Profilesdepending on the type of application.
• Stack Database - retrieved from the remote SDP server database. E.g. one particular remoteservice record value that should be cached by the client and read by the stack layers will bethe ProtocolDescriptorList attribute (see [1] for a definition of all universal attributes).
ServiceDiscovery
ServerDBM Protocol
Layers
DBM
DBM_ReqRegisterServiceDBM_RegisterServiceCnf
DBM_ReqUnRegisterService
DBM_UnRegisterServiceCnf
DBM_ReqRegistrationOfService
DBM_RegistrationOfServiceCnf
DBM_ReqAddAttribute
DBM_AddAttributeCnf
DBM_ReqReadAttribute
DBM_ReadAttributeCnf
DBM_ReqSearchServiceRecordHandle
DBM_SearchServiceRecordHandleCnf
DBM_ReqModifyAttribute
DBM_ModifyAttributeCnf
DBM_ReqDeleteAttribute
DBM_DeleteAttributeCnf
DBM_ReqAddDescriptor
DBM_AddDescriptorCnf
DBM_ReqReadDescriptor
DBM_ReadDescriptorCnf
DBM_ReqModifyDescriptor
DBM_ModifyDescriptorCnf
DBM_ReadAttributeDescriptorsCnf
DBM_ReqReadAttributeDescriptors
DBM_ReqStart
DBM_StartCnf
Bluetooth PC Reference Stack by Ericsson
Page 95
5.4.2.1 START Procedure
5.4.2.1.1 Overview
The Start procedure must be the first action performed on the DBM before actual data can behandled between the user (application or layers) and DBM.
5.4.2.1.2 Function Interface
Name Parameters Function Description
DBM_ReqStart void Start function to start component
DBM_ReqRegisterService uiSeqNr,DBM_TDatabase *
A service is administered in the DBMdatabase
DBM_ReqUnRegisterService uiSeqNr,ulDbmHandle
A service is removed in one of the severaldatabases
Table 5-61: Function Interface of Start Procedure
5.4.2.1.3 Message Interface
Name Contents Message Description
DBM_START_CNF
(DBM_TStartCnf)
MSG_TControlHdr This is the positive cnf for theDBM_ReqStart function.
DBM_REGISTER_CNF
(DBM_TRegisterServiceCnf)
MSG_TControlHdr,
ulDbmHandle
The Cnf for RegisterService holds theHeader and DBMHandle. The DBM handleis uniquely chosen by the DBM todistinguish among the other service recordsin the several databases
DBM_REGISTER_CNF_NEG
(DBM_TRegisterServiceCnfNeg)
MSG_TControlHdr The CnfNeg is replied when the registrationhas failed.
DBM_UNREGISTER_CNF
(DBM_TUnregisterServiceCnf)
MSG_TControlHdr This message is the positive reply (Cnf)representing if a service (record has beenremoved from one of the several databasesbased on the parameter ServiceRecordhandle defined in theDBM_TUnRegisterServiceReq command.
DBM_UNREGISTER_CNF_NEG
(DBM_TUnregisterServiceCnfNeg)
MSG_TControlHdr This message is the negative reply(CnfNeg) representing that a service recordhas not been removed from one the severaldatabases based on the parameterServiceRecord handle defined in theDBM_TUnRegisterServiceReq command.
Table 5-62: Message Interface of Start Procedure
5.4.2.1.4 Data elements
Name Size Value Description
Bluetooth PC Reference Stack by Ericsson
Page 96
DBM_TDatabase uint8 See Table5-65
Type of database for which services need to beregistered. See also structure DBM_TDatabase.Current values :0 : Service Discovery Database of the server itself1 : Stack Database of retrieved values from REMOTEService Discovery (peer data) Databases.
MSG_TControlHdr - - Holds MessageID of the message.
uiSeqNr uint16 - Sequence number. The reply of a message mustalways have the same sequence number as thereceived message. This can be used to match multipleoutstanding messages (Req/Ind) with the responses(Cnf/Rsp). In the function calls for Req/Ind the SeqNr isthe first parameter.
ulDbmHandle uint32 - Unsigned integer representing the unique value of aservice record maintained by the DBM.The two most significant bits represent the type ofdatabase (currently Service Discovery Database andStack Database).
Table 5-63: Data Elements of Start Procedure
Error Name Value Description
DBM_POS_RESULT 0 Everything went alright
DBM_ERROR_DBM_HANDLE_NOT_LOCATED -1 Name says it all.
DBM_ERROR_ATTRIBUTE_ID_NOT_LOCATED -2 Name says it all.
DBM_ERROR_DESCRIPTOR_UUID_NOT_LOCATED -4 Name says it all.
DBM_ERROR_ATTRIBUTE_ID_ALREADY_EXISTS -8 Name says it all.
DBM_ERROR_DESCRIPTOR_UUID_ALREADY_EXISTS -10 Name says it all.
DBM_ERROR_READ_ONLY_ATTRIBUTE -20 This implies that the atttribute (including itsvalue) cannot be modified or deleted
DBM_ERROR_ATTRIBUTE_HAS_DESCRIPTORS -40 This implies that the requested attributehas a value which consists of Descriptors(or Uuid’s). One should perform aDBM_ReqGetDescriptorValue to obtainthe values and probable parameters foreach Descriptor to obtain the completevalue belonging to this Attribute.
DBM_ERROR_ATTRIBUTE_HAS_NO_DESCRIPTORS -80 This implies that the Attribute has noattributevalue at all (BTW : this shouldactually never occur)
DBM_ERROR_NO_SERVICE_RECORD_HANDLES_FOUND -100 Error Code for the negative reply onDBM_ReqSearchServiceRecordHandles
DBM_NOT_STARTED -300 DBM should be started first beforeexecuting another request other thanDBM_ReqStart
Table 5-64 : General Error Codes
Bluetooth PC Reference Stack by Ericsson
Page 97
Name Type Value Description
DBM_DET_NULL 0x00 Null type
DBM_DET_UINT8 0x08 Unsigned Integer 8 bits
DBM_DET_UINT16 0x09 Unsigned Integer 16 bits
DBM_DET_UINT32 0x0A Unsigned Integer 32 bits
DBM_DET_UINT64 0x0B Unsigned Integer 64 bits
DBM_DET_UINT128 0x0C Unsigned Integer 128 bits
DBM_DET_INT8 0x10 Signed twos-compl. Integer 8 bits
DBM_DET_INT16 0x11 Signed twos-compl. Integer 16 bits
DBM_DET_INT32 0x12 Signed twos-compl. Integer 32 bits
DBM_DET_INT64 0x13 Signed twos-compl. Integer 64 bits
DBM_DET_INT128 0x14 Signed twos-compl. Integer 128 bits
DBM_DET_UUID16 0x19 Universally Unique Identifier 16 bits
DBM_DET_UUID32 0x1A Universally Unique Identifier 32 bits
DBM_DET_UUID128 0x1C Universally Unique Identifier 128 bits
DBM_DET_STRING8 0x25 0-terminated string 8 bits
DBM_DET_STRING16 0x26 0-terminated string 16 bits
DBM_DET_STRING32 0x27 0-terminated string 32 bits
DBM_DET_BOOLEAN 0x28 Boolean, 1 byte
DBM_DET_SEQUENCE8 0x35 Sequence of data elements 8 bits
DBM_DET_SEQUENCE16 0x36 Sequence of data elements 16 bits
DBM_DET_SEQUENCE32 0x37 Sequence of data elements 32 bits
DBM_DET_ALTERNATIVE8 0x3D Selection from Sequence 8 bits
DBM_DET_ALTERNATIVE16 0x3E Selection from Sequence 16 bits
DBM_DET_ALTERNATIVE32 0x3F Selection from Sequence 32 bits
DBM_DET_URL8 0x45 0-terminated string 8 bits
DBM_DET_URL16 0x46 0-terminated string 16 bits
DBM_TDataElement
DBM_DET_URL32 0x47 0-terminated string 32 bits
Table 5-65 : Struct TDataElement in DBM
The table above contains type-identifiers for dataelements that are commonly used in SDP andtherefor also stored in DBM for correct dataexchange. The types for Strings, Sequences,Alternatives and URLs imply that the actual data for these types are predecessed by an 8, 16 or32 bit field in which the length of the actual data is stored.
Name Type Value Description
DBM_ServiceDiscoveryDB 0 Make Service Record forBluetooth Profile
DBM_TDatabase
DBM_StackDB 1 Peer Data : Make servicerecord for storing retrievedservice data
Bluetooth PC Reference Stack by Ericsson
Page 98
Table 5-66 : Struct TDatabase with type of database
5.4.2.1.5 Communication procedures
Before an application can use its database, it should start DBM. If this succeeded the databaseshould be filled. To do that, the application should first register a particular service (record) . If thissucceeded, the application must fill this particular service record with attributes and its values inorder for other bluetooth devices to know what kind of services and what characteristics of theservices are running.
In the figure below, the Message Sequence Chart is shown for these actions. If an applicationwants to register another service it does not need to perform a DBM_ReqStart anymore. Thefigure also shows how the application can unregister a service record if the application wants forsome reason to delete a service record and its contents (attributes and values).
Note in general: Only an application can register and fill a database and do whatever is necessarywith it. Other users of the database, like protocols, can only perform read-only-actions 4!
4 Actually, only one write-action can the protocols perform, this is the DBM_ReqAddDescriptor to fill protocol specificparameters.
Bluetooth PC Reference Stack by Ericsson
Page 99
Note to the figures: To every Request there’s besides a Confirm also a Confirm Negative, but onlythe Confirm is shown in the figures below.
Figure 5-33 : MSC of Start Procedure
Descriptions
With DBM_ReqRegisterService a service is administered in the DBM database (tDatabaseType =0). E.g. The Headset Profile needs its record to be administered in the DBM Database. Or theProtocolDescriptorList from a remote service discovery database is being cached in the StackDatabase. DBM replies with DBM_TRegisterServiceCnf. Reply: Cnf/Neg
The Cnf for RegisterService holds the Header and DBMHandle. The DBM handle is uniquelychosen by the DBM to distinguish among the other service records in the several databases. TheCnfNeg is replied when the registration has failed.
With DBM_ReqUnRegisterService a service (record) is removed in one of the several databases.Reply: Cnf/Neg
Errorcodes (Table 5-64):CnfNeg tHdr.iResult for DBM_ReqUnRegisterService can be :DBM_ERROR_DBM_HANDLE_NOT_LOCATED
CnfNeg tHdr.iResult for DBM_ReqStart can be :DBM_NOT_STARTED
5.4.2.2 WRITE Actions
5.4.2.2.1 Overview
Write Actions are performed to fill the database with actual data of the Service Record. Theseactions can only be done by the application.
Application DBM
DBM_TRegisterServiceCnf (ulDBMHandle)
DBM_ReqRegisterService
DBM_TUnRegisterServiceCnf
DBM_ReqUnRegisterService (ulDBMHandle)
DBM_ReqStart
DBM_TStartCnf
After Start
Write-Actions on Service Record using specific ulDBMHandle
Optionalmultiple ServiceRecords
Bluetooth PC Reference Stack by Ericsson
Page 100
5.4.2.2.2 Function Interface
Name Parameters Function Description
DBM_ ReqAddAttribute uiSeqNr,ulDbmHandle,uiAttributeId,DBM_TAttributeValue *
Adds the specified attribute and its value tothe DBM database
DBM_ ReqDeleteAttribute uiSeqNr,ulDbmHandle,uiAttributeId
Deletes the specified attribute and its valuein the DBM database
DBM_ ReqModifyAttribute uiSeqNr,ulDbmHandle,uiAttributeId,DBM_TAttributeValue *
Modifies the specified attributevalue in theDBM database
DBM_ ReqAddDescriptor uiSeqNr,ulDbmHandle,uiAttributeId,DBM_TDescriptorUuid *,DBM_TDescriptorValue *
Adds the value of a particular UUID (thedescriptor) of an attribute and the valueitself. Note : this only counts for thoseattributes which have values like a dataelement sequence or –alternative (thatcontain descriptors)
DBM_ReqModifyDescriptor uiSeqNr,ulDbmHandle,uiAttributeId,DBM_TDescriptorUuid *,DBM_TDescriptorValue *
Modifes the value of a particular UUID (thedescriptor) of an attribute. Note : this onlycounts for those attributes which havevalues like a data element sequence or –alternative.
Table 5-67 : Function Interface of Write Actions
5.4.2.2.3 Message Interface
Name Contents Message Description
DBM_ADD_ATTRIBUTE_CNF(DBM_TAddAttributeCnf)
MSG_TControlHdr This message is the positive (Cnf) on thefunction DBM_TReqAddAttribute
DBM_ADD_ATTRIBUTE_CNF_NEG(DBM_TAddAttributeCnfNeg )
MSG_TControlHdr This message is the negative reply(CnfNeg) on the functionDBM_TReqAddAttribute
DBM_MODIFY_ATTRIBUTE_CNF(DBM_TModifyAttributeCnf)
MSG_TControlHdr This message is the positive (Cnf) on thefunction DBM_TReqModifyAttribute
DBM_MODIFY_ATTRIBUTE_CNF_NEG(DBM_TModifyAttributeCnfNeg)
MSG_TControlHdr This message is the negative reply(CnfNeg) on the functionDBM_TReqModifyAttribute
DBM_DELETE_ATTRIBUTE_CNF(DBM_TDeleteAttributeCnf)
MSG_TControlHdr This message is the positive (Cnf) on thefunction DBM_TReqDeleteAttribute
DBM_DELETE_ATTRIBUTE_CNF_NEG(DBM_TDeleteAttributeCnfNeg)
MSG_TControlHdr This message is the negative reply(CnfNeg) on the functionDBM_TReqDeleteAttribute
DBM_ADD_DESCRIPTOR_CNF(DBM_TAddDescriptorCnf)
MSG_TControlHdr This message is the positive (Cnf) on thefunction DBM_TReqAddDescriptor
DBM_ADD_DESCRIPTOR_CNF_NEG(DBM_TAddDescriptorCnfNeg)
MSG_TControlHdr This message is the negative reply(CnfNeg) on the functionDBM_TReqAddDescriptor
DBM_MODIFY_DESCRIPTOR_CNF(DBM_TModifyDescriptorCnf)
MSG_TControlHdr This message is the positive (Cnf) on thefunction DBM_TReqModifyDescriptor
DBM_MODIFY_DESCRIPTOR_CNF_NEG(DBM_TModifyDescriptorCnfNeg)
MSG_TControlHdr This message is the negative reply(CnfNeg) on the functionDBM_TReqModifyDescriptor
Bluetooth PC Reference Stack by Ericsson
Page 101
Table 5-68 : Message Interface of Write Actions
5.4.2.2.4 Data elements
Name Size Value Description
MSG_TControlHdr - - Holds MessageID of the message.
uiSeqNr uint16 - Sequence number. The reply of amessage must always have the samesequence number as the receivedmessage. This can be used to matchmultiple outstanding messages(Req/Ind) with the responses(Cnf/Rsp). In the function calls forReq/Ind the SeqNr is the firstparameter.
ulDbmHandle uint32 - Unsigned integer representing theunique value of a service recordmaintained by the DBM.The two most significant bits representthe type of database (currently ServiceDiscovery Database and StackDatabase).
uiAttributeId uint16 - Integer representing the AttributeIDwhich uniquely describes an attribute
DBM_TAttributeValue - DBM_TDataElement;pucValue
Attributevalue to be stored in thedatabase. StructDBM_TAttributeValue holds the typeand the Value of and Attribute. FortType see Table 5-65.
DBM_TDescriptorUuid - DBM_TDataElement;pucDescriptorUuidValue
Struct DBM_TDescriptorUuid holdsthe type and the the unique Value of aDescriptor UUID of the attribute in theservice record for which parameterscan be defined.Eg. Descriptor#0 = L2CAP UUID,Descriptor#1 = RFCOMM UUID. OrServiceClass#0 = Telephony UUID,ServiceClass#1 = Headset UUID .DBM_TDataElement is only forUUID,s (see Table 5-65).See Appendix 11 for a code example!
DBM_TDescriptorValue - uiNrOfParams;uiSizeOfValueInBytes;pucValue
Struct DBM_TDescriptorValue holdsthe number of parameters and the sizein bytes and the Value ( pointer to aparameter-block ) of a Descriptor(UUID).This value can contain uiNrOfParamsparameters.Eg.1. <tType Par1><DataPar1>
<tType Par2><DataPar2>2. <>where tType is of typeDBM_TDataelementSee Appendix 11 for a code example!
DBM_TDataElement uint8 - see Table 5-65.
pucDescriptorUuidValue uint8 * - Pointer to a 16, 32 or 128 bits UUIDvalue
uiSizeOfValueInBytes uint16 - Size of datablock
uiNrOfParams uint16 - Number of parameters of a descriptor
Bluetooth PC Reference Stack by Ericsson
Page 102
pucValue uint8 * - PucValue is a pointer to a parameter-block (used as bytearray). Length canvary.
Table 5-69 : Data Elements of Write Actions
If a particular Service (Record) is registered the application must fill this particular service recordwith attributes and its values in order for other bluetooth devices to know what kind of servicesand what characteristics of the services are running.
Figure 5-34 : MSC for Write Actions on the database
The figure shows how the application can fill a service record (with DBM_ReqAddAttribute andDBM_ReqAddDescriptor) in the database using the Service Record’s DBMHandle and how theapplication can alter the database if that’s necessary for the application.
After an application has filled a database, the database can be queried by its own users. The user(usually the protocol) can only perform read-only-actions on the database. However, there’s onewrite-action that the protocol must perform and that’s the DBM_ReqAddDescriptor function to fill aparticular service record with protocol specific parameters. The figure shows this action. This isnot a sequence that must be followed. Any function can be called any time.
Note in general: Only an application can register and fill a database and do whatever is necessarywith it. Other users of the database, like protocols, can only perform read-only-actions 5!
Note to the figures: To every Request there’s besides a Confirm also a Confirm Negative, but onlythe Confirm is shown in the figure below.
Descriptions
5 Actually, only one write-action can the protocols perform, this is the DBM_ReqAddDescriptor to fill protocol specificparameters.
Application DBM
DBM_AddAttributeCnf
DBM_ReqAddAttribute
DBM_ModifyAttributeCnf
DBM_ReqModifyAttribute
DBM_AddDescriptorCnf
DBM_ReqAddDescriptor
DBM_ModifyDescriptorCnf
DBM_ReqModifyDescriptor
DBM_DeleteAttributeCnf
DBM_ReqDeleteAttribute
Bluetooth PC Reference Stack by Ericsson
Page 103
Function DBM_ReqAddAttribute adds an arbitrary attribute to the DBM database. If the attributealready exists in the database, the reply is negative which could mean that the user may use theDBM_TReqModifyAttribute function.Message DBM_TAddAttributeCnf is the positive (Cnf) or negative reply (CnfNeg) on the functionDBM_TReqAddAttribute. The result in the MsgHeader is 0 if the reply is positive.ErrorCodes (see Table 5-64) :CnfNeg tHdr.iResult can be :DBM_ERROR_DBM_HANDLE_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_ID_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_ID_ALREADY_EXISTS
Function DBM_ReqDeleteAttribute deletes an attribute from a particular database in the DBMindicated by the DBMHandle. Reply: Cnf/NegMessage DBM_TDeleteAttributeCnf is the positive (Cnf) or negative reply (CnfNeg) on theDBM_TReqDeleteAttribute. The result in the MsgHeader is 0 if the reply is positive. Cnf forDBM_ReqDeleteAttribute Holds Header.ErrorCodes (see Table 5-64) :CnfNeg tHdr.iResult can be :DBM_ERROR_DBM_HANDLE_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_ID_NOT_LOCATEDDBM_ERROR_READ_ONLY_ATTRIBUTE
Function DBM_ReqAddDescriptor adds the value of a particular UUID (the descriptor) of anattribute and the UUID itself. Note : this only counts for those attributes which have values like adata element sequence or -alternative. If the attribute does not exist, the attribute is created (sothere’s no need to first make an DBM_ReqAddAttribute) !Message DBM_TAddDescriptorCnf is the positive (Cnf) or negative reply (CnfNeg) on theDBM_ReqAddDescriptor. Cnf for DBM_ReqAddDescriptor Holds Header.ErrorCodes (see Table 5-64) :CnfNeg tHdr.iResult can be :DBM_ERROR_DBM_HANDLE_NOT_LOCATEDDBM_ERROR_DESCRIPTOR_UUID_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_ID_ALREADY_EXISTSDBM_ERROR_DESCRIPTOR_UUID_ALREADY_EXISTS
Function DBM_ReqModifyAttribute updates an attributevalue from a specified service record in aspecific database in the DBM indicated by the DBMHandle. A Negative confirm is given if theDBMhandle if the attributeID is not found.Message DBM_TModifyAttributeCnf is the positive (Cnf) or negative reply (CnfNeg) as stated intHdr. The result in the MsgHeader is 0 if the reply is positive. Cnf for DBM_ReqModifyAttributeHolds Header.ErrorCodes (see Table 5-64) :CnfNeg tHdr.iResult can be :DBM_ERROR_DBM_HANDLE_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_ID_NOT_LOCATEDDBM_ERROR_READ_ONLY_ATTRIBUTE
Function DBM_ReqModifyDescriptor updates a descriptor in an attributevalue from a specifiedservice record in a specific database in the DBM indicated by the DBMHandle. A Negativeconfirm is given if the DBMhandle or the attributeID is not found.Message DBM_TModifyDescriptorCnf is the positive (Cnf) or negative reply (CnfNeg) as stated intHdr. Cnf for DBM_ReqModifyDescriptor Holds HeaderErrorCodes (see Table 5-64) :CnfNeg tHdr.iResult can be :DBM_ERROR_DBM_HANDLE_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_ID_NOT_LOCATEDDBM_ERROR_DESCRIPTOR_UUID_NOT_LOCATEDDBM_ERROR_READ_ONLY_ATTRIBUTE
Bluetooth PC Reference Stack by Ericsson
Page 104
5.4.2.3 READ actions
5.4.2.3.1 OverviewRead Actions are performed to read the database for the actual data of the Service Record (thecharacteristics of service). These actions can be done anytime by both the application and theuser, as long the database has been filled.
5.4.2.3.2 Function Interface
Name Parameters Function Description
DBM_ ReqReadAttribute uiSeqNr,ulDbmHandle,uiAttributeId
Read the value of the specified attribute in theDBM database.
DBM_ ReqReadAttributeDescriptor uiSeqNr,ulDbmHandle,uiAttributeId
The descriptors (UUID’s) of an AttributeValuecan be obtained. This only counts for thoseattribute which have values like Data elementsequence or –alternatives (that containdescriptors). After obtaining this list theapplication can obtain the descriptor values foreach of the descriptors in this list.
DBM_ ReqReadDescriptor uiSeqNr,ulDbmHandle,uiAttributeId,DBM_TDescriptorUuid *
The Descriptors Value of a descriptor (UUID) inan AttributeValue can be obtained.
Table 5-70 : Function Interface for Read Actions
5.4.2.3.3 Message Interface
Name Contents Message Description
DBM_READ_ATTRIBUTE_CNF(DBM_TReadAttributeCnf)
MSG_TControlHdr,DBM_TDataElement,ucValue
This message contains thecomplete attributevalue withtType being the type ofatributevalue and ucValue beingthe actual value.
DBM_READ_ATTRIBUTE_CNF_NEG(DBM_TReadAttributeCnfNeg)
MSG_TControlHdr This message is the negativereply (CnfNeg).
DBM_ READ_ATTRIBUTE_DESCRIPTORS_CNF(DBM_TReadAttributeDescriptorsCnf)
MSG_TControlHdruiNrOfUuidDescriptors,ulSizeOfValueInBytes,ucValue
Cnf forReadAttributeDescriptors. HoldsHeader and DescriptorList(stored in ucValue)
DBM_ READ_ATTRIBUTE_DESCRIPTORS_CNF_NEG(DBM_TReadAttributeDescriptorsCnfNeg)
MSG_TControlHdr This message is the negativereply (CnfNeg) on the functionDBM_TReadAttributeDescriptors. It means that the attribute hasno descriptors at all (an emptyattribute or attributeID without avalue).
DBM_READ_DESCRIPTOR_CNF(DBM_TReadDescriptorCnf)
MSG_TControlHdr,uiNrOfParams,ulSizeOfValueInBytes,ucValue
Cnf for ReadDescriptor holdsHeader and DescriptorValue(the parameters).
DBM_READ_DESCRIPTOR_CNF_NEG(DBM_TReadDescriptorCnfNeg)
MSG_TControlHdr This message is the negativereply (CnfNeg).
Table 5-71 : Message Interface for Read Actions
Bluetooth PC Reference Stack by Ericsson
Page 105
5.4.2.3.4 Data elements
Name Size Value Description
MSG_TControlHdr - - Holds MessageID of the message.
uiSeqNr uint16 - Sequence number. The reply of amessage must always have the samesequence number as the receivedmessage. This can be used to matchmultiple outstanding messages(Req/Ind) with the responses(Cnf/Rsp). In the function calls forReq/Ind the SeqNr is the firstparameter.
ulDbmHandle uint32 - Unsigned integer representing theunique value of a service recordmaintained by the DBM.The two most significant bits representthe type of database (currently ServiceDiscovery Database and StackDatabase).
uiAttributeId uint16 - Integer representing the AttributeIDwhich uniquely describes an attribute
DBM_TDescriptorUuid - DBM_TDataElement;pucDescriptorUuidValue
Struct DBM_TDescriptorUuid holdsthe type and the the unique Value of aDescriptor UUID of the attribute in theservice record for which parameterscan be defined.Eg. Descriptor#0 = L2CAP UUID,Descriptor#1 = RFCOMM UUID. OrServiceClass#0 = Telephony UUID,ServiceClass#1 = Headset UUID .DBM_TDataElement is only forUUID,s (see Table 5-65).
See Appendix 11 for a code example!
DBM_TDataElement uint8 - see Table 5-65.
pucDescriptorUuidValue uint8 * - Pointer to a 16, 32 or 128 bits UUIDvalue
uiSizeOfValueInBytes uint16 - Size of datablock
pucValue uint8 * - PucValue is a pointer to a parameter-block (used as bytearray). Length canvary.
uiNrOfParams uint16 - Number of parameters of a descriptor
uiNrOfUuidDescriptors uint16 - Number of descriptors in the list for theattribute
Bluetooth PC Reference Stack by Ericsson
Page 106
ucValue (DBM_TReadAttributeCnf) uint8 - First byte of a parameterblockspecifying the value belonging to theattributeID. Data must be read basedon the tType.Example :1. <Data>2. <Additional bits with length><Data>3. <NULL>where Data is the actual attributevalueand NULL implies that the attributecould contain descriptors (UUID’s)that, in turn, could contain parametersbelonging to this descriptor. Therefor,if the attributevalue is NULL, the usershould perform aDBM_ReadAttributeDescriptors andDBM_ReadDescriptor in order toobtain the value for this particularattribute (e.g. TheProtocolDescriptorList Attribute)See also Appendix 11 !
UcValue(DBM_TReadAttributeDescriptorsCnf)
uint8 list ofDBM_TDescriptorUuid
First byte of a list ofDBM_TDescriptorUuidEg.DBM_DET_UUID16, 0x0100,DBM_DET_UUID16, 0x0003,etc.( = tType, L2CAP UUID, tType, RFCOMM UUID, etc.)
UcValue(DBM_TReadDescriptorCnf)
uint8 - First byte of a block of data containinguiNrOfParams in the following format :<tType><ParamData 1><etc>
DBM_TDescriptorValue - uiNrOfParams;uiSizeOfValueInBytes;pucValue
Struct DBM_TDescriptorValue holdsthe number of parameters and the sizein bytes and the Value ( pointer to aparameter-block ) of a Descriptor(UUID).This value can contain uiNrOfParamsparameters.Eg.1. <tType Par1><DataPar1> <tType Par2><DataPar2>2. <>where tType is of typeDBM_TDataelementSee Appendix 11 for a code example!
Table 5-72 : Data Elements of Read Actions
5.4.2.3.5 Communication procedures
After an application has filled a database, its own users can query the database. In the figurebelow, the Message Sequence Charts are shown for the read actions on a database.
Note to the figures: To every Request there’s besides a Confirm also a Confirm Negative, but onlythe Confirm is shown in the figures below.
Bluetooth PC Reference Stack by Ericsson
Page 107
Note: To every Request there’s besides a Confirm also a Confirm Negative, but only the Confirmis shown in the figures below.
Figure 5-35 : MSC for Read Actions
Descriptions
Function DBM_ReqReadAttribute let a server application (profile) and protocol layers read fromthe DBM database what attributevalues are listed for a specified Attribute ID and DBMhandle.Returns Cnf/Neg if DBM handle or AttributeID is not found.Message DBM_TReadAttributeCnf is the positive (Cnf) or negative reply (CnfNeg). It returns ahandle to the AttributeListvalue for the requested attributeID and DBMhandle. The result in theMsgHeader is 0 if the reply is positive. Cnf for DBM_ReqReadAttribute Holds Header andAttributeValue.ErrorCodes (see Table 5-64) :CnfNeg tHdr.iResult can be :DBM_ERROR_DBM_HANDLE_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_ID_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_HAS_DESCRIPTORS
Function DBM_ReqReadAttributeDescriptors : the Descriptors (UUID’s) of an AttributeValue canbe obtained. This only counts for those attribute which have values like Data element sequence or–alternatives. After obtaining this list the application can obtain the descriptor values for each ofthe descriptors in this list.Message DBM_TReadAttributeDescriptorsCnf is the positive (Cnf) or negative reply (CnfNeg) onthe TReadAttributeDescriptorsCnf function.Cnf for ReadAttributeDescriptors Holds Header and DescriptorList.ErrorCodes (see Table 5-64) :CnfNeg tHdr.iResult can be :DBM_ERROR_DBM_HANDLE_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_ID_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_HAS_NO_DESCRIPTORS
Function DBM_ReqReadDescriptor : the Descriptors Value (UUID’s) of an AttributeValue can beobtained. This only counts for those attribute which have values like Data element sequence or –alternatives. After obtaining the DescriptorsList with the functionDBM_ReqReadAttributeDescriptors the application can obtain the descriptor values for each ofthe descriptors in this list with this function.
User (Application/Protocol) DBM
DBM_ReadAttributeCnf
DBM_ReqReadAttribute
DBM_ReadDescriptorCnf
DBM_ReqReadDescriptor
DBM_ReqReadAttributeDescriptors
DBM_ReadAttributeDescriptorsCnf
Bluetooth PC Reference Stack by Ericsson
Page 108
See also Appendix 11.Message DBM_TReadDescriptorCnf is the positive (Cnf) or negative reply (CnfNeg). Cnf forReadDescriptor Holds Header and DescriptorValue.ErrorCodes (see Table 5-64) :CnfNeg tHdr.iResult can be :DBM_ERROR_DBM_HANDLE_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_ID_NOT_LOCATEDDBM_ERROR_DESCRIPTOR_UUID_NOT_LOCATEDDBM_ERROR_ATTRIBUTE_HAS_NO_DESCRIPTORS
5.4.2.4 Miscellaneous actions
5.4.2.4.1 Overview
5.4.2.4.2 Function Interface
Name Parameters Function Description
DBM_ ReqSearchServiceRecordHandle uiSeqNr,DBM_TDescriptorValue *
The user can search for servicerecord handles (the values of theAttributeID ServiceRecordHandle,see [1]) based on the UUIDList.DBM searches itsServiceDiscoveryDB for thoseService Records that match withthis UUIDList.Note : This function is primarelyused by SDS.
Table 5-73 : Function Interface for Miscellaneous Actions
5.4.2.4.3 Message Interface
Name Contents Message Description
DBM_SEARCH_SERVICE_RECORD_HANDLE_CNF(DBM_TSearchServiceRecordHandleCnf)
MSG_TControlHdr,uiNrOfDbmHandlesSRHandles,ucValue
This message holds the list ofcombinations of bothServiceRecordHandlesDBMHandles. It’s acombinationlist because inorder to reach a certainServiceRecord you’ll need itscorresponding DBMHandle.
DBM_SEARCH_SERVICE_RECORD_HANDLE_CNF_NEG(DBM_TSearchServiceRecordHandleCnfNeg)
MSG_TControlHdr This message is the negativereply (CnfNeg) on thefunction DBM_TReqSearchServiceRecordHandle
Table 5-74 : Message Interface for Miscellaneous Actions
5.4.2.4.4 Data elements
Name Size Value Description
MSG_TControlHdr - - Holds MessageID of the message.
Bluetooth PC Reference Stack by Ericsson
Page 109
uiSeqNr uint16 - Sequence number. The reply of amessage must always have the samesequence number as the receivedmessage. This can be used to matchmultiple outstanding messages (Req/Ind)with the responses (Cnf/Rsp). In thefunction calls for Req/Ind the SeqNr isthe first parameter.
ulDbmHandle uint32 - Unsigned integer representing theunique value of a service recordmaintained by the DBM.The two most significant bits representthe type of database (currently ServiceDiscovery Database and StackDatabase).
uiNrOfDMBHandlesSRHandles uint16 - DBM searches its ServiceDiscoveryDBfor those Service Records that matchwith a UUIDList. The Cnf contains aDBMHandleSRHHandleList in whichexists combinations of both DBMHandleand the ServiceRecordHandle. Thisinteger is a combinationlist because inorder to reach a certain ServiceRecordyou’ll need its correspondingDBMHandle.
ucValue uint8 - First byte to a block of data(DBM_TDBMHandleSRHandle) in whichcombinations of DMBHandles andSRHandles are given. Size dependsuopn the integeruiNrOfDMBHandlesSRHandles. EachHandle is 32-bits. So if this integer is eg.2, it means that 2 combinations arefound and the datablock will be therefor2*2*4-bytes of size. Format :DBMHandle1, SRHandle1,DBMHandle2, SRHandle2, etc.
DBM_TDescriptorValue - uiNrOfParams;uiSizeOfValueInBytes;pucValue
Struct DBM_TDescriptorValue holds thenumber of parameters and the size inbytes and the Value ( pointer to aparameter-block ) of a Descriptor (UUID).This value can contain uiNrOfParamsparameters.Eg.1. <tType Par1><DataPar1> <tType Par2><DataPar2>2. <>where tType is of typeDBM_TDataelementSee Appendix A for a code example!
uiSizeOfValueInBytes uint16 - Size of datablock
pucValue uint8 * - PucValue is a pointer to a parameter-block (used as bytearray). Length canvary.
DBM_TDBMHandleSRHandle - UlDbmHandle,ulServiceRecordHandle
Struct containing combinations of bothDBMHandle and SRHandle
uiNrOfParams uint16 - Number of parameters of a descriptor
Table 5-75 : Data Elements for Miscellaneous Actions
5.4.2.4.5 Communication procedures
Bluetooth PC Reference Stack by Ericsson
Page 110
After an application has filled a database, the database can be queried in several ways. Somemiscellaneous actions are shown in figure below.
Note to the figures: To every Request there’s besides a Confirm also a Confirm Negative, but onlythe Confirm is shown in the figure below.
Figure 5-36 : MSC for Miscellaneous Actions
Description
Function DBM_ReqSearchServiceRecordHandle searches for service record handles (the valuesof the AttributeID ServiceRecordHandle, see SDP-specification) based on the UUIDList. DBMsearches its ServiceDiscoveryDB for those Service Records that match with this UUIDList. TheCnf contains a DBMHandleSRHHandleList in which exists combinations of both DBMHandle andthe ServiceRecordHandle.Message DBM_TSearchServiceRecordHandleCnf is the positive (Cnf) or negative reply (CnfNeg)on the DBM_ReqSearchServiceRecordHandle. Cnf for SearchServiceRecordHandle HoldsHeader and a List.ErrorCodes (see Table 5-64) :CnfNeg tHdr.iResult can be :DBM_ERROR_ATTRIBUTE_ID_NOT_LOCATEDDBM_ERROR_NO_SERVICE_RECORD_HANDLES_FOUND
5.4.3 SDS
5.4.3.1 START Procedure
5.4.3.1.1 Overview
The Start procedure is the only action that can be done on SDS in order to have SDS send andreceive messages.
5.4.3.1.2 Function Interface
Name Parameters Function Description
SDS_ReqStart uiSeqNr Start function to start component
User (Application/Protocol) DBM
DBM_ReqSearchServiceRecordHandle
DBM_SearchServiceRecordHandleCnf
Bluetooth PC Reference Stack by Ericsson
Page 111
Table 5-76: Function Interface of SDS Start Procedure
5.4.3.1.3 Message Interface
Name Contents Message Description
SDS_START_CNF(SDS_TStartCnf)
MSG_TControlHdr This is the positive cnf for theSDS_ReqStart function.
SDS_START_CNF_NEG(SDS_ TStartCnfNeg)
MSG_TControlHdr The CnfNeg is replied when startup hasfailed.
Table 5-77: Message Interface of SDS Start Procedure
5.4.3.1.4 Data elements
Name Size Value Description
MSG_TControlHdr - - Holds MessageID of the message.
uiSeqNr uint16 - Sequence number. The reply of a message mustalways have the same sequence number as thereceived message. This can be used to match multipleoutstanding messages (Req/Ind) with the responses(Cnf/Rsp). In the function calls for Req/Ind the SeqNr isthe first parameter.
Table 5-78: Data Elements of SDS Start Procedure
Error Name Value Description
SDS_POS_RESULT 0 Everything went alright
SDS_NEG_RESULT -1 Something went wrong. Eg. SDS isnot yet started.
Table 5-79 : General Error Codes
5.4.3.1.5 Communication procedures
Before any messages can be handled by SDS the application should start SDS. In the figurebelow, the Message Sequence Chart is shown for this action.
Figure 5-37 : MSC of SDS Start Procedure
Descriptions
Application SDS
SDS_ReqStart
SDS_TStartCnf
SDS_TStartCnfNegSDS not started
Bluetooth PC Reference Stack by Ericsson
Page 112
Function SDS_ReqStart will startup the SDS component in order to send and receive messages.Message SDS_TStartCnf is the positive reply.The CnfNeg tHdr.iResult for SDS_ReqStart can be :SDS_NEG_RESULT
Bluetooth PC Reference Stack by Ericsson
Page 113
5.5 L2CAP Interface
HCI Driver
RFCOMM
L2CAP
SDP
OS Adaptation
Serial Line Interface
Application
ApplicationProgrammersInterface
VOSInterface
SILInterface
SCM
The L2CAP stack component exports services to one or more ‘adapted protocols’:
5.5.1 Overview
The interface to L2CA is a message interface. For each message towards L2CA a function isavailable to create and send that message to the correct destination in L2CA. L2CA users arefree to compose the messages themselves, the described functions just make life easier. So thedescribed functions are all message generators for messages being sent to L2CA, and thedescribed messages are all messages sent out of L2CA to the component requesting the L2CAservices. An exception is the data-interface; it has some extra functions to support it.
The offered services by L2CA can be divided in the following functional groups:
• Component management.Start of the L2CA component as being applicable to all components in the BT stack. Alsoprotocol registration on top of L2CA, together with the subscription on events coming fromL2CA is part of this group.Supported functionality in this group:
– Start:Start L2CA
– Register:An adapted protocol asks L2CA for making use of its services.
– DeRegister:Tell L2CA that an adapted protocol doesn’t want to make use of its service anymore.
– FillPDL:Ask L2CA to fill its parameters belonging to the indicated PDL, managed by the DBMcomponent.
– AclInUseAsk L2CA if a specific ACL link is used by L2CA.
– Info:Ask the peer L2CA to reply the requested info.
Bluetooth PC Reference Stack by Ericsson
Page 114
– Version:Ask L2CA for its version.
• Connection establishment.Set-up/accept/disconnect a logical L2CA connection.Supported functionality in this group:
– Connect:Set-up a data connection to L2CA.
– Disconnect:Disconnect a data connection to L2CA.
– Echo:Ask the peer L2CA unit to send a reply, to check weather the peer L2CA is still alive.
– QosViolation:The configured QoS is violated.
• Connection configuration.(Re)configure an L2CA connection.Supported functionality in this group:
– Config:(Re)configure an existing L2CA connection.
• Data transfer.Send/receive data.Supported functionality in this group:
– Data:Exchange data between the adapted protocol and L2CA.
– DataInfo:Exchange necessary information to establish a data connection service.
5.5.2 Component management.
The start procedure must be the first action performed on L2CA, before any other action can bedone. After the start procedure is completed, protocols can register themselves to L2CA, andother processes can request L2CA to fill its PDL in DBM.
5.5.2.1 Interface and MSC's
5.5.2.1.1 Function interface
Name Parameters Function description
L2CA_ReqStart uiSeqNr Will cause L2CA to start
L2CA_ReqRegister uiSeqNr, uiPsm for registration of an adapted protocol
L2CA_ReqDeRegister uiSeqNr, uiPsm for deregistration of an adaptedprotocol
L2CA_ReqFillPdl uiSeqNr, uiServiceRecordId, a request for L2CA to fill it's
Bluetooth PC Reference Stack by Ericsson
Page 115
uiPsm information in the PDL.
L2CA_ReqAclInUse uiSeqNr, tHandle to ask L2CAP if a specific Acl link isreally in use, i.e. if there are openconnections on that ACL link
5.5.2.1.2 Message interface
Name Contents Message description
L2CA_TStartCnf tHdr Confirm on a start request
L2CA_TStartCnfNeg tHdr Negative confirm on a start request
L2CA_TRegisterCnf tHdr Confirm on a register request.
L2CA_TDeregisterCnf tHdr Confirm of a de-registration
L2CA_TRegisterCnfNeg tHdr Negative Confirm on a registerrequest
L2CA_TFillPdlCnf tHdr Confirm on a Fill PDL request
L2CA_TFillPdlCnfNeg tHdr Negative Confirm on a Fill PDLrequest
L2CA_TAclInUseCnf tHdr Confirms that an ACL is in use
L2CA_TAclIinUseCnfNeg tHdr Confirms that an ACL is not in use.
5.5.2.1.3 Data elements
Name Size Value Description
uiSeqNr uint16 - To be able to match multiplereplies on multiple requests
uiPsm uint16 - Protocol/Service multiplexor
uiServiceRecordId uint16 - Identifier of service record inDBM
tHandle BT handle of an AL link
5.5.2.1.4 Communication procedures
Before an application can make use of L2CA, L2CA must be started. There is no need to startL2CA multiple times for multiple applications/protocols, once L2CA is started, allapplications/protocols can register themselves to L2CA.
However, each application/protocol is allowed to start L2CA. If L2CA was started already, apositive response is sent back immedeately.
In the figures below, the MSC's for starting and registering are depicted.
Bluetooth PC Reference Stack by Ericsson
Page 116
L2CA_ReqStart()
L2CA_StartCnf
AdaptedProtocol
L2CA L2CA any process
Figure 5-38 MSC for starting L2CA : MSC_START
Starting is required to make L2CA register itself to the processes it needs for normal operation. IfL2CA registered itself to all processes it needs, a StartCnf is sent back to the originator.
L2CA_ReqRegister(PSM)
L2CA_RegisterCnf
AdaptedProtocol
L2CA L2CA Adapted Protocol
Figure 5-39 MSC for registering to L2CA: MSC_REGISTER
L2CA needs to know which processes are capable of processing data sent to a certain PSM.Therefore, these processes need to identify themselves to L2CA. Only one process at a time canbe registered for the same PSM.
L2CA_ReqRegister(PSM)
L2CA_RegisterCnf
AdaptedProtocol
L2CA L2CA Adapted Protocol
Figure 5-40 MSC for deregistering from L2CA: MSC_DEREGISTER
When an adapted protocol is unable to process further data from L2CA (for example, when thehuman user closed an application), that protocol should deregister itself from L2CA. Thederegistration is confirmed by a L2CA_DeregisterCnf message. Deregistration always succeeds,i.e. there is no L2CA_DeregisterCnfNeg message
Bluetooth PC Reference Stack by Ericsson
Page 117
L2CA_ReqAclInUse(tHandle)
L2CA_AclInUseCnf
AdaptedProtocol
L2CA L2CA Adapted Protocol
Figure 5-41 MSC for requesting if an Acl is in use by L2CA
Other processes can ask L2CA if it is using a certain ACL link. This is the only way for otherprocesses to find out if an ACL link can be deleted or not.
L2CA_ReqStartInvoking this function will cause L2CA and all the components needed by L2CA (HCI, DBM andSCM) to start. Subsequent start requests will be queued and responded after L2CA is fullystarted. If L2CA is already started, subsequent start requests will be responded immediately.
L2CA_StartCnfThis is the positive reply on L2CA_ReqStart(). The reply will also be positive in case L2CA wasalready started.
L2CA_StartCnfNegThis is the negative reply on L2CA_ReqStart(). This reply will be sent back when L2CAP has tooless resources for minimal functionality.
L2CA_ReqRegisterRequest L2CA for a registration of the adapted protocol layer, identified with ‘Psm’. The processcalling this function will be administrated in L2CA as the IndHandler for all Ind and Evt messagesmeant for this protocol layer.
L2CA_TRegisterCnfThis is the positive reply on L2CA_ReqRegister(). L2CA has accepted the registration request.
L2CA_TRegisterCnfNegThis is the negative reply on L2CA_ReqRegister(). L2CA has refused this request, and'Hdr.Result' contains the reason for this refusal. Possible result values for this negative reply:- L2CA_NEG_NO_RESOURCE : L2CA is unable to create the nessecary administrations for thisregistration request, because the maximum number of protocols is reached. (See the constantMAX_UPPER_LAYERS)
- L2CA_NEG_ALREADY_REGISTERED: L2CA already has an administration for the requestedPSM. No more than one protocol at a time can be subscribed on a specific PSM.
L2CA_ReqDeRegisterA protocol can deregister itself from L2CA, to enable other protocols to register themselves.
L2CA_TDeRegisterCnfThis is the positive reply on L2CA_ReqDeRegister(); the reply will always be positive, also in casethere was no registration at all. L2CA accepts the removal of the protocol registration by the upperlayer.
Bluetooth PC Reference Stack by Ericsson
Page 118
L2CA_ReqFillPdlA request to L2CA to fill its information in the PDL (Protocol Descriptor List), identified with‘ServiceRecordId’. This information is stored, making use of the DBM service that knows where tostore the L2CA info using this ‘ServiceRecordId’. ‘Psm’ defines the contents of the L2CA info inthis PDL.
L2CA_TFillPdlCnfThis is the positive reply on L2CA_ReqFillPdl(). L2CA has filled its parameters in the PDL(Protocol Descriptor List), identified in the request.
L2CA_TFillPdlCnfNegThis is the negative reply on L2CA_ReqFillPdl(). L2CA has refused this request, and 'Hdr.Result'contains the reason for this refusal. Possible result values for this negative reply:- L2CA_NEG_DBM_REFUSED: L2CA is unable to store its information because it is refused bythe DBM module for one or another reason.
L2CA_ReqAclInUseBecause L2CA is not the owner of a physical connection and other processes might use the sameconnection, the connection is managed by another process. The only way for this managementprocess to know if L2CA is really using the connection is asking it to L2CA. This request providesa mean to ask it to L2CA. (Actually it is not a request, it is a question)
L2CA_AclInUseCnfThis is the positive answer on the ReqAclInUse request. If L2CA uses the Acl, this confirm is sentback.
L2CA_AclInUseCnfNegThis is the negative answer on the ReqAclInUse request. If L2CA doesn't use the Acl, thisnegative confirm is sent back.
5.5.3 Connection establishment.
5.5.3.1 Interface and MSC's
5.5.3.1.1 Function interface
Name Parameters Function description
L2CA_ReqConnect uiSeqNr, tHandle, uiPsm Will initiate a connection setupprocedure
L2CA_RspConnect **pptMsg, iResult, uiCid obligated response on a connectionindication.
L2CA_ReqDisconnect uiSeqNr, uiCid Will initiate a connection terminationprocedure
5.5.3.1.2 Message interface(Each message contains a header. This header is not mentioned in the following table)
Name Contents Message description
Bluetooth PC Reference Stack by Ericsson
Page 119
L2CA_TConnectCnf uiCid Confirm on a connect request
L2CA_TConnectCnfNeg - Negative confirm on a connectrequest
L2CA_TConnectInd uiCid, tHandle Indication to an upper layer thatsomeone wants to connect
L2CA_TDisconnectCnf - Confirms that the disconnect requestis processed
L2CA_TDisconnectEvt - tells an upper layer that there is noconnection anymore.
5.5.3.1.3 Data elements
Name Size Value Description
uiSeqNr uint16 - To be able to match multiplereplies on multiple requests
tHandle uint16 - handle of an ACL link
uiPsm uint16 table 5.4 of [1] Protocol/Service multiplexor, see5.2 of [1]
iResult int16 various ID of a result of an action.
ppMsg -- ptr to ptr to msg Some responses require a betterreference to the indica-tionthey're replying on. Thisparameter refers to suchindications.
5.5.3.1.4 Communication procedures
L2CA_ReqConnect()(Handle) L2CA_TConnectInd
(Handle, CID)L2CA_RspConnect()
L2CA_TConnectCnf(CID)
AdaptedProtocol
L2CA L2CA AdaptedProtocol
Figure 5-42 MSC of setting up a connection
L2CA_ReqDisconnect()(CID)
L2CA_DisconnectEvtL2CA_DisconnectCnf (Cid)
AdaptedProtocol
L2CA L2CA AdaptedProtocol
Figure 5-43 MSC of terminating a connection
In this MSC, the ReqDisconnect can also be initiated from the other side.
Bluetooth PC Reference Stack by Ericsson
Page 120
L2CA_ReqDisconnect()(CID)
L2CA_DisconnectCnf
AdaptedProtocol
L2CA L2CA AdaptedProtocol
Figure 5-44 MSC of terminating a non-existent connection.
L2CA_DisconnectEvt L2CA_DisconnectEvt(Cid) (Cid)
AdaptedProtocol
L2CA L2CA AdaptedProtocol
Figure 5-45 MSC of disconnection in case of e.g. Out of Range
L2CA_ReqConnectThe protocol, identified with ‘Psm’ is requesting a L2CA channel to the device identified with the‘Handle’ to HCI.The ‘SeqNr’ is simply copied into the header of the request message, it can be used to find thecorresponding confirm for this request.ATTENTION: there is a special ‘Handle’ defined for local communication (BT_HANDLE_LOCAL).With this ‘Handle’ L2CA acts as a local routing device, connecting 2 adapted layers in the samedevice as if they where using a Bluetooth connection. So in this case L2CA doesn’t make use ofthe HCI services.
L2CA_TConnectCnfThis is the positive reply on L2CA_ReqConnect(). It returns the unique 'Cid' to L2CA. This 'Cid'acts as the local connection handle between the requesting layer and L2CA for the requestedconnection.
L2CA_TConnectCnfNegThis is the negative reply on L2CA_ReqConnect(). L2CA has refused this request, and'Hdr.Result' contains the reason for this refusal. Possible result values for this negative reply:- L2CA_NEG_NO_FREE_CID: The local L2CA has no free entries in it's CID list.
- L2CA_NEG_NO_RESOURCE: The local L2CA has no resources left.
- L2CA_NEG_P_PSM_NOT_SUPPORTED: The peer L2CA has no protocol available for therequested PSM
- L2CA_NEG_P_SECURITY_BLOCK: Connection refused by the peer L2CA due to a securityreason
- L2CA_NEG_P_NO_RESOURCE: The peer L2CA has no resources left for an additionalconnection
L2CA_TConnectIndThis event signals a new connection to the upper layer. The channel ID of this new channel isidentified with 'Cid'. Also the ACL-link used by this channel is returned via the 'Handle' abstraction.
Bluetooth PC Reference Stack by Ericsson
Page 121
The upper layer will reply with L2CA_TConnectRsp or the Neg version of it, depending whether ithas accepted this connection or not.
L2CA_RspConnectThis is the reply of the upper layer on a L2CA_TConnectInd message. ‘Result’ defines whether itis a positive (Result >= 0) or a negative reply, where the ‘Result’ value also indicates the reasonfor the negative reply. Recognised ‘Results’ are:- L2CA_POS_RESULT: The L2CAP connection is established.
- L2CA_NEG_P_REJECTED: The peer entity refused the connection
- L2CA_POS_P_PENDING: The peer entity is still busy requesting a pin-code from the user.
- L2CA_NEG_P_PSM_NOT_SUPPORTED: The peer entity has no protocol available for therequested PSM
- L2CA_NEG_P_SECURITY_BLOCK: A wrong pin-code is entered, or the devices are not paired.
- L2CA_NEG_P_NO_: The peer entity has not enough resources to establish a connection.
- L2CA_NEG_NO_FREE_CID: The local entity has reached it's maximum number of connections.
- L2CA_NEG_NO_RESOURCE: The local entity has not enough resources to establishconnection.
REMARK: When the connection is accepted, the connection is not open yet. First it must beconfigured for both directions, initiated via an L2CA_ReqConfig.
L2CA_ReqDisconnectOpposite of L2CA_ReqConnect(). It requests for a disconnection of the data channel as identifiedwith ‘Cid’. As soon as the disconnection is finished, a positive reply (L2CA_TDisconnectCnf) willbe returned. The Reply is always positive because ‘disconnect’ wills always succeed, also in casethe connection was already terminated.
L2CA_TDisconnectCnfThis is the positive reply on L2CA_ReqDisconnect(); the reply will always be positive, also in casethere was no connection at all. L2CA accepts the termination of the connection by the upperlayer. When something strange is detected, it will be replied as a positive ‘Hdr.Result’, which canhave the following values:- L2CA_POS_RESULT- L2CA_POS_CID_UNKNOWN- L2CA_POS_NO_RESOURCE- L2CA_POS_TIMEOUT
In all cases the L2CAP channel is disconnected locally. When the result is L2CA_POS_RESULT,the remote side is also notified for this disconnection.
L2CA_TDisconnectEvtThis event signals a broken data connection to the upper layer. The channel ID of this brokenchannel is identified with 'Cid'. No reply is necessary. There are 2 possible causes for thisdisconnection: the destination has disconnected this logical L2CAP channel, or the ACL link wasbroken (e.g. out of range).
5.5.4 Connection configuration.
5.5.4.1 Interface and MSC's
Bluetooth PC Reference Stack by Ericsson
Page 122
5.5.4.1.1 Function interface
Name Parameters Function description
L2CA_ReqConfig uiSeqNr, uiCid, uiInMtu,ptOutFlow, uiLocalFlushTime
initiates a configuration procedure
L2CA_RspConfig **pptMsg, iResult, uiOutMtu,ptInFlow,uiRemoteFlushTime
obligated response on a connectionindication.
5.5.4.1.2 Message interface
Name Contents Message description
L2CA_TConfigCnf tHdr, uiCid, uiInMtu,tOutFlow, uiLocalFlushTime
Confirm on a configuration request,the upper layer accepts the configrequest by sending this confirm back.
L2CA_TConfigCnfNeg tHdr, uiCid, uiInMtu,tOutFlow, uiLocalFlushTime
The upper layer sends back thismessage if the configuration is notaccepted.
L2CA_TConfigInd tHdr, uiCid, uiOutMtu,tInFlow, uiRemoteFlushTime
Indication to an upper layer that thepeer entity wants to configure theconnection.
5.5.4.1.3 Data elements
Name Size (default)Value
Description
uiSeqNr uint16 - To be able to match multiple replies onmultiple requests
tHandle uint16 - handle of an ACL link
uiCid uint16 ID of an L2CA connection. Can bedifferent on both endpoints of an L2CAconnection.
uiInMtu,uiOutMtu
uint16 672 Maximum transmission Unit on incomingor outgoing flow, see par. 6.1 of [1]
ptOutFlowptInFlow
QoS - Quality of Service of incoming flow oroutgoing flow
uiLocalFlushTimeuiRemoteFlushTime
uint16 0xFFFF indicates how long retansmissions will bedone on incoming or outgoing flow
pptMsg ptr - Pointer to message on which a responseis generated
iResult uint16 - ID of result of an action
The structure of QoS is:typedef struct{ uint8 ucSpare; uint8 ucServiceType; uint32 ulTokenRate; uint32 ulTokenBucketSize; uint32 ulPeakBandWidth;
Bluetooth PC Reference Stack by Ericsson
Page 123
uint32 ulLatency; uint32 ulDelayVariation;} L2CA_TQos;
5.5.4.1.4 Communication procedures
L2CA_ReqConfig()(CID) L2CA_ConfigInd
(CID)L2CA_RspConfig()
L2CA_ConfigCnf
AdaptedProtocol
L2CA L2CA AdaptedProtocol
Figure 5-46 MSC of configuration sequence (for one direction)
The MSC shows the configuration for the data-channel from left to right. An L2CA connectionhowever must be configured in both directions. This can be done simultaneously, there is no needto complete one direction before configuring the other direction. If a L2CA_ReqConfig is repliedwith a L2CA_ConfigCnfNeg, the adapted protocol is free to choose between reconfiguring ordisconnecting.
L2CA_ReqConfigRequest for (re)configuration of the L2CAP channel, identified with ‘Cid’. The followingparameters will be negotiated with the remote side:- ‘InMtu’: the MTU this L2CA entity can accept.(default = L2CA_CONFIG_DEFAULT_MTU)- ‘OutFlow’: the QoS of this L2CA entity for outgoing data flow.- ‘LocalFlushTime’: the time (ms) to wait before terminating an unresponsive link.(default = L2CA_CONFIG_DEFAULT_FLUSH_TIME)REMARK1: The mentioned parameters will arrive as a L2CA_TConfigInd on the remote side.REMARK2: This command may start the (re)configuration. During this configuration, data may notbe send.
L2CA_TConfigCnfThis is the positive reply on L2CA_ReqConfig(). This means that the remote side has acceptedthe requested configuration for the indicated channel ('Cid'), seen from this side. The contents ofthe negotiated parameters (‘InMtu’, ‘OutFlow’, and ‘LocalFlushTime’) are also returned.REMARK: The channel may be used for data transfer when a L2CA_TConfigInd has beenreceived earlier which was accepted with a positive reply.
L2CA_TConfigCnfNegThis is the negative reply on L2CA_TConfigReq. L2CA has refused this request, and 'Hdr.Result'contains the reason for this refusal. Possible result values for this negative reply:- L2CA_NEG_P_PARAMS_NOT_ACCEPTED: The remote side refuses this configurationbecause it cannot handle some requested parameters. A modified configuration is returnedcontaining a configuration that would be accepted when requested. So re-configuration isnecessary. The receiving upper layer should compare the original Req parameters with thesereturned parameters in order to detect the differences for re-negotiation.- L2CA_NEG_P_REJECTED: The requested configuration is refused without giving a specificreason. The returned configuration is the same as the requested one. This means that (re)-configuration is not possible on this channel, so a retry is useless.The 'Cid' identifies the L2CA channel being configured. Replied configuration parameters in case
Bluetooth PC Reference Stack by Ericsson
Page 124
of L2CA_NEG_CONFIG_NOT_ACCEPTED:- InMtu: Max. number of bytes to be received in 1 packet over this Cid.- OutFlow: QoS of the data stream going out (sent) over this Cid.- LocalFlushTime: Time period (ms) before this station will flush a data packet when it is not ableto send it to the remote station.
L2CA_TConfigIndThis event signals that the other side wants to (re)configure the existing connection identified with'Cid'. The parameters being configured are:- OutMTU: Max. number of bytes to be send in 1 packet over this Cid.- InFlow: QoS of the data stream, received over this Cid.- RemoteFlushTime: Time period (ms) before the remote station will flush a data packet when it isnot able to send it to this station.The upper layer will reply with L2CA_TConfigRsp or the Neg version of it, depending whether ithas accepted this configuration or not.REMARK: This indication may start the (re)configuration. During this configuration, data may notbe send.
L2CA_RspConfigThis is the reply of the upper layer on a L2CA_TConfigInd message. ‘Result’ defines whether it isa positive (Result >= 0) or a negative reply, where the ‘Result’ value also indicates the reason forthe negative reply. Recognised ‘Results’ are:- L2CA_POS_RESULT
- L2CA_NEG_REJECTED: The upper layer refuses this connection. No reason is provided,reconfiguration is useless.
- L2CA_NEG_CONFIG_NOT_ACCEPTED: The upper layer refuses this configuration because itcannot handle some requested parameters. A modified configuration is returned containing aconfiguration that would be accepted when requested. So re-configuration is necessary from theremote side. The remote side should compare the original Req parameters with these returnedparameters in order to detect the differences for re-negotiation.REMARK1: The mentioned parameters will arrive as a L2CA_TConfigCnf on the remote side.REMARK2: The channel may be used for data transfer when a positive ‘Result’ is returned andalso a positive L2CA_TConfigCnf has been received earlier.
5.5.5 Data transfer
5.5.5.1 Interface and MSC's
5.5.5.1.1 Function interface
Name Parameters Function description
L2CA_DataAlloc uiLength Allocate an OS-buffer containing aMSG_TDataMsg structure.
L2CA_DataSend ucSeqNr, pucData, uiLength,uiCid
Sends the data
L2CA_DataFree pucData For releasing an allocated buffer, viaL2CA_DataAlloc. Only necessarywhen the allocated buffer is not sentto L2CAP.
L2CA_DataExtract ptDataInd, puiLength, puiCid Extract header information from thejust received DataInd.
Bluetooth PC Reference Stack by Ericsson
Page 125
L2CA_RspData uiSeqNr, iResult, uiCid Rsp on a L2CA_DataInd.
L2CA_ReqDataInfo uiSeqNr Request to L2CA to send info aboutheader and trailer sizes
5.5.5.1.2 Message interface
Name Contents Message description
L2CA_TDataCnf tHdr, uiCid Positive reply on L2CA_DataSend.
L2CA_TDataCnfNeg tHdr Negative reply on L2CA_DataSend.
L2CA_TDataInd tHdr Indication to an upper layer that datahas arrived
L2CA_TDataInfoCnf ucNrOfHdrBytes,ucNrOfTrailerBytes
Tells the size of L2CA header andtrailer.
5.5.5.1.3 Data elements
Name Size (default)Value
Description
uiSeqNr uint16 - To be able to match multiple replies onmultiple requests
pucData ptr - Ptr to memory where the user can put it'sinformation.
uiCid uint16 - Connection ID of an L2CA connection
ucNrOf...Bytes uint8 - Size of L2CA header and trailer in bytes.
ptDataInd ptr - pointer to message containing a receiveddata indication.
uiLength uint16 - Length of the data to be sent/allocated.
5.5.5.1.4 Communication procedures
L2CA_DataAlloc(Length)
L2CA_DataSend(CID, Data)(CID, Data) L2CA_TDataInd
L2CA_TDataCnf (CID)L2CA_RspData()
L2CA_DataExtract()
AdaptedProtocol
L2CA L2CA AdaptedProtocol
Figure 5-47 MSC of a single data transfer
Bluetooth PC Reference Stack by Ericsson
Page 126
Before sending data, the most sophisticated way of allocating space for it is usingL2CA_DataAlloc, as figured out in Figure 5-47. However, it is possible for a user to allocate thememory itself. The user then is responsible for clearing the header and trailer space to zero's.
L2CA_DataAllocAllocate an OS-buffer containing a MSG_TDataMsg structure. The ‘Length’ defines the number ofbytes the requester wants to put into this buffer, where this routine adds enough header andtrailer space for a copyless transfer of the data buffer through the stack. The returned ‘Data’points at the start location in this buffer where the requester can put its data.
L2CA_DataSendSend the filled data message to the correct process (‘DataReqHandler’) in L2CAP, the ‘Cid’defines the used connection channel to L2CA, published at connection set-up (seeL2CA_TConnectCnf message). The ‘Length’ defines the number of bytes the requester has putinto this buffer; this ‘Length’ should be less then the original requested ‘Length’ (seeL2CA_DataAlloc), where ‘Length’ = 0 is interpreted as being equal to the original requested‘Length’. When the ‘Length’ is not equal to 0, the new ‘Length’ will be placed in the message; butonly when the new ‘Length’ is shorter then the requested ‘Length’, otherwise a negative reply(L2CA_DataCnfNeg) will be returned. The ‘SeqNr’ field is simply copied into the correspondingL2CA_TdataCnf, so the requester is able to link the request with the reply.
L2CA_TDataCnfThis is the positive reply on L2CA_DataSend(). It tells the upper layer that L2CA has processedthe data-packet sent earlier.
L2CA_TDataCnfNegThis is the negative reply on L2CA_DataSend().L2CA has refused this request, and 'Hdr.Result' contains the reason for this refusal. Possibleresult values for this negative reply:- L2CA_NEG_BUSY: L2CA is already busy with a data-packet on this Cid; only one outstandingpacket is allowed.– L2CA_NEG_LENGTH_TOO_BIG: The new ‘Length’ is bigger then the allocated length fortransmission.
L2CA_DataFreeSuppose the application has allocated a data buffer for transmission via L2CA_DataAlloc. Nowthe application decides for one or another reason not to send this packet. In that case thecorresponding OS buffer needs to be released. The application however is not able to determinethis buffer pointer, so therefore this routine should be used. The ‘Data’ pointer points at the startof the requested data in the OS buffer as returned by L2CA_DataAlloc.ATTENTION: This function may only be used for this purpose. So not for releasing a receivedL2CA_TDataInd buffer!!
L2CA_TDataIndThe data message, sent to the upper layer, has the common data message structure.
L2CA_DataExtractExtract the header information and data from the just received ‘DataInd’. The header items‘Length’ and ‘Cid’ are returned, together with the pointer to the start of the ‘Data’ (function return).With this action also the header of L2CA is stripped from the data-packet! So this routine can onlybe used once for each received DataInd!!
L2CA_RspDataReply (Rsp) on a received L2CA_TDataInd message. The ‘SeqNr’ must be copied from the‘SeqNr’ as received in the corresponding L2CA_TDataInd message. The ‘Cid’ identifies the data
Bluetooth PC Reference Stack by Ericsson
Page 127
connection channel. The ‘Result’ defines whether it is a positive or a negative reply; (Result < 0)means a negative reply
L2CA_ReqDataInfoRequest for fixed data information, necessary to supply a data interface service. This requestshould be made after registering to the L2CA when the upper layer offers a data connectionservice.
L2CA_TDataInfoCnfReply on L2CA_ReqDataInfo. This reply is always positive. It contains the size of the header(‘NrOfHeaderBytes’) this L2CA layer is using, including the lower layers. The same can be said oftrailer size ate the end of the data-packet (‘NrOfTrailerBytes’). With this information, therequesting layer is able to provide a data service making use of “copyless” data transfer.
5.5.6 Connection misc
5.5.6.1 Interface and MSC's
5.5.6.1.1 Function interface
Name Parameters Function description
L2CA_ReqInfo uiSeqNr, tHandle, uiInfoType Sends an INFORMATION REQUESTto a peer entity
L2CA_ReqEcho uiSeqNr, uiLength,
pucData
Sends an ECHO REQUEST to apeer entity
5.5.6.1.2 Message interface
Name Contents Message description
L2CA_TInfoCnf uiInfoType, uiResult Positive reply on Info Request
L2CA_TInfoCnfNeg - negative version
L2CA_TEchoCnf pucData, uiDataSize Positive reply on Echo Request
L2CA_TEchoCnfNeg - negative version
5.5.6.1.3 Data elements
Name Size (default) Value Description
uiSeqNr uint16 - To be able to match multiple replieson multiple requests
pucData ptr - Ptr to memory where the user canput it's information.
uiResult uint16 - see table 5.9 of [1]
uiDataSize uint16 - Length of to be send/received data
uiInfoType uint16 - See table 5.8 of [1]
Bluetooth PC Reference Stack by Ericsson
Page 128
5.5.6.1.4 Communication procedures
L2CA_ReqInfo(InfoType)
L2CA_TInfoCnf(InfoType, Result)
AdaptedProtocol
L2CA L2CA AdaptedProtocol
Figure 5-48 MSC of an Info Request
L2CA_ReqEcho(data)
L2CA_TEchoCnf(data)
AdaptedProtocol
L2CA L2CA AdaptedProtocol
Figure 5-49 MSC of an Echo Request
When the InfoReq function is called, the corresponding message is sent to a peer entity. Thisentity will respond with an Information Response, indicating whether the peer entity supports therequesting functionality.When the EchoReq function is called, the corresponding message is sent to a peer entity. Thisentity will respond with an Echo Response, and this response invokes an L2CA_TEchoCnfmessage sent to the original requester.L2CA_ReqEchoRequest for fixed data information, necessary to supply a data interface service. This requestshould be made after registering to the L2CA when the upper layer offers a data connectionservice.
Bluetooth PC Reference Stack by Ericsson
Page 129
5.5.7 COMMUNICATION PROCEDURES
In this paragraph an example of how a complete sequence of setting up a connection, transferdata through it and disconnect could be done. This MSC is just an example, other sequences arealso possible.
AdaptedProtocol
L2CA L2CA AdaptedProtocol
Registration
Connection set-up
Connection configuration
Connection configuration
data transfer
data transfer
data transfer
data transfer
data transfer
disconnect
Figure 5-50 Example of a complete MSC
The start sequence is left out, because the start mechanism is only added to influence the bootsequence of each component. Starting is a part of system boot, not of normal operation ofL2CAP.
The connection setup arrow is drawn from left to right. However, a connection setup could alsohave been initialized from right to left.
The connection configuration arrows are drawn seperately. Both directions are obligatory, butthey're allowed to intervene.
Data transfer is allowed in both directions, the channel is full duplex.
Bluetooth PC Reference Stack by Ericsson
Page 130
Disconnect is not obligatory, however it would free system resources when an unused L2CAPconnection would be closed down. Closing down all L2CAP channels will not close down the ACLlink, this is beyond the scope of L2CAP.
When an ACL link is removed whilst L2CAP still has open connections, those connections will beclosed down. The protocols involved will receive a disconnect indication. This is a typical scenarioin case of an out of range situation.
5.5.8 Data types + constants.
5.5.8.1 L2CA_TQoStypedef struct{
uint8 ucSpare;uint8 ucServiceType;uint32 ulTokenRate;uint32 ulTokenBucketSize;uint32 ulPeakBandWidth;uint32 ulLatency;uint32 ulDelayVariation;
} L2CA_TQos;Description:See the L2CAP specification for detailed info. Most common values for these fields can befilled/interpreted with the L2CA_QOS_... constants.
Bluetooth PC Reference Stack by Ericsson
Page 131
Name Size Value / Range Description
Spare 1 0x00 For future use
ServiceType 4 0x00000000-0xFFFFFFFF
Level of required service (see L2CA_QOS_SERVICE...constants).
TokenRate 4 0x00000000-0xFFFFFFFF
Continuously transfer rate (bytes/sec).
TokenBucketSize 4 0x00000000-0xFFFFFFFF
Size of the token bucket (bytes).
PeakBandWidth 4 0x00000000-0xFFFFFFFF
Burst transfer rate (bytes/sec).
Latency 4 0x00000000-0xFFFFFFFF
Max. transmission delay (msec).
DelayVariation 4 0x00000000-0xFFFFFFFF
Difference between max. and min. latency.
Table 5-80 : L2CA_TQos data elements
5.5.8.2 L2CA_NEG_…: negative reply results.
Negative reply results. Two types of negative replies are possible:L2CA_NEG_--- have a local reason, i.e. the local L2CA generated the negative reply.L2CA_NEG_P_--- have a 'peer reason', i.e. the peer L2CA entity generated the negative reply.
#define L2CA_NEG_NO_REASON ((int16) -1)#define L2CA_NEG_TIMEOUT ((int16) -2)#define L2CA_NEG_NO_FREE_CID ((int16) -3)#define L2CA_NEG_BUSY ((int16) -4)#define L2CA_NEG_CONFIG_NOT_ACCEPTED ((int16) -5)#define L2CA_NEG_REJECTED ((int16) -6)#define L2CA_NEG_NOT_SUPPORTED ((int16) -7)#define L2CA_NEG_LENGTH_TOO_BIG ((int16) -8)#define L2CA_NEG_ILLEGAL_LENGTH ((int16) -9)#define L2CA_NEG_TX_FAILED ((int16) -10)#define L2CA_NEG_NO_RESOURCE ((int16) -11)#define L2CA_NEG_CID_UNKNOWN ((int16) -12)#define L2CA_NEG_DISCONNECTED ((int16) -13)#define L2CA_NEG_DBM_REFUSED ((int16) -14)#define L2CA_NEG_ALREADY_ADMINISTRATED ((int16) -15)#define L2CA_NEG_P_REJECTED ((int16) -16)#define L2CA_NEG_P_PSM_NOT_SUPPORTED ((int16) -17)#define L2CA_NEG_P_SECURITY_BLOCK ((int16) -18)#define L2CA_NEG_P_NO_RESOURCE ((int16) -19)#define L2CA_NEG_P_PARAMS_NOT_ACCEPTED ((int16) -20)#define L2CA_NEG_P_UNKNOWN_OPTIONS ((int16) -21)#define L2CA_NEG_P_INFO_NOT_SUPPORTED ((int16) -22)
5.5.8.3 L2CA_POS_…: positive reply results.Positive reply results. Two types of positive replies are possible:L2CA_--- have a local reason, i.e. the local L2CA generated the reply. L2CA _P_--- have a 'peerreason', i.e. the peer L2CA entity generated the reply..#define L2CA_POS_RESULT MSG_POS_RESULT#define L2CA_POS_P_PENDING ((int16) 1)#define L2CA_POS_CID_UNKNOWN ((int16) 2)#define L2CA_POS_NO_RESOURCE ((int16) 3)
Bluetooth PC Reference Stack by Ericsson
Page 132
#define L2CA_POS_DISCONNECTED ((int16) 4)#define L2CA_POS_TIMEOUT ((int16) 5)
5.5.8.4 L2CA_QOS_…: QoS negotiation fields.L2CA_QOS_SERVICE_…: ServiceType field. (default = BEST_EFFORT)#define L2CA_QOS_SERVICE_NO_TRAFFIC ((uint8) 0x00)#define L2CA_QOS_SERVICE_BEST_EFFORT ((uint8) 0x01)#define L2CA_QOS_SERVICE_GUARANTEED ((uint8) 0x02)TokenRate field. (default = NO_RATE)#define L2CA_QOS_NO_RATE ((uint32) 0x00000000)#define L2CA_QOS_MAX_RATE ((uint32) 0xFFFFFFFF)TokenBucketSize field. (default = NO_BUCKET)#define L2CA_QOS_NO_BUCKET ((uint32) 0x00000000)#define L2CA_QOS_MAX_BUCKET ((uint32) 0xFFFFFFFF)L2CA_QOS_PEAK_…: PeakBandWidth field. (default = UNKNOWN)#define L2CA_QOS_PEAK_UNKNOWN ((uint32) 0x00000000)L2CA_QOS_LATENCY_…: Latency field. (default = DONT_CARE)#define L2CA_QOS_LATENCY_DONT_CARE ((uint32) 0xFFFFFFFF)L2CA_QOS_DELAY_VAR_…: DelayVariation field. (default = DONT_CARE)#define L2CA_QOS_DELAY_VAR_DONT_CARE ((uint32) 0x00000000)
5.5.8.5 L2CA_CONFIG_…: Default values for CID configuration.#define L2CA_CONFIG_DEFAULT_MTU ((uint16) 672)#define L2CA_CONFIG_DEFAULT_FLOW (NULL)#define L2CA_CONFIG_DEFAULT_FLUSH_TIME ((uint16) 0xFFFF)
Bluetooth PC Reference Stack by Ericsson
Page 133
5.6 Host Controller Interface (HCI)
HC I Drive r
RFC O M M
L2C AP
SDP
OS A
daptation
Se ria l Line In te rfa c e
A p p lic a t io n
ApplicationProgrammersInterface
VOSInterface
SILInterface
SC M
5.6.1 General DescriptionTo understand the HCI interface one must know the context in which it will be used. The HCI isthe layer between the other Bluetooth components (SCM, L2CA, SDP and RFCOMM) and theLink Manager (LM). HCI provides these components with a generic interface towards the linkmanager. This is shown in the following picture:
LM
HCI
Radio
SCM
DBM
SDPCOM
L2CAP
TC
Application
Figure 5-51 - Context of HCI
The interface of HCI towards upper components is described in this chapter.
Bluetooth PC Reference Stack by Ericsson
Page 134
5.6.2 Start Commands
5.6.2.1 OverviewThe Common interface commands allows the host to register and start the Host ControllerInterface in the BT OSI SCS.
5.6.2.1.1 Function Interface
Name Parameters Function Description
HCI_CmdRegister HCI_TMessageGroup Register a customer of the HCI component in order to receive thespecified indications
HCI_ReqStart HCI_TSeqNr This function is called to start HCI. Before HCI receives thismessage it will not accept any other messages accept theHCI_CmdRegister. All other messages will be freed and thereforenot processed.
Table 5-81- Functions of Common Interface
5.6.2.1.2 Message Interface
Name Contents Message Description
HCI_START_CNF MSG_TControlHdr This message is sent to the task that called the HCI_ReqStart functionto confirm that HCI has started processing incoming messages.
Table 5-82- Messages of Common Interface
5.6.2.1.3 Data elements
Name Size Value Description
HCI_TMessageGroup uint8 HCI_CONNECT_GROUP
HCI_DATA_GROUP
Specifies the group for which indications toregister
HCI_TSeqNr uint16 - Sequence number. The reply of a message mustalways have the same sequence number as thereceived message. This can be used to matchmultiple outstanding messages (Req/Ind) with theresponses (Cnf/Rsp).
MSG_TControlHdr - - Control Header used in each message
Table 5-83- Data Elements of Common Interface
Defines
Name Value Description
HCI_CONNECT_GROUP 0x00 Connection Group
HCI_DATA_GROUP 0x01 Data Group
Table 5-84 - Defines of Common Interface
5.6.2.2 Communication Procedures
Bluetooth PC Reference Stack by Ericsson
Page 135
Host HCI
HCI_CmdRegistertMessageGroup = HCI_CONNECT_GROUP
HCI_START_CNF
HCI_CmdRegistertMessageGroup = HCI_DATA_GROUP
(tSeqNr = 30)
HCI_ReqStart(tSeqNr = 30)
Figure 5-52 - HCI Initialisation
This MSC gives the start-up for HCI. First HCI_ReqStart is called and after the HCI_START_CNFis received the host register itself to the HCI_CONNECT_GROUP and HCI_DATA_GROUP withHCI_CmdRegister
Bluetooth PC Reference Stack by Ericsson
Page 136
5.6.3 Link Control Commands
5.6.3.1 OverviewThe Link Control Commands allow the host controller to control connections to other Bluetoothdevices. When the Link Control Commands are used, the Link Manager (LM) controls how theBluetooth piconet and scatternets are established and maintained. These commands instruct theLM to create and modify link layer connections with Bluetooth remote devices, perform Inquiriesof other Bluetooth devices in range, and other Link Manager Protocol commands.
5.6.3.1.1 Function Interface
Name Parameters Function Description
HCI_CmdExitPeriodicInquiry - Stops the periodic inquiry mode. A pending inquirywill be stopped.
HCI_CmdInquiryCancel - This command is issued when the host wants tocancel an ongoing inquiry procedure. Can not beused during a PeriodicInquiry.
HCI_ReqAddSco HCI_TSeqNr
BT_THandle
HCI_TPacketType
This command will cause the link manager to createa SCO connection using the ACL connectionspecified by the BT_THandle command parameter.
HCI_ReqAuthentication HCI_TSeqNr
BT_THandle
Establish authentication between the devicesassociated with the specified connection handle.This handle must be a handle for an ACLconnection.
HCI_ReqChangeEncryption HCI_TSeqNr
BT_THandle
HCI_TEncryptionEnable
Enables or disables the link level encryptionbetween the devices associated with the specifiedconnection handle. This handle must be a handlefor an ACL connection.
HCI_ReqChangeKey HCI_TSeqNr
BT_THandle
Force the devices, associated with the specifiedconnection handle, to generate a new link key. Thishandle must be a handle for an ACL connection.
HCI_ReqChangePacketType HCI_TSeqNr
BT_THandle
HCI_TPacketType
Changes the packet types that can be used for aconnection that is currently established. This allowscurrent connections to be dynamically modified tosupport different types of user data. The handle canbe a handle for an ACL or SCO connection.
HCI_ReqConnect HCI_TSeqNr
BT_TAddress
HCI_TPacketType
HCI_TPageScanRepMode
HCI_TPageScanMode
HCI_TClockOffset
HCI_TAcceptRoleSwitch
This function has to be used to establish anasynchronous (ACL) connection between twoBluetooth devices.
HCI_ReqDisconnect HCI_TSeqNr
BT_THandle
HCI_TErrorCode
This function has to be used to destroy anasynchronous (ACL) or synchronous (SCO)connection between to Bluetooth devices. The errorcode must contain the reason of the disconnection.
Bluetooth PC Reference Stack by Ericsson
Page 137
HCI_ReqInquiry HCI_TSeqNr
HCI_TLap
HCI_TInquiryLength
HCI_TNrOfResponses
This function is used to discover other nearbyBluetooth radios.
See for Error! Reference source not found.detailed information how to use this function.
HCI_ReqMasterKey HCI_TSeqNr
HCI_TKeyFlag
Force the device that is master of the piconet to usethe temporary link key of the master device or thesemi-permanent link keys. The temporary link key isused for encryption of broadcast messages within apiconet and the semi-permanent link keys are usedfor private encrypted point-to-point communication.
HCI_ReqPeriodicInquiry HCI_TSeqNr
HCI_TInquiryPeriod
HCI_TInquiryPeriod
HCI_TLap
HCI_TInquiryLength
HCI_TNrOfResponses
This function is used to perform an automaticInquiry.
See Figure 5-56 for detailed information how to usethis function.
HCI_ReqReadClockOffset HCI_TSeqNr
BT_THandle
Read the clock offset of the remote deviceassociated with the specified connection handle.
This command could be used to facilitate handoffs ofBluetooth devices from one device to another.
HCI_ReqReadRemoteFeatures HCI_TSeqNr
BT_THandle
Requests a list of the supported features of a remotedevice.
HCI_ReqReadRemoteVersion HCI_TSeqNr
BT_THandle
Obtain the values of the version information for theremote device.
HCI_RspConnect MSG_TMsg
HCI_TErrorCode
HCI_TRole
This function has to be used to give a response onthe HCI_CONNECT_IND message. If the tRoleparameter indicates a different role than the devicecurrently is in then a role switch will be performed (orat least tried). The tErrorCode parameter indicateswhether the connection set-up is rejected or not. If itis HCI_NO_ERROR then the connection set-up isaccepted.
HCI_RspLinkKey MSG_TMsg
HCI_TLinkKey
HCI_ErrorCode
This function has to be used by the HCI client toreturn a link key. This function has to be called afterthe HCI_TLinkKeyInd message has been received.The tErrorCode may indicate a possible failurereason.
HCI_RspPincode MSG_TMsg
HCI_TPinCode
HCI_TPinCodeLength
HCI_TErrorCode
This function has to be used by the HCI client toreturn a PIN code. This function has to be calledafter the HCI_TpincodeInd message has beenreceived. If the tErrorCode parameter is not equal toHCI_NO_ERROR then the host can not supply HCIwith a PIN code for the specified Bluetooth device.
Table 5-85 - Functions of Link Control Commands
Bluetooth PC Reference Stack by Ericsson
Page 138
5.6.3.1.2 Message Interface
Name Contents Message Description
HCI_ADD_SCO_CNF MSG_TControlHdr
BT_TAddress
HCI_TLinkType
BT_THandle
This message acknowledgesthe request to set-up an SCOconnection to the specifiedBluetooth device. The tHandlecan be used in subsequentmessages to identify thisconnection.
HCI_ADD_SCO_CNF_NEG MSG_TControlHdr
BT_TAddress
This message rejects therequest to set-up an SCOconnection to the specifiedBluetooth device. The resultfield of the header indicates whythe SCO connection could notbe established.
HCI_AUTHENTICATION_CNF MSG_TControlHdr
BT_THandle
Indicate that authentication isenabled for the connectionbetween two devices.
HCI_AUTHENTICATION_CNF_NEG MSG_TControlHdr
BT_THandle
Indicate that authentication cannot be enabled for theconnection between twodevices.
HCI_CHANGE_ENCRYPTION_CNF MSG_TControlHdr
BT_THandle
Indicates that encryption ischanged for the connectionbetween two devices.
HCI_CHANGE_ENCRYPTION_CNF_NEG MSG_TControlHdr
BT_THandle
HCI_TEncryptionEnable
Indicate that encryption can notbe change for the connectionbetween two devices.EncryptionEnable indicate thecurrent encryption-mode for thespecified ACL connectionhandle.
HCI_CHANGE_ENCRYPTION_COMPLETE_EVT MSG_TControlHdr
BT_THandle
HCI_TEncryptionEnable
This message will be send tothe process registered withHCI_CONNECT_GROUP. Itindicate that the encryption for aspecified connection handle haschanged.
HCI_CHANGE_PACKET_TYPE_CNF MSG_TControlHdr
BT_THandle
HCI_ TPacketType
Indicate that the change ofpacket type succeeded.
HCI_CHANGE_PACKET_TYPE_CNF_NEG MSG_TControlHdr
BT_THandle
Indicate that the change ofpacket type failed.
HCI_CONNECT_CNF MSG_TControlHdr
BT_THandle
BT_TAddress
HCI_TLinkType
HCI_TEncryptionMode
This message acknowledgesthe requested connection set-up. It will be sent to the processin which the HCI_ReqConnectfunction has been called.
HCI_CONNECT_CNF_NEG MSG_TControlHdr
BT_TAddress
This message tells the processthat called the functionHCI_ReqConnect that theconnection set-up has failed tothe specified Bluetooth address.The result field of the messageheader indicates the reason offailure.
Bluetooth PC Reference Stack by Ericsson
Page 139
HCI_CONNECT_COMPLETE_EVT MSG_TControlHdr
BT_TAddress
BT_THandle
HCI_TLinkType
HCI_TEncryptionMode
This message indicates to thereceiving party forming theconnection that a newconnection has beenestablished. This message willbe sent to the process in whichthe HCI_RspConnect functionhas been called.
HCI_CONNECT_IND MSG_TControlHdr
BT_TAddress
HCI_TCod
HCI_TLinkType
This message will be send tothe registered customer in caseanother Bluetooth device tries toconnect.
HCI_DISCONNECT_CNF MSG_TControlHdr
BT_THandle
This message acknowledgesthe disconnection of theconnection. This message willbe send to the process thatcalled the HCI_ReqDisconnectfunction.
HCI_DISCONNECT_CNF_NEG MSG_TControlHdr
BT_THandle
This message tells the host thatthe disconnection failed. Thismessage will be sent to theprocess that called theHCI_ReqDisconnect function.The result field of the messageheader indicates the reason offailure.
HCI_DISCONNECT_COMPLETE_EVT MSG_TControlHdr
BT_THandle
This message will be sent to theprocess that called theHCI_ReqDisconnect function.The result field of the messageheader indicates the reason whythe other end terminated theconnection. After receiving theHCI_DISCONNECT_COMPLETE_EVT message the specifiedBluetooth connection is closeddown.
HCI_INQUIRY_CNF MSG_TControlHdr
HCI_TNrOfResponses
This message is sent when theinquiry procedure is finished.This can be when the procedurehas timed out or when themaximum number of responseshas been received from the LM.The tNrOfResponses indicateshow many devices respondedduring the inquiry procedure.
HCI_INQUIRY_COMPLETE_EVT MSG_TControlHdr Indicates that an inquiry,initiated by aHCI_ReqPeriodicInquiry, hasfinished. This message will besent to process that calledHCI_ReqPeriodicInquiry.
HCI_INQUIRY_RESULT_EVT MSG_TControlHdr
BT_TAddress
HCI_TPageScanRepMode
HCI_TPageScanPeriodMode
HCI_TPageScanMode
HCI_TCod
HCI_TClockOffset
This message is sent betweenthe start and end of the inquiryprocedure to the process thatcalled HCI_ReqInquiry orHCI_ReqPeriodicINquiry. It issent for every Bluetooth devicethat responded to the inquirymessage and that met all theinquiry criteria for theGeneral/Unlimited Access Codeand HCI_ReqFilter (see5.6.7.2.1) functions.
Bluetooth PC Reference Stack by Ericsson
Page 140
Table 5-86 - Messages of Link Control Commands
Bluetooth PC Reference Stack by Ericsson
Page 141
5.6.3.1.3 Data elements
Name Size Value Description
BT_Taddress struct
{ uint8 ucByte0
uint8 ucByte1
uint8 ucByte2
uint8 ucByte3
uint8 ucByte4
uint8 ucByte5
}
- Bluetooth Device Address(BD_ADDR)
BT_THandle uint16 Only 12 bits LSB are meaningful Connection handle for aACL or SCO connection
HCI_TAcceptRoleSwitch uint8 HCI_NOT_ACCEPT_ROLE_SWITCH
HCI_ACCEPT_ROLE_SWITCH
Indicate if a role switch msutbe accepted or not.
HCI_TClockOffset uint16 bit 15 -> Clock offset valid flag
0 -> Invalid
1 -> Valid
bit14,0 ->bit 16..2 of CLKslave-CLKmaster
Difference between the ownclock and clock of theremote device
HCI_TCod struct
{ ucA[HCI_SIZE_OF_COD]
}
See [1] – BluetoothAssigned Numbers
Specifies the Class ofDevice, used to indicate thecapabilities of the localdevice to other devices
HCI_TEncryptionEnable uint8 HCI_ENCRYPTION_DISABLE
HCI_ENCRYPTION_ENABLE
Specifies if encryption mustbe on or off.
HCI_TEncryptionMode uint8 HCI_ENCRYPTION_OFF
HCI_ENCRYPTION_POINT
_TO_POINT
HCI_ENCRYPTION_POINT
_TO_MULTIPOINT
Specifies the EncryptionMode. The Encryption Modecontrols if the Bluetoothradio will require encryptionfor each connection toanother device.
HCI_TErrorCode uint16 HCI_OE_USER_ENDED_
CONNECTION
HCI_OE_LOW_RECOURCES
HCI_OE_POWER_OFF
Indicates reason to end aconnection or to decline aconnection.
(See Table 5-112)
HCI_TInquiryLength uint8 - Maximum amount of timespecified before the Inquiryis halted.
Time = N * 1.28 Sec
Range : 0x01 – 0x30 (1.28Sec – 61.44 Sec)
HCI_TKeyFlag uint8 HCI_SEMI_PERMANENT_KEY
HCI_TEMPORARY_KEY
HCI_TLap struct
{ ucA[HCI_SIZEOF_LAP]
}
- This is the Lower AddressPart (LAP) from which theInquiry access code isderived when the inquiryprocedure is made.
Bluetooth PC Reference Stack by Ericsson
Page 142
HCI_TLinkKey struct
{ ucA[HCI_SIZE_OF_LINKKEY]
}
- Link Key for the associatedBD_ADDR
HCI_TLinkType uint8 HCI_ACL
HCI_SCO
Indicates the Link Type of aconnection: ACL or SCO.
HCI_TLmpFeatures struct
{ ucA[HCI_SIZE_OF_LMP_FEATURES]
}
See [1] – Link ManagerProtocol
The features that the LMsupports
HCI_TLmpSubVersion uint16 See [1] – Link ManagerProtocol
The Sub Version is theresponsibility of thecompany.
HCI_TLmpVersion uint8 See [1] – BluetoothAssigned Numbers
Bluetooth Link ManagerProtocol specificationversion.
HCI_TManufacturerName uint16 See [1] – BluetoothAssigned Numbers
Component ID for eachcompany that makes aunique implementation ofthe Link Manager.
HCI_TNrOfResponses uint8 - Maximum number ofresponses from the Inquiry.
0x00 – Default: UnlimitedNumber of Responses
0xXX – Maximum numberof responses (0x01-0xFF)
HCI_TPacketType uint16 HCI_DM1
HCI_DH1
HCI_AUX1
HCI_DM3
HCI_DH3
HCI_DM5
HCI_DH5
HCI_HV1
HCI_HV2
HCI_HV3
HCI_DV
Indicates which packet typesthe LM may use for theconnection.
HCI_TPageScanMode uint8 HCI_MANDATORY_PAGE_
SCAN_MODE
HCI_OPTIONAL_PAGE_
SCAN_MODE_I
HCI_OPTIONAL_PAGE_
SCAN_MODE_II
HCI_OPTIONAL_PAGE_
SCAN_MODE_III
Specifies, also withtPageScanRepMode, thepage scan modes that aresupported.
Values:
HCI_TPageScanPeriodeMode uint8 HCI_P0
HCI_P1
HCI_P2
Bluetooth PC Reference Stack by Ericsson
Page 143
HCI_TPageScanRepMode uint8 HCI_R0
HCI_R1
HCI_R2
Specifies, also withtPageScanMode, the pagescan modes that aresupported.
HCI_TPincode struct
{ ucA[HCI_SIZE_OF_PINCODE]
}
- PIN code for the device thatis to be connected. The Hostshould insure that strongPIN Codes are used. PINCodes can be up to amaximum of 128 bits. TheMSB of the PIN codeoccupies byte zero.
HCI_TPincodeLength uint8 Range: 0x01 – 0x10 Specifies length, in bytes, ofthe PIN code
HCI_TRole uint8 HCI_MASTER
HCI_SLAVE
Allows the Host to specify ifthe LM must perform aMaster-Slave switch andbecome Master for thisconnection.
ucA uint8 - Array value
Table 5-87 - Data Elements of Link Control Commands
Note: In the struct, field ucA[0] is the MSB.
Bluetooth PC Reference Stack by Ericsson
Page 144
5.6.3.1.4 Defines used by parameters and messages
Name Value Description
HCI_SCO 0x00 SCO Link Type
HCI_ACL 0x01 ACL Link Type
HCI_MASTER 0x00 Become master for this connection
HCI_SLAVE 0x01 Remain Slave for this connection.
HCI_MANDATORY_PAGE_SCAN_MODE 0x00 Mandatory page scan mode (Default)
HCI_OPTIONAL_PAGE_SCAN_MODE_I 0x01 Optional Page Scan Mode I
HCI_OPTIONAL_PAGE_SCAN_MODE_II 0x02 Optional Page Scan Mode II
HCI_OPTIONAL_PAGE_SCAN_MODE_III 0x03 Optional Page Scan Mode III
HCI_R0 0x00 R0 (Page Scan Repetition Mode)
HCI_R1 0x01 R1 (Page Scan Repetition Mode)
HCI_R2 0x02 R2 (Page Scan Repetition Mode)
HCI_P0 0x00 P0 (Page Scan Period Mode)
HCI_P1 0x01 P1 (Page Scan Period Mode)
HCI_P2 0x02 P2 (Page Scan Period Mode)
HCI_DM1 0x0008 DM1 (Packet Type for both ACL and SCO)
HCI_DH1 0x0010 DH1 (Packet Type for ACL connection)
HCI_DM3 0x0400 DM3 (Packet Type for ACL connection)
HCI_DH3 0x0800 DH3 (Packet Type for ACL connection)
HCI_DM5 0x4000 DM5 (Packet Type for ACL connection)
HCI_DH5 0x8000 DH5 (Packet Type for ACL connection)
HCI_HV1 0x0020 HV1 (Packet Type for SCO connection)
HCI_HV2 0x0040 HV2 (Packet Type for SCO connection)
HCI_HV3 0x0080 HV3 (Packet Type for SCO connection)
HCI_ENCRYPTION_DISABLE 0 Turn Link Level Encryption Off
HCI_ENCRYPTION_ENABLE 1 Turn Link Level Encryption On
HCI_ENCRYPTION_OFF 0 Encryption disabled
HCI_ENCRYPTION_POINT_TO_POINT 1 Encryption only for point-to-point packets
HCI_ENCRYPTION_POINT_TO_MULTIPOINT 2 Encryption for both point to point and broadcastpackets
HCI_SEMI_PERMANENT_KEY 0 Use Semi-permanent Link Keys
HCI_TEMPORARY_KEY 1 Use Temporary Link Key
HCI_NOT_ACCEPT_ROLE_SWITCH 0 Do not accept a role switch
HCI_ACCEPT_ROLE_SWITCH 1 Accept a role switch
HCI_SIZE_OF_COD 3 Size of COD
HCI_SIZE_OF_LAP 3 Size of LAP
HCI_SIZE_OF_LINKKEY 16 Size of Link Key
Bluetooth PC Reference Stack by Ericsson
Page 145
Name Value Description
HCI_SIZE_OF_LMP_FEATURES 8 Size of LMP Features
HCI_SIZE_OF_PINCODE 16 Size of Pin code
Table 5-88 - Defines of Link Control Commands
5.6.4 Interface Specific Items
5.6.4.1 ReqAddScoThis command causes the local Bluetooth radio to create an SCO connection. The Link Managerwill determine how the new connection is established. This established connection is determinedby the current state of the device, its piconet, and the state of the device to be connected. TheHCI_TPacketType command parameter specifies which packet types the Link Manager shoulduse for the connection. The Link Manager must only use the packet type(s) specified by theHCI_TPacketType command parameter. Multiple packet types may be specified for theHCI_TPacketType parameter by performing a bitwise OR operation of the different packet types.The Link Manager may choose which packet type to be used from the list of acceptable packettypes. A Connection handle for this connection is returned in the HCI_TAddScoCnf message.Note: The connection handle for the SCO connection should be disconnected before theconnection handle for the ACL connection.
5.6.4.2 Communication Procedures
HOST:1 HOST:2HCI:1 HCI:2
HCI_ReqConnecttAddress, tPacketType
HCI_LINK_KEY_IND
tAddress
HCI_CONNECT_IND
tAddress, tCoD, tLinkType=ACL
HCI_RspPinCodetSeqNr, tAddress,
tPinCode, tPinCodeLength,tErrorCode = HCI_NO_ERROR
HCI_RspLinkKeytSeqNr, tAddress, tLinkKey,tErrorCode = HCI_KEY_MISSING
HCI_PINCODE_IND
tAddress
HCI_RspPinCodetSeqNr, tAddress,tPinCode, tPinCodeLength,tErrorCode = HCI_NO_ERROR
HCI_LINK_KEY_NOTIFY_EVT
tAddress, tLinkKey
HCI_PINCODE_IND
tAddress
HCI_LINK_KEY_NOTIFY_EVT
tAddress, tLinkKey
HCI_CONNECT_COMPLETE_EVT
tSeqNr, tAddress, tHandle,tLinkType,tEncryptionMode
HCI_CONNECT_COMPLETE_EVT
tSeqNr, tAddress, tHandle,tLinkType,tEncryptionMode
Figure 5-52 - ACL Connection with pairing
Bluetooth PC Reference Stack by Ericsson
Page 146
With pairing the two Bluetooth devices don’t have a common link key. After theHCI_CONNECT_COMPLETE_EVT the Host can store the Link Key with HCI_ReqWriteLinkKey.
HOST:1 HOST:2HCI:1 HCI:2
HCI_ReqConnecttAddress, tPacketType
HCI_LINK_KEY_IND
tAddress
HCI_CONNECT_IND
tAddress, tCoD, tLinkType=ACL
HCI_RspLinkKeytSeqNr, tAddress, tLinkKey,
tErrorCode = HCI_NO_ERROR
HCI_RspLinkKeytSeqNr, tAddress, tLinkKey,tErrorCode = HCI_NO_ERROR
HCI_LINK_KEY_IND
tAddress
HCI_CONNECT_COMPLETE_EVT
tSeqNr, tAddress, tHandle,tLinkType,tEncryptionMode
HCI_CONNECT_COMPLETE_EVT
tSeqNr, tAddress, tHandle,tLinkType,tEncryptionMode
Figure 5-53 - ACL Connection with Authentication
With Authentication the two Bluetooth devices has already set-up a connection with each otherbefore and the host still has the correct link key. When the link key of the previous connection wasstored (with HCI_ReqWriteLinkKey) this link key would be used and the HCI_LINK_KEY_INDdidn’t occur.
Host HCI
HCI_ReqInquirytSeqNr = 34, tInquiryLength = 5,tInquiryPeriod = 7, tCod =0x9E8B33
tSeqNr = 34, NrOfResponses = 2
HCI_INQUIRY_RESULT_EVT
HCI_INQUIRY_RESULT_EVT
HCI_INQUIRY_CNF
BT_TAddress = AA BB CC DD EE FF,HCI_TPageScanRepMode,
HCI_TPageScanPeriodMode,HCI_TPageScanMode,
HCI_TCod,HCI_TClockOffset
BT_TAddress = 0x11 22 33 44 55 66,HCI_TPageScanRepMode,
HCI_TPageScanPeriodMode,HCI_TPageScanMode,
HCI_TCod,HCI_TClockOffset
Figure 5-54 - Inquiry
Bluetooth PC Reference Stack by Ericsson
Page 147
Host HCI
HCI_ReqPeriodicInquirytSeqNr = 34, tInquiryLength = 5,tInquiryPeriod = 7
HCI_PERIODIC_INQUIRY_CNF
HCI_CmdExitPeriodicInquiry
tSeqNr = 34, NrOfResponses = 2
tSeqNr = 34
HCI_INQUIRY_RESULT_EVT
HCI_INQUIRY_RESULT_EVT
HCI_INQUIRY_COMPLETE_EVT
BT_TAddress,HCI_TPageScanRepMode,HCI_TPageScanPeriodMode,HCI_TPageScanMode,HCI_TCod,HCI_TClockOffset
BT_TAddress,HCI_TPageScanRepMode,
HCI_TPageScanPeriodMode,HCI_TPageScanMode,
HCI_TCod,HCI_TClockOffset
tSeqNr = 34, tNrOfResponses = 1
HCI_INQUIRY_RESULT_EVT
HCI_INQUIRY_COMPLETE_EVT
BT_TAddress,HCI_TPageScanRepMode,
HCI_TPageScanPeriodMode,HCI_TPageScanMode,
HCI_TCod,HCI_TClockOffset
InquiryLength
InquiryPeriod
InquiryLength InquiryPeriod
Figure 5-56 - Periodic Inquiry
HCI_ReqInquiry:The HCI_TLap parameter contains the LAP from which the inquiry access code will be derivedwhen the inquiry is made.The HCI_TInquiryLength specifies the total duration of the Inquiry. HCI_TNrOfResponsesspecifies the number of responses that must be received before the inquiry is halted. AHCI_TNrOfResponses of zero indicates unlimited responses.
HCI_ReqPeriodicInquiry:The first HCI_TInquiryPeriod of HCI_ReqPeriodicInquiry is the maximum period length and thesecond HCI_TInquiryPeriod is the minimum period length between two consecutive inquiries fromthe beginning of an inquiry until the start of a next inquiry. The HCI_TLap parameter contains theLAP from which the inquiry access code will be derived when the inquiry is made.
Bluetooth PC Reference Stack by Ericsson
Page 148
The HCI_TInquiryLength of the HCI_ReqPeriodicInquiry specifies the total duration of an Inquiry.HCI_TNrOfResponses specifies the number of responses that must be received before theinquiry is halted. A HCI_TNrOfResponses of zero indicates unlimited responses.Note that Max Period > Min Period > InquiryLength!The exact InquiryPeriod lies between the MinInquiryPeriod and the MaxPeriodInquiry. Note thatthe MaxInquiryPeriod must be greater than the MinInquiryPeriod and that the MinInquiryPeriodmust be greater than the InquiryLength. In conjunction with this the ranges for these parametersare as follow:InquiryLength 0x01 – 0x30 (1.28s – 61.44s)MinInquiryPeriod 0x0002 – 0xFFFE (2.56s – 83883.52s)MaxInquiryPeriod 0x0003 – 0xFFFF (3,84s – 83884.8s)
Bluetooth PC Reference Stack by Ericsson
Page 149
5.6.5 Link Policy Commands
5.6.5.1 OverviewThe Link Policy Commands provide methods for the host to effect how the LM manages thepiconet. When Link Policy Commands are used the LM still maintains control how Bluetoothpiconets and scatternets are established and mainainted depending on the adjustable policyparameters. These policy commands modify the behaviour of the LM that can result in changes tothe link layer connections with Bluetooth remote devices.Note: Only one ACL connection can exits between two Bluetooth devices, and therefore there canonly be one ACL HCI Connection Handle for each physical link layer connection. The BluetoothHost Controller provides policy adjustment mechanisms to provide support for a number ofdifferent policies.
5.6.5.2 Layout
5.6.5.2.1 Function Interface
Name Parameters Description
HCI_ReqQosSetup HCI_TSeqNr
BT_THandle
HCI_TQosFlags
HCI_TServiceType
HCI_TTokenRate
HCI_TPeakBandwidth
HCI_TLatency
HCI_TDelayVariation
This command is used to specify Quality of Service(Qos) parameters for a connection handle.
Table 5-89 - Functions of Link Policy Commands
5.6.5.2.2 Message Interface
Name Contents Description
HCI_QOS_SETUP_CNF MSG_TControlHdr
BT_THandle
Indicate the completion of the Qos set-up
HCI_QOS_SETUP_CNF_NEG MSG_TControlHdr
BT_THandle
HCI_TQosFlags
HCI_TServiceType
HCI_TTokenRate
HCI_TPeakBandwidth
HCI_TLatency
HCI_TDelayVariation
Indicate that the Qos set-up failed. This signal containsQos parameters corresponding to the current Qualityof Service. These values are not valid if a connectionhandle, given with HCI_ReqQosSetup, does notcorrespond to an existing ACL connection.
Bluetooth PC Reference Stack by Ericsson
Page 150
HCI_QOS_SETUP_EVT MSG_TControlHdr
BT_THandle
HCI_TQosFlags
HCI_TServiceType
HCI_TTokenRate
HCI_TPeakBandwidth
HCI_TLatency
HCI_TDelayVariation
Indicate that a Qos set-up has occurred.
HCI_QOS_VIOLATION_EVT MSG_TControlHdr
BT_Handle
Indicate that the LM is unable to provide the QOS thathas earlier been requested by the HCI_ReqQosSetup.
Table 5-90 - Messages of Link Policy Commands
5.6.5.2.3 Data elements
Name Size Value Description
HCI_TDelayVariation struct
{ ucA[HCI_SIZE_OF_DELAY_VARIATION]
}
- Available Delay Variation inmicroseconds
HCI_TLatency struct
{ ucA[HCI_OF_SIZE_LATENCY]
}
- Available Latency inmicroseconds
HCI_TPeakBandwidth struct
{ ucA[HCI_SIZE_OF_PEAK_BANDWIDTH]
}
- Available Peak Bandwidth inbytes per second
HCI_TQosFlags uint8 - Reserved for future use
HCI_TServiceType uint8 HCI_NO_TRAFFIC
HCI_BEST_EFFORT
HCI_GUARANTEED
Required Service level
HCI_TTokenRate struct
{ ucA[HCI_SIZE_OF_TOKENRATE]
}
- Available Token Rate in bytesper second
Table 5-91 - Data Elements of Link Policy Commands
Note: In the struct, field ucA[0] is the MSB.
Bluetooth PC Reference Stack by Ericsson
Page 151
5.6.5.3 Defines
Name Value Description
HCI_NO_TRAFFIC 0 No data is send so the other parameters may be ignored.
HCI_BEST_EFFORT 1 The remote device treats the other parameters as hints.
HCI_GUARANTEED 2 The remote device uses the exact values of the otherparameters given with the req.
HCI_SIZE_OF_DELAY_VARIATION 4 Size of Delay Variation
HCI_SIZE_OF_LATENCY 4 Size of Latency
HCI_SIZE_OF_PEAK_BANDWIDTH 4 Size of Peak bandwidth
HCI_SIZE_OF_TOKENRATE 4 Size of Token rate
Table 5-92 - Defines of Link Policy Commands
5.6.6 Communication Procedures
AIR
HOST:1 HOST:2HCI:1 HCI:2
HCI_ReqQosSetuptSeqNr, tHandle, tQosFlags,tServiceType, tTokenRate,tPeakBandWidth, tLatency,tDelayVariation
HCI_QOS_SETUP_CNF
tSeqNr
HCI_QOS_SETUP_EVT
tHandle, tQosFlags, tServiceType,tTokenRate, tPeakBandWidth, tLatency,tDelayVariation
HCI_ReqQosSetuptSeqNr, tHandle, tQosFlags,tServiceType, tTokenRate,tPeakBandWidth, tLatency,tDelayVariation
HCI_QOS_SETUP_CNF_NEG
tSeqNr, tHandle, tQosFlags,tServiceType, tTokenRate,tPeakBandWidth, tLatency,
tDelayVariation
Figure 5-56 – Qos Setup
When a Qos set-up is successful, a Cnf will be send on the initiating side and an Evt on theremote side. The Cnf only indicate that the Qos set-up is successful and don’t return the Qosparameters.If Qos set-up failed only a CnfNeg will be send on the initiating side. The Qos parametersreturned with the CnfNeg indicate the current Qos.
Bluetooth PC Reference Stack by Ericsson
Page 152
5.6.7 Host Controller & Baseband Commands
5.6.7.1 OverviewThe Host Controller and Baseband Commands are used to change the way of operation of theLM in conjunction with a connection set-up such as voice-settings, authentication mode andencryption mode.
5.6.7.2 Layout
5.6.7.2.1 Function Interface
Name Parameters Function Description
HCI_CmdReset - Resets HCI and the LM. Pending requestswill be stopped no confirms are returned.The host(s) is (are) still registered on HCI.
HCI_ReqDeleteLinkKey HCI_TSeqNr
BT_TAddress
HCI_TDeleteLinkKeyFlag
Remove one or all of the stored link key(s)In the Host Controller. TheHCI_TDeleteLinkKeyFlag indicates thatone or all the stored keys should bedeleted.If the HCI_TDeleteLinkKeyFlagindicates that all keys should be deletedthan the BT_TAddress is ignored, but maynot have the value NULL.
HCI_ReqReadAuthenticationMode HCI_TSeqNr Read the Authentication Mode parameter.
HCI_ReqReadCod HCI_TSeqNr Read the Class of Device parameter.
HCI_ReqReadConnectTimeout HCI_TSeqNr Read the connect timeout parameter.
HCI_ReqReadEncryptionMode HCI_TSeqNr Read the Encryption Mode parameter.
HCI_ReqReadInquiryScanActivity HCI_TSeqNr Read the Inquiry Scan Activity parameter.
HCI_ReqReadLinkKey HCI_TSeqNr
BT_TAddress
HCI_TReadLinkKeyFlag
Read one or all link keys stored in theHost Controller. TheHCI_TReadLinkKeyFlag indicates that oneor all stored link keys should be returned.If the HCI_TReadLinkKeyFlag indicatesthat all keys should be read, than theBT_TAddress must be ignored, but maynot have the value NULL.
Each stored link keys is returned by aHCI_READ_LINK_KEY_RESULT_EVTmessage. When theHCI_ReqReadLinkKey is finished aHCI_READ_LINK_KEY_CNF orHCI_READ_LINK_KEY_CNF_NEG isreturned.
HCI_ReqReadName HCI_TSeqNr Read the Local Name
HCI_ReqReadPageScanActivity HCI_TSeqNr Read the Page Scan Activity parameter.
HCI_ReqReadPageScanMode HCI_TSeqNr Read the Page Scan Mode.
HCI_ReqReadPageScanPeriodMode HCI_TSeqNr Read the Page Scan Period Mode.
HCI_ReqReadPageTimeout HCI_TSeqNr Read the page timeout parameter.
HCI_ReqReadPinType HCI_TSeqNr Reads the PinType. This parameterspecifies if the host supports variable PINor if the host only supports fixed PINs.
HCI_ReqReadScanEnable HCI_TSeqNr Read the scan enable parameter.
Bluetooth PC Reference Stack by Ericsson
Page 153
HCI_ReqReadScoFlowControl HCI_TSeqNr Read the Sco Flow Control parameter.
HCI_ReqReadTransmitPowerLevel HCI_TSeqNr
BT_THandle
HCI_TTransmitPowerLevelType
Read the values for the Transmit PowerLevel parameter for a specified connectionhandle
HCI_ReqReadVoiceSettings HCI_TSeqNr Reads the voice settings for the voiceconnections
HCI_ReqRemoteName HCI_TSeqNr
BT_TAddress
HCI_TPageScanPeriodMode
HCI_TPageScanMode
HCI_TClockOffset
Reads the name of a remote Bluetoothdevice. The parameters are used in casethere is no existing connection with thedevice yet to set-up a link.
HCI_ReqSetBufferSize HCI_TSeqNr
HCI_TMaxAclPacketSize
HCI_TMaxScoPacketSize
HCI_TMaxAclPackets
HCI_TMaxScoPackets
Set the Host buffer size.
HCI_ReqSetFilter HCI_TSeqNr
HCI_TFilterType
HCI_TFilterConditionType
HCI_TCod
HCI_TCod
BT_TAddress
HCI_TOnOff
Add a filter for the inquiry scan or pagescan.
Filter for page scan or inquiry scan
Condition of filter: Address, Cod or all
Class of Device
Class of Device Mask
AutoAccept
HCI_ReqSetHostFlowControl HCI_TSeqNr
HCI_TFlowControl
Set the Host Flow Control parameter.
HCI_ReqWriteAuthenticationMode HCI_TSeqNr
HCI_TAuthMode
Set the authentication mode. Thisparameter specifies whetherauthentication is required during link set-up
HCI_ReqWriteCOD HCI_TSeqNr
HCI_TCod
Writes the COD of the local device
HCI_ReqWriteConnectTimeOut HCI_TSeqNr
HCI_TInterval
Writes the connect timeout parameter
Range HCI_TInterval: 0x0001 – 0xB540
Default HCI_TInterval: 0x1FA0
HCI_ReqWriteEncryptionMode HCI_TSeqNr
HCI_TEncryptionMode
Writes the encryption mode. Encryptioncan enabled or disabled
HCI_ReqWriteLinkKey HCI_TSeqNr
BT_TAddress
HCI_TLinkKey
Writes a link key associated with a certainBluetooth device address in non-volatilememory
Bluetooth PC Reference Stack by Ericsson
Page 154
HCI_ReqWriteName HCI_TSeqNr
HCI_TName*
Changes the local name of the Bluetoothdevice. This will be reset after a reset(HCI_CmdReset) or Power-up.
Note: HCI_TName is a pointer to a stringwith a maximum of 248 bytes. If smallerthan 248 the string is terminated with aNULL character (0x00).
HCI_ReqWritePageTimeout HCI_TSeqNr
HCI_TPageTimeout
Writes the page timeout value. This is themaximum time the device will wait for aresponse on the page scan.
Range HCI_TPageTimeout: 0x0001 –0xFFFF
Default HCI_TPageTimeout: 0x2000
HCI_ReqWritePinType HCI_TSeqNr
HCI_TPinType
Write the PinType. This parameterspecifies if the host supports variable PINor if the host only supports fixed PINs. Thebluetooth hardware uses the PIN typeinformation during paring.
HCI_ReqWriteScanEnable HCI_TSeqNr
HCI_TScanEnable
Writes the scan enable setting. Thisindicates whether page and/or inquiryscan is enabled or disabled.
HCI_ReqWriteVoiceSettings HCI_TSeqNr
HCI_TInputCoding
HCI_TInputFormat
HCI_TSampleSize
HCI_TPcmBitPos
HCI_TAirCoding
Writes the voice settings:
Coding type used for the input data
Data format: 1’s, 2’s complement or sign-magnitude
Sample size: 8 bit or 16 bit
Bit positions that MSB of sample is awayfrom starting at MSB (only for Linear PCM)
Coding format on the air interface
Table 93 - Functions of host controller & baseband commands
Bluetooth PC Reference Stack by Ericsson
Page 155
5.6.7.2.2 Message Interface
Name Contents Message Description
HCI_DELETE_LINK_KEY_CNF MSG_TControlHdr
HCI_TKeysDeleted
Indicates that the link keys aredeleted and the number of deletedkeys
HCI_DELETE_LINK_KEY_CNF_NEG MSG_TControlHdr Indicates that deleting of the linkkey(s) has failed.
HCI_FILTER_CNF MSG_TControlHdr This message is used to confirm thata filter is added to the list of filters.
HCI_FILTER_CNF_NEG MSG_TControlHdr This message is used to indicatethat adding a filter has failed.
HCI_PAGE_TIMEOUT_CNF MSG_TControlHdr Indicates that the page timeoutvalue has successfully been written
HCI_PAGE_TIMEOUT_CNF_NEG MSG_TControlHdr Indicates that the page timeoutvalue has not been written
HCI_READ_PAGE_SCAN_PERIOD_MODE_CNF_NEG
MSG_TControlHdr Indicate that reading the Page ScanPeriod Mode failed.
HCI_READ_AUTHENTICATION_MODE_CNF MSG_TControlHdr
HCI_TAuthMode
Returns the authentication modeparameter
HCI_READ_AUTHENTICATION_MODE_CNF_NEG MSG_TControlHdr Indicate the reading theauthentication mode parameterfailed.
HCI_READ_COD_CNF MSG_TControlHdr
HCI_TCod
Returns the local Class of Device
HCI_READ_COD_CNF_NEG MSG_TControlHdr Indicate that reading the local Classof Device failed.
HCI_READ_CONNECT_TIMEOUT_CNF MSG_TControlHdr
HCI_TInterval
Returns the connect timeoutparameter
HCI_READ_CONNECT_TIMEOUT_CNF_NEG MSG_TControlHdr
HCI_TInterval
Indicate that reading the connecttimeout parameter failed
HCI_READ_ENCRYPTION_MODE_CNF MSG_TControlHdr
HCI_TEncryptionMode
Returns the encryption modeparameter.
HCI_READ_ENCRYPTION_MODE_CNF_NEG MSG_TControlHdr Indicate that reading the encryptionmode parameter failed.
HCI_READ_INQUIRY_SCAN_ACTIVITY_CNF MSG_TControlHdr Returns the inquiry scan interval andthe inquiry scan window parameters.
HCI_READ_INQUIRY_SCAN_ACTIVITY_CNF_NEG MSG_TControlHdr
HCI_TInterval
HCI_TInterval
Indicate that inquiry scan intervaland the inquiry scan windowparameters can not be read.
HCI_READ_LINK_KEY_CNF MSG_TControlHdr
HCI_TMaxKey
HCI_TKeysRead
This is used to indicate that thestored link keys which match thecriteria given withHCI_ReqReadLinkKey are return tothe host. HCI_TKeysRead gives thenumber of keys returned andHCI_TMaxKey gives the number ofkeys that can be stored.
Bluetooth PC Reference Stack by Ericsson
Page 156
HCI_READ_LINK_KEY_RESULT_EVT MSG_TControlHdr
BT_TAddress
HCI_TLinkKey
This event is used to return a BDAddress and the corresponding linkkey to the host
HCI_READ_NAME_CNF MSG_TControlHdr
HCI_TName
Returns the local name of the device
HCI_READ_NAME_CNF_NEG MSG_TControlHdr Indicate that reading the local namefailed.
HCI_READ_PAGE_SCAN_ACTIVITIY_CNF_NEG MSG_TControlHdr Indicate that page scan interval andthe page scan window parameterscan not be read.
HCI_READ_PAGE_SCAN_ACTIVITY_CNF MSG_TControlHdr
HCI_TInterval
HCI_TInterval
Returns the page scan interval andthe page scan window parameters.
HCI_READ_PAGE_SCAN_MODE_CNF MSG_TControlHdr
HCI_TPageScanMode
Returns the Page Scan Modeparameter.
HCI_REMOTE_NAME_CNF MSG_TControlHdr
BT_TAddress
HCI_TName
Returns the remote name of theremote bluetooth device
HCI_REMOTE_NAME_CNF_NEG MSG_TControlHdr
BT_TAddress
Indicates that the name of theremote bluetooth device could notbe read
HCI_WRITE_AUTHENTICATION_MODE_CNF MSG_TControlHdr Indicates that the Authenticationmode is successfully set
HCI_WRITE_AUTHENTICATION_MODE_CNF_NEG MSG_TControlHdr Indicates that the Authenticationmode is not set
HCI_SET_BUFFER_SIZE_CNF MSG_TControlHdr Indicate that writing the BuferSizeparamters succeeded.
HCI_SET_BUFFER_SIZE_CNF_NEG MSG_TControlHdr Indicate that writing the BufferSizeparameters failed
HCI_SET_HOST_FLOW_CONTROL_CNF MSG_TControlHdr Indicate that writing the Host FlowControl parameter succeeded.
HCI_SET_HOST_FLOW_CONTROL_CNF_NEG MSG_TControlHdr Indicate that writing the Host FlowControl parameter failed.
HCI_WRITE_AUTHENTICATION_MODE_CNF MSG_TControlHdr Indicates that the Authenticationmode is successfully been written
HCI_WRITE_AUTHENTICATION_MODE_CNF_NEG MSG_TControlHdr Indicates that the Authenticationmode is not been written
HCI_WRITE_COD_CNF MSG_TControlHdr Indicates that the COD parameterhas been written
HCI_WRITE_COD_CNF_NEG MSG_TControlHdr Indicates that the COD parameterhas not been written
HCI_WRITE_CONNECT_TIMEOUT_CNF MSG_TControlHdr Indicates that the connect timeoutparameter has successfully beenwritten
Bluetooth PC Reference Stack by Ericsson
Page 157
HCI_WRITE_CONNECT_TIMEOUT_CNF_NEG MSG_TControlHdr Indicates that the connect timeoutparameter has not been written
HCI_WRITE_ENCRYPTION_MODE_CNF MSG_TControlHdr Indicates that the encryption modeparameter has successfully beenwritten
HCI_WRITE_ENCRYPTION_MODE_CNF_NEG MSG_TControlHdr Indicates that the encryption modeparameter has not been written
HCI_WRITE_LINK_KEY_CNF MSG_TControlHdr Indicates that the link key has beenwritten
HCI_WRITE_LINK_KEY_CNF_NEG MSG_TControlHdr Indicates that the link key has notbeen written
HCI_WRITE_NAME_CNF MSG_TControlHdr Indicate that the local name hasbeen written
HCI_WRITE_NAME_CNF_NEG MSG_TControlHdr Indicate that the local name has notbeen written
HCI_WRITE_PIN_TYPE_CNF MSG_TControlHdr Indicate that the pin type hassuccessfully been written
HCI_WRITE_PIN_TYPE_CNF_NEG MSG_TControlHdr Indicate that writing of the pin typefailed
HCI_WRITE_SCAN_ENABLE_CNF MSG_TControlHdr Indicates that the scan enablesettings has successfully beenwritten
HCI_WRITE_SCAN_ENABLE_CNF_NEG MSG_TControlHdr Indicates that scan enble settingshas not been written
HCI_WRITE_VOICE_SETTINGS_CNF MSG_TControlHdr Indicates that the requested voicesettings have been writtensuccessfully
HCI_WRITE_VOICE_SETTINGS_CNF_NEG MSG_TControlHdr Indicates the write voice settingshave not been written
Table 5-94 - Messages of HOST CONTROLLER & BASEBAND COMMANDS
Bluetooth PC Reference Stack by Ericsson
Page 158
5.6.7.2.3 Data elements
Name Size Value Description
BT_TAddress struct
{ uint8 ucByte0
uint8 ucByte1
uint8 ucByte2
uint8 ucByte3
uint8 ucByte4
uint8 ucByte5
}
- Array of bytes specifying theBluetooth Address.
HCI_TAirCoding uint8 HCI_AIR_CODING_CVSD
HCI_AIR_CODING_ULAW
HCI_AIR_CODING_ALAW
HCI_TAuthMode uint8 HCI_AUTH_ENABLE
HCI_AUTH_DISABLE
HCI_TClockOffset uint16 bit 15 -> Clock offset valid flag
0 -> Invalid
1 -> Valid
bit14,0 ->bit 16..2 of CLKslave-CLKmaster
Difference between the ownclock and clock of theremote device
HCI_TCod struct
{ ucA[HCI_SIZE_OF_COD]
}
- Array of bytes specifying theClass of Device
HCI_TDeleteLinkKeyFlag uint8 HCI_DELETEKEY_ADDRESS
HCI_DELETEKEY_ALL
HCI_TEncryptionMode uint8 HCI_ENCRYPTION_OFF
HCI_ENCRYPTION_POINT_TO_POINT
HCI_ENCRYPTION_POINT_TO_MULTI_POINT
HCI_TFilterConditionType uint8 HCI_FILTER_INQUIRY_ALL
HCI_FILTER_INQUIRY_COD
HCI_FILTER_INQUIRY_ADDRESS
HCI_FILTER_CONNECT_ALL
HCI_FILTER_CONNECT_COD
HCI_FILTER_CONNECT_ADDRESS
HCI_TFilterType uint8 HCI_FILTER_CLEAR_ALL
HCI_FILTER_INQUIRY
HCI_FILTER_CONNECT
HCI_TFlowControl uint8 HCI_FLOW_CONTROL_OFF
HCI_FLOW_CONTROL_ON
HCI_TInputCoding uint8 HCI_INPUT_CODING_LINEAR
HCI_INPUT_CODING_ULAW
HCI_INPUT_CODING_ALAW
HCI_TInputFormat uint8 HCI_INPUT_FORMAT_1COMPLEMENT
HCI_INPUT_FORMAT_2COMPLEMENT
HCI_INPUT_FORMAT_SIGN_MAGNITUDE
Bluetooth PC Reference Stack by Ericsson
Page 159
HCI_TInterval uint16 - Multiply this value with 0.625ms to get actual time.
HCI_TKeysDeleted uint16 - Number of keys deleted
HCI_TKeysRead uint16 - Number of keys returned
HCI_TLinkKey struct
{ucA[HCI_SIZE_OF_LINKKEY]
}
Array of bytes specifying thelink key
HCI_TMaxKey uint16 - Maximum keys that can bestored
HCI_TName uint8 Default: Zero length string terminated with aNULL character.
Array of 248 bytes. String isUTF-8 encoded and isterminated with a 0 whenshorter than 248 bytes.
HCI_TOnOff uint8 HCI_DO_AUTO_ACCEPT
HCI_DO_NOT_AUTO_ACCEPT
HCI_TPageScanMode uint8 HCI_MANDATORY_PAGE_SCAN_MODE
HCI_OPTIONAL_PAGE_SCAN_MODE_I
HCI_OPTIONAL_PAGE_SCAN_MODE_II
HCI_OPTIONAL_PAGE_SCAN_MODE_III
HCI_TPageScanPeriodMode uint8 HCI_P0
HCI_P1
HCI_P2
HCI_TPcmBitPos uint8 - Range: 0-7
HCI_TPinType uint8 HCI_PIN_VARIABLE
HCI_PIN_FIXED
HCI_TPowerLevel int8 - Powerlevel in dBm
Range: -30 .. 20
HCI_TReadLinkKeyFlag uint8 HCI_LINKKEY_ADDRESS
HCI_LINKKEY_ALL
HCI_TSampleSize uint8 HCI_SAMPLE_SIZE_8BIT
HCI_SAMPLE_SIZE_16BIT
HCI_TScanEnable uint8 HCI_INQUIRY_SCAN_ENABLED
HCI_PAGE_SCAN_ENABLED
These values can be OR’ed
HCI_TScoFlowControl uint8 HCI_SCO_FLOW_CONTROL_ENABLED
HCI_SCO_FLOW_CONTROL_DISABLED
HCI_TSeqNr uint16 - This 16 bit integer representa sequence number
HCI_TTransmitPowerLevelType uint8 HCI_TRANSMIT_POWER_LEVEL_CURRENT
HCI_TRANSMIT_POWER_LEVEL_MAXIMUM
MSG_TControlHdr
Table 5-95 - Data Elements of host controller and baseband commands
Note: In the struct, field ucA[0] is the MSB.
5.6.7.2.4 Defines
Bluetooth PC Reference Stack by Ericsson
Page 160
Name Value Description
HCI_ ENCRYPTION_MODE_POINT_TO_POINT 1
HCI_AIR_CODING_ALAW 2
HCI_AIR_CODING_CVSD 0
HCI_AIR_CODING_ULAW 1
HCI_AUTH_DISABLE 0
HCI_AUTH_ENABLE 1
HCI_DELETEKEY_ADDRESS 0 Delete only link keys which matches withthe given BD Address
HCI_DELETEKEY_ALL 1 Delete all link keys
HCI_DO_AUTO_ACCEPT 2
HCI_DO_NOT_AUTO_ACCEPT 1
HCI_ENCRYPTION_MODE_OFF 0
HCI_ENCRYPTION_MODE_POINT_TO_MULTI_POINT 2
HCI_FILTER_CLEAR_ALL 0
HCI_FILTER_CONNECT 2
HCI_FILTER_CONNECT_ADDRESS 0x02
HCI_FILTER_CONNECT_ALL 0x00
HCI_FILTER_CONNECT_COD 0x01
HCI_FILTER_INQUIRY 1
HCI_FILTER_INQUIRY_ADDRESS 0x02
HCI_FILTER_INQUIRY_ALL 0x00
HCI_FILTER_INQUIRY_COD 0x01
HCI_INQUIRY_SCAN_ENABLED 1
HCI_PAGE_SCAN_ENABLED 2
HCI_LINKKEY_ADDRESS 0 Return only link keys which matches withthe given BD Address
HCI_LINKKEY_ALL 1 Return all link keys
HCI_MANDATORY_PAGE_SCAN_MODE 0
HCI_OPTIONAL_PAGE_SCAN_MODE_I 1
HCI_OPTIONAL_PAGE_SCAN_MODE_II 2
HCI_OPTIONAL_PAGE_SCAN_MODE_III 3
HCI_R0 0
HCI_R1 1
HCI_R2 2
HCI_SAMPLE_SIZE_16BIT 1
HCI_SAMPLE_SIZE_8BIT 0
HCI_TRANSMIT_POWER_LEVEL_CURRENT 0
HCI_TRANSMIT_POWER_LEVEL_MAXIMUM 1
HCI_PIN_VARIABLE 0
Bluetooth PC Reference Stack by Ericsson
Page 161
HCI_PIN_FIXED 1
HCI_INPUT_CODING_LINEAR 0
HCI_INPUT_CODING_ULAW 1
HCI_INPUT_CODING_ALAW 2
HCI_FLOW_CONTROL_OFF 0 Turn flow control off
HCI_FLOW_CONTROL_ON 1 Turn flow control on
HCI_SCO_FLOW_CONTROL_ENABLED 0 Enable Sco flow control
HCI_SCO_FLOW_CONTROL_DISABLED 1 Disable Sco flow control
Table 5-96 - Defines of host controller & baseband commands
5.6.7.3 Communication proceduresThe first one requests for all link-keys stored in the LM. The second one requests the link- keysthat belong to a certain BD Address. This is done with the tReadLinkKeyFlag set toHCI_LINKKEY_ADDRESS.
Host HCI
HCI_ReqReadLinkKey(tSeqNr = 34, tAddress = 11 22 33 44 55 66, tReadLinkKeyFlag = HCI_LINKKEY_ALL)
tSeqNr = 34, tMaxKey= 5, tKeysRead=2
HCI_READ_LINK_KEY_RESULT_EVT
HCI_READ_LINK_KEY_RESULT_EVT
HCI_READ_LINK_KEY_CNF
tAddress = 07 08 09 0A 0B 0C,tLinkKey = 01 02 03 04 05 06 07 08 09 0A 0B
0C 0D 0E 0F
tAddress = 01 02 03 04 05 06,tLinkKey = 11 22 33 44 55 66 77 88 99 AA BB
CC DD EE FF
HCI_ReqReadLinkKey(tSeqNr = 56, tAddress = 11 22 33 44 55 66, tReadLinkKeyFlag = HCI_LINKKEY_ADDRESS)
tSeqNr = 56, tMaxKey= 5, tKeysRead=1
HCI_READ_LINK_KEY_RESULT_EVT
HCI_READ_LINK_KEY_CNF
BT_TAddress = 11 22 33 44 55 66,HCI_TLinkKey = 10 20 30 40 50 60 70 80 90 A0
B0 C0 D0 E0 F0
Read LinkKey from specified BD Address
Figure 5-57 - Read LinkKey
Bluetooth PC Reference Stack by Ericsson
Page 162
If on link key exists the host will not receive a HCI_READ_LINK_KEY_EVT and the tKeysRead inthe message HCI_READ_LINK_KEY_CNF will be 0.
AIR
DevicesHost HCI/LM
HCI_ReqInquirytSeqNr = 34, tInquiryLength = 5,tInquiryPeriod = 7, tCod =0x9E8B33
tSeqNr = 34, NrOfResponses = 1
HCI_INQUIRY_RESULT_EVT
HCI_INQUIRY_CNF
BT_TAddress = AA BB CC DD EE FF
BT_TAddress = 0x11 22 33 44 55 66,HCI_TPageScanRepMode,
HCI_TPageScanPeriodMode,HCI_TPageScanMode,
HCI_TCod,HCI_TClockOffset
HCI_ReqSetFiltertSeqNr = 31,tFilterType = HCI_FILTER_INQUIRY,tFilterCondition =HCI_FILTER_INQUIRY_ADDRESS,tAddress = 11 22 33 44 55 66
HCI_FILTER_CNF
tSeqNr = 31
INQUIRY_CONF
INQUIRY_CONF
BT_TAddress = 11 22 33 44 55 66
Devices
Figure 5-58 – Set Inquiry Filter
First an inquiry-filter is added for Bluetooth devices with address 11 22 33 44 55 66 (note: theaddresses are in hexadecimal). After this an inquiry is performed. HCI receives from two devicesan inquiry_conf but only one the one that meet the filter requirements is passed on to the host.
Devices
AIR
Host HCI/LM
HCI_CONNECT_INDBT_TAddress = AA BB CC DD EE FF
BT_TAddress = 0x11 22 33 44 55 66,tCod,
tLinkType
HCI_ReqSetFiltertSeqNr = 32,tFilterType = HCI_FILTER_CONNECT,tFilterCondition =HCI_FILTER_INQUIRY_ADDRESS,tAddress = AA BB CC DD EE FF
HCI_FILTER_CNF
tSeqNr = 32
ConncectReq
ConnectReq
BT_TAddress = 11 22 33 44 55 66
Devices
Figure 5-59 - Set Connect Filter
First a connect-filter is added for Bluetooth devices with address AA BB CC DD EE FF (note: theaddresses are in hexadecimal). When HCI receive a connect_ind from a device that meet thefilter requirements, a HCI_CONNECT_IND is passed on to the host.More filters can be added but the first filter that applies to a connect_ind or inquiry_conf is used.E.g. A filter is added for a certain BD address and (after this) a filter is added for a certain Cod. Ifa device with the specified Cod wants to connect it is passed to the host even if the BD addressisn’t correct.
Bluetooth PC Reference Stack by Ericsson
Page 163
5.6.8 Informational CommandsThe informational parameters are fixed by the manufacturer of the Bluetooth Hardware. Theseparameters provide information about the Bluetooth device and the capabilities of the HostController, Link Manager and Baseband. The host cannot modify any of these parameters.
5.6.8.1.1 Function Interface
Name Parameters Description
HCI_ReqCountryCode HCI_TSeqNr Read the CountryCode of the local Bluetooth device
HCI_ReqLocalAddress HCI_TSeqNr Read the BDAddress of the local Bluetooth device
HCI_ReqLocalAddress HCI_TSeqNr Read the BDAddress of the local Bluetooth device
HCI_ReqReadLocalFeatures HCI_TSeqNr Read a list of supported features for the local device.
HCI_ReqReadLocalVersion HCI_TSeqNr Read the version information for the local Bluetooth device.
Table 5-97 - Functions of Informational Commands
5.6.8.1.2 Message Interface
Name Parameters Description
HCI_COUNTRY_CODE_CNF MSG_TControlHdr This confirm to HCI_ReqCountryCodereturns the Countrycode
HCI_COUNTRY_CODE_CNF_NEG MSG_TControlHdr Negative confirm toHCI_ReqCountryCode
HCI_LOCAL_ADDRESS_CNF MSG_TControlHdr
BT_TAddress
This confirm to HCI_ReqLocalAddressreturns the local BD Address
HCI_LOCAL_ADDRESS_CNF_NEG MSG_TControlHdr Negative confirm toHCI_ReqLocalAddress
HCI_LOCAL_ADDRESS_CNF_NEG MSG_TControlHdr Negative confirm toHCI_ReqLocalAddress
HCI_READ_LOCAL_FEATURES_CNF MSG_TControlHdr
HCI_TLmpFeatures
Returns a list of supported features forthe local device
HCI_READ_LOCAL_FEATURES_CNF_NEG MSG_TControlHdr Indicate that reading the supportedfeatures of the local device failed
HCI_READ_LOCAL_VERSION_CNF MSG_TControlHdr
HCI_THciVersion
HCI_THciRevision
HCI_TLmpVersion
HCI_TManufacturerName
HCI_TLmpSubVersion
Returns the version information for thelocal Bluetooth device
HCI_READ_LOCAL_VERSION_CNF_NEG MSG_TControlHdr Indicate that reading of the localversion information failed
Table 5-98 - Messages of Informational Commands
Bluetooth PC Reference Stack by Ericsson
Page 164
5.6.8.1.3 Data elements
Name Size Value Description
BT_TAddress 6 x uint8 -
HCI_TCountryCode uint8 HCI_COUNTRY_NORTH_AMERICA_AND_EUROPE
HCI_COUNTRY_FRANCE
HCI_COUNTRY_SPAIN
HCI_COUNTRY_JAPAN
HCI_TErrorCode uint16
HCI_THciRevision uint16 - Revision of the CurrentHCI in the Bluetoothhardware.
HCI_THciVersion uint8 HCI_BLUETOOTH_HCI_SPEC_10 Version of the CurrentHCI in the Bluetoothhardware.
Table 5-99 - Data Elements of Informational Commands
Defines
Name Value Description
HCI_ BLUETOOTH_HCI_SPEC_10 0x00 Bluetooth HCI Specification 1.0
HCI_COUNTRY_FRANCE 0x01 Bluetooth device is only usable in France
HCI_COUNTRY_JAPAN 0x03
HCI_COUNTRY_NORTH_AMERICA_AND_EUROPE 0x00
HCI_COUNTRY_SPAIN 0x02
Table 5-100 - Defines of Informational Commands
5.6.9 Status commands
5.6.9.1 OverviewThe status commands provide information about the current state of HCI, LM and BB. Thesestatus parameters cannot be change by the host, except the ability to reset some parameters.
5.6.9.2 Layout
5.6.9.2.1 Function Interface
Name Parameters Description
HCI_ReqGetLinkQuality HCI_TSeqNr
BT_THandle
Read the value for the Link Quality for the specifiedconnection handle.
Bluetooth PC Reference Stack by Ericsson
Page 165
HCI_ReqReadFailedCounter HCI_TSeqNr
BT_THandle
Read the value for Failed Contact Counter parameterfor a particular connection. The Failed ContactCounter records the number of consecutive incidencesin which either the slave or master didn’t respond afterthe flush timeout had expired.
The counter for a connection is rest or zero on thefollowing coditions:
When a new connection is established
When the counter is greater then zero and a packet isacknowledged for that connection.
The HCI_ReqResetFailCounter was issued
HCI_ReqResetFailedCounter HCI_TSeqNr
BT_THandle
Reset the value for the Failed Contact Counterparameter for a particular connection.
HCI_ReqRssi HCI_TSeqNr
BT_THandle
Read the value for the difference between themeasured Received Signal Strength Indication (RSSI)and the desired RSSI of the radio for the specifiedconnection handle
Table 5-101 - Functions of Status Commands
Note: The connection handles of these functions must be connection handles to an ACLconnection.
5.6.9.3 Message Interface
Name Parameters Description
HCI_GET_LINK_QUALITY_CNF MSG_TControlHdr
BT_THandle
HCI_TLinkQuality
Returns the Link Quality for the specifiedconnection handle. The higher the value,the better Link Quality is.
HCI_GET_LINK_QUALITY_CNF_NEG MSG_TControlHdr Indicate that reading the Link Qualityfailed.
HCI_READ_FAILED_COUNTER_CNF MSG_TControlHdr
BT_THandle
HCI_TFailedCounter
Returns the Failed Contact Counterparameter.
HCI_READ_FAILED_COUNTER_CNF_NEG MSG_TControlHdr
BT_THandle
Indicate that reading the Failed ContactCounter failed.
HCI_RESET_FAILED_COUNTER_CNF MSG_TControlHdr
BT_THandle
Indicate that the Failed Contact Counterhas successfully been reset.
HCI_RESET_FAILED_COUNTER_CNF_NEG MSG_TControlHdr
BT_THandle
Indicate that resetting the Failed ContactCounter failed.
HCI_RSSI_CNF MSG_TControlHdr
BT_THandle
HCI_TRssi
Returns the Rssi value.
HCI_RSSI_CNF_NEG MSG_TControlHdr
BT_THandle
Indicate that reading the Rssi valuefailed.
Table 5-102 - Messages of Status Commands
Bluetooth PC Reference Stack by Ericsson
Page 166
5.6.9.4 Data elements
Name Size Value Description
HCI_TFailedCounter uint16 - Number of failed responses after a flushtimeout.
HCI_TLinkQuality uint8 - The link quality. The higher the value, thebetter the link quality is.
HCI_TRssi int8 - Recevied Signal Strength Indication
Range: –128 .. 127
Units: dB
Table 5-103 - Data Elements of Status Commands
5.6.10 Test commands
5.6.10.1 OverviewThe testing commands are used to provide the ability to test various functionality of the Bluetoothhardware. For a more complete description see chapter “Testing Commands” of [1].
5.6.10.2 Layout
5.6.10.2.1 Function Interface
Name Parameters Description
HCI_ReqEnableDutMode HCI_TSeqNr This command allow the local bluetooth device toenter test mode via LMP test commands.
HCI_ReqReadLoopbackMode HCI_TSeqNr Read the value for the host controller’s loopbackmode setting.
HCI_ReqWriteLoopbackMode HCI_TSeqNr
HCI_TLoopbackMode
Write the value for the host controller’s loopbackmode setting
Table 5-104 - Functions of Status Commands
5.6.10.3 Message Interface
Name Parameters Description
HCI_ENABLE_DUT_MODE_CNF MSG_TControlHdr Indicate that Device Under Test mode isenabled
HCI_ENABLE_DUT_MODE_CNF_NEG MSG_TControlHdr Indicate that enabling Device Under Testmode failed
HCI_READ_LOOPBACK_MODE_CNF MSG_TControlHdr
HCI_TLoopbackMode
Returns the loop-back mode
HCI_READ_LOOPBACK_MODE_CNF_NEG MSG_TControlHdr Indicate that reading the loop-back modefailed
HCI_WRITE_LOOPBACK_MODE_CNF MSG_TControlHdr Indicate that the loop-back mode hassuccessfully been written.
HCI_WRITE_LOOPBACK_MODE_CNF_NEG MSG_TControlHdr Indicate that writing the loop-back modefailed
Bluetooth PC Reference Stack by Ericsson
Page 167
Table 5-105 - Messages of Status Commands
5.6.10.4 Data elements
Name Size Value Description
HCI_TLoopbackMode uint8 HCI_LOOPBACK_NONE
HCI_LOOPBACK_ LOCAL
HCI_LOOPBACK_ REMOTE
Table 5-106 - Data Elements of Status Commands
5.6.10.5 Defines
Name Value Description
HCI_LOOPBACK_NONE 0 No loopback
HCI_LOOPBACK_ LOCAL 1 Local loopback mode
HCI_LOOPBACK_ REMOTE 2 Remote loopback mode
Table 5-107 - Defines of Status Commands
Bluetooth PC Reference Stack by Ericsson
Page 168
5.6.11 Communication Procedures
HOST HCI
HCI_ReqWriteLoopbackMode
tSeqNr = 1tLoopbackMode =HCI_LOOPBACK_LOCAL
HCI_WRITE_LOOPBACK_MODE_CNF
tSeqNr = 1
HCI_CONNECT_COMPLETE_EVT
tAddress, tHandle = 4,tLinkType=SCO,tEncryptionMode
HCI_DATA_IND
tAddress, tCoD, tLinkType=ACL
HCI_RspData
tRole,tErrorCode = HCI_NO_ERROR
HCI_CONNECT_COMPLETE_EVT
tAddress, tHandle = 1,tLinkType=ACL,tEncryptionMode
HCI_CONNECT_COMPLETE_EVT
tAddress, tHandle = 2,tLinkType=SCO,tEncryptionMode
HCI_CONNECT_COMPLETE_EVT
tAddress, tHandle = 3,tLinkType=SCO,tEncryptionMode
HCI_Command
~~~~HCI_LOOPBACK_EVT
HCI_DataSend
tSeqNr = 1, *pData, tHandle = 1
HCI_DATA_IND
tAddress, tCoD, tLinkType=SCO
HCI_RspData
tRole,tErrorCode = HCI_NO_ERROR
HCI_DataSend
tSeqNr = 1, *pData, tHandle = 3
Figure 5-60 - Local Loopback Mode
Bluetooth PC Reference Stack by Ericsson
Page 169
In Local Loopback every command is return in the HCI_LOOPBACK_EVT accept for Reset,ReadLoopbackMode, WriteLoopbackMode, DataInfo and SetHostBufferSize.
AIR
HOST:1 HOST:2HCI:1 HCI:2
HCI_ReqWriteLoopbackMode
tSeqNr = 1tLoopbackMode =HCI_LOOPBACK_REMOTE
HCI_WRITE_LOOPBACK_MODE_CNF
tSeqNr = 1
HCI_CONNECT_IND
tAddress, tCoD, tLinkType=ACL
HCI_CONNECT_CNF
tSeqNr=2, tAddress, tHandle = 1,tLinkType,tEncryptionMode
HCI_CONNECT_COMPLETE_EVT
tAddress, tHandle,tLinkType,tEncryptionMode
HCI_RspConnect
tRole,tErrorCode = HCI_NO_ERROR
HCI_ReqConnect
tSeqNr = 2tAddress, tPacketType
HCI_DATA_IND
tAddress, tCoD, tLinkType=ACL
HCI_RspData
tRole,tErrorCode = HCI_NO_ERROR
HCI_DataAlloc
uiLength
HCI_DataSend
tSeqNr = 3, pucData, tHandle = 1,uiLength
HCI_DataSend
tSeqNr = 3, pucData, tHandle = 1,uiLength
HCI_DATA_IND
tAddress, tCoD, tLinkType=ACL
HCI_RspData
tRole,tErrorCode = HCI_NO_ERROR
Figure 5-61 - Remote Loopback Mode
In Remote Loopback mode a connection from a remote device will accepted and every datapacket that is send to local device (the one that is in Remote Loopback mode) will be send backto the remote device (the device that initiated the connection).
Bluetooth PC Reference Stack by Ericsson
Page 170
5.6.12 Data Commands
5.6.12.1.1 Function Interface
Function interface (from higher layers to this component)
Name Parameters Function Description
HCI_CmdFlush BT_THandle This function flushes the outstanding data for the connectionindicated by tHandle.
HCI_DataAlloc uint16 uiLength returns a pointer of type uint8* to allocated buffer
HCI_DataBroadcast uint8* pData
uint16 uiLength
HCI_TBroadcast
HCI_TPacketBoundary
The same as HCI_DataSend only not for point-to-point but forbroadcast. tBroadcast defines whether this message is send to allthe active devices (HCI_BROADCAST_ACTIVE) or also to theparked devices (HCI_BROADCAST_ALL)
HCI_DataExtract MSG_TDataMsg*
BT_THandle*
uint16* puiLength
HCI_TPacketBoundary*
This function returns a pointer to the start of the data in themessage that is received with a HCI_DATA_IND. The otherparameters are extracted from this message.
HCI_DataFree uint8* pucData Free the buffer which is allocated with HCI_DataAlloc
HCI_DataSend HCI_TSeqNr
uint8* pucData
BT_THandle
uint16 uiLength
HCI_TPacketBoundary
Sends the data packet, pointed by pucData. This is only meant fora point-to-point connection and no broadcast.HCI_TPacketBoundary defines whether the data packet is the first(or complete) fragment or a next (continuing) fragment.
HCI_DataExtract MSG_TDataMsg*
BT_THandle*
uint16* puiLength
HCI_TPacketBoundary*
This function returns a pointer to the start of the data in themessage which is received with a HCI_DATA_IND. The otherparameters are extracted from this message.
HCI_DataFree uint8* pucData Free the buffer which is allocated with HCI_DataAlloc
HCI_DataSend HCI_TSeqNr
uint8* pData
BT_THandle
uint16 uiLength
HCI_TPacketBoundary
Sends the data packet, pointed by pData. This is only meant for apoint-to-point connection and no broadcast. tPacketBoundarydefines whether the data packet is the first (or complete) fragmentor a next (continuing) fragment.
HCI_ReqDataInfo HCI_TSeqNr This function is used to retrieve information about the maximumamount of outstanding ACL/SCO packets, maximum packet size,number of leading and trailer bytes that HCI needs for every datapacket.
HCI_RspData BT_THandle
Table 5-108 - Functions of Data Commands
5.6.12.1.2 Message Interface
Bluetooth PC Reference Stack by Ericsson
Page 171
Name Contents Message Description
HCI_DATA_CNF MSG_TControlHdr
BT_THandle
Indicates that the data packet has been sent to the remotehost
HCI_DATA_CNF_NEG MSG_TControlHdr
BT_THandle
Indicates that the data packet associated with the givenconnection handle could not be sent to the remote host.
This is probably because the data has been flushed by thelink manager.
HCI_DATA_IND MSG_TDataMsg Indicates that a data message has been received by theHCI.
HCI_DATA_INFO_CNF MSG_TControlHdr
HCI_TMaxAclPacketSize
HCI_TMaxScoPacketSize
HCI_TMaxAclPackets
HCI_TMaxScoPackets
uint8
uint8
This is the return message for HCI_ReqDataInfo.
Maximum ACL packet size
Maximum SCO packet size
Maximum outstanding ACL packets
Maximum outstanding SCO packets
Number of trailer bytes
Number of header bytes
Table 5-109 - Messages of Data Commands
Note: HCI_DATA_IND do not actually contains the struct MSG_TDataMsg but is equal to thisstructure.
5.6.12.1.3 Data elements
Parameters of the functions
Name Size Value Description
BT_THandle uint16 -
HCI_TBroadCast uint8 HCI_BROADCAST_NO
HCI_BROADCAST_ACTIVE
HCI_BROADCAST_ALL
HCI_TMaxAclPackets uint8 - Maximum amount of outstanding ACL packets
HCI_TMaxAclPacketSize uint16 - Maximum packet size
HCI_TMaxScoPackets uint8 - Maximum amount of outstanding SCO packets
HCI_TMaxScoPacketSize uint16 - Maximum packet size
HCI_TPacketBoundary uint8 HCI_PACKET_COUNTINUE
HCI_PACKET_FIRST
HCI_TSeqNr uint16 - Sequence number. The reply of a message mustalways have the same sequence number as thereceived message. This can be used to matchmultiple outstanding messages (Req/Ind) with theresponses (Cnf/Rsp). In the function calls forReq/Ind the SeqNr is the first parameter.
MSG_TControlHdr uint64 -
Table 5-110 - Data Elements of Data Commands
Bluetooth PC Reference Stack by Ericsson
Page 172
Defines
Name Value Description
HCI_PACKET_COUNTINUE 0x00 Next fragment to send
HCI_PACKET_FIRST 0x01 First (or complete) fragment to send
HCI_BROADCAST_NO 0x00
HCI_BROADCAST_ACTIVE 0x01 Broadcast to only the active devices
HCI_BROADCAST_ALL 0x02 Broadcast to all active and parked devices
Table 5-111 - Defines of Data Commands
Bluetooth PC Reference Stack by Ericsson
Page 173
5.6.12.2 Communication procedures
In the MSC below the usage of the data functions is depicted.
HOST:1 HOST:2HCI:1 HCI:2
HCI_ReqDataInfo
HCI_DATA_INFO_CNF
HCI_DataAllocuiLength
tSeqNr
HCI_ReqDataSendtSeqNr, pData, tHandle,uiLength, tPacketBoundary
tHdrMAX_ACL_PACKET_SIZEMAX_SCO_PACKET_SIZE
MAX_ACL_PACKETSMAX_SCO_PACKETS
ucNrOfHdrBytesucNrOfTrailerBytes
HCI_DATA_INDtDataHeaderucData
HCI_RspDatatHandleHCI_DATA_CNF
tHdrtHandle
HCI_DataExtractptDataInd
tHandleuiLength
tPacketBoundary
SET-UP CONNECTION
Figure 5-62 - Usage of Data functions
This MSC gives an example of a data transfer for both sides on the link. With theHCI_DataExtract the host (host 2) can extract the handle, data length, pointer to the data and thepacket boundary from the message received with an HCI_DATA_IND.
5.6.12.3 Interface specific itemsHCI_TPacketBoundary:If a higher level L2CAP frame is greater than the maximum data length that can be send withHCI_DataSend the frame is divided in several pieces. The first part must be indicated withHCI_PACKET_FIRST. If an entire frame can be send with one HCI_DataSend this packet mustalso be indicated with HCI_PACKET_FIRST. Every ‘FIRST’ packet must contain a correct L2CAPlength, see [1] – Logical Link Control and Adaptation Protocol Specification.HCI_DataAlloc:To allocate memory to send data the function HCI_DataAlloc must be used since the HostController need to add some extra data to the data packet. The lower layer needs this extra data.The amount of extra data can be requested with HCI_ReqDataInfo. This function returns thenumber of header- and trailer-bytes. E.g. to send a data packet of 100 bytes and the number ofheader-bytes is 4 and the number of trailer-bytes is 2, HCI_DataAlloc is called to allocate 106bytes. The pointer returned with HCI_DataAlloc is the pointer to the place where the Host can puthis data.HCI_ReqDataInfo also returns the maximum packet size for ACL data packets and SCO datapackets. Data blocks larger than these sizes must not be allocated.
Bluetooth PC Reference Stack by Ericsson
Page 174
5.6.13 HCI Error values
Name Value Description
HCI_NO_ERROR 0x00 no error detected
HCI_UNKNOWN_COMMAND -0x01 Unknown HCI Command
HCI_NO_CONNECTION -0x02 No Connection
HCI_HW_FAILURE -0x03 Hardware Failure
HCI_PAGE_TIMEOUT -0x04 Page Timeout
HCI_AUTH_FAILURE -0x05 Authentication Failure
HCI_KEY_MISSING -0x06 Key Missing
HCI_MEMORY_FULL -0x07 Memory Full
HCI_CONNECTION_TIMEOUT -0x08 Connection Timeout
HCI_MAX_NUM_CONNECTIONS -0x09 Max Number Of Connections
HCI_MAX_SCO -0x0A Max Number Of SCO Connections To A Device
HCI_MAX_ACL -0x0B Max Number Of ACL Connections To A Device
HCI_COMMAND_DISALLOWED -0x0C Command Disallowed
HCI_REJECT_LIM_RESOURCE -0x0D Host Rejected due to limited resources
HCI_REJECT_SECURITY -0x0E Host Rejected due to security reasons
HCI_REJECT_PERSONAL -0x0F Host Rejected due to remote device is only apersonal device
HCI_HOST_TIMOUT -0x10 Host Timeout
HCI_UNSUPPORTED -0x11 Unsupported Feature or Parameter Value
HCI_INVALID_PARAMETERS -0x12 Invalid HCI Command Parameters
HCI_OE_USER_ENDED_CONNECTION -0x13 Other End Terminated Connection: User EndedConnection
HCI_OE_LOW_RESOURCES -0x14 Other End Terminated Connection: Low Resources
HCI_OE_POWER_OFF -0x15 Other End Terminated Connection: About to PowerOff
HCI_CONNECTION_TERMINATED -0x16 Connection Terminated by Local Host
HCI_REPEATED_ATTEMPS -0x17 Repeated Attempts
HCI_PAIRING_NOT_ALLOWED -0x18 Pairing Not Allowed
HCI_UNKNOWN_LMP_PDU -0x19 Unknown LMP PDU
HCI_UNSUP_REMOTE_FEATURE -0x1A Unsupported Remote Feature
HCI_SCO_OFFSET_REJECTED -0x1B SCO Offset Rejected
HCI_SCO_INTERVAL_REJECTED -0x1C SCO Interval Rejected
HCI_AIR_MODE_REJECTED -0x1D SCO Air Mode Rejected
Bluetooth PC Reference Stack by Ericsson
Page 175
HCI_INVALID_LMP -0x1E Invalid LMP Parameters
HCI_UNSPECIFIED_ERROR -0x1F Unspecified Error
HCI_UNSUP_LMP_VALUE -0x20 Unsupported LMP Parameter Value
HCI_ROLE_SWITCH_NOT_ALLOWED -0x21 Role switch not allowed
HCI_LMP_RESPONSE_TIMEOUT -0x22 LMP Response Timeout
HCI_LMP_ERROR_TRANSACTION_COLLISION -0x23 LMP Error Transaction Collision
HCI_LMP_PDU_NOT_ALLOWED -0x24 LMP PDU Not Allowed
HCI_NEG_DATA_FLUSHED -0x25 Data is flushed
HCI_NEG_DEVICE_TIMEOUT -0x26 Device timeout
HCI_NEG_NOT_STARTED -0x27 HCI is not started
Table 5-112 - HCI Error values
Bluetooth PC Reference Stack by Ericsson
Page 176
5.7 Timer Service (TIM)This section describes the interfaces to the timer component. The interfaces to the timercomponent are function calls only. The interface from the timer component to another task ismessage event.
5.7.1 Interface Timer
5.7.1.1 Overview
The timer handling offers the user the possibility to use software timers for general purpose.
5.7.1.2 Layout
5.7.1.2.1 Function Interface
Name Parameters Function Description
TIM_StartTimer ulTime,
MSG_TMsgID,
uiInstance,
uiOccurence
This function starts a timer.
TIM_StopTimer MSG_TMsgID,
uiInstance
This function stops the timer that has been started with theTIM_StartTimer function
Table 5-113 : Function Interface of Timer
5.7.1.3 Message Interface
Name Contents Message Description
TASK_TIMEOUT MSG_TMsg
uiInstance,
uiOccurence
This message event is send back to the Task that started the Timerwhen the given time has elapsed.
Table 5-114 : Message Interface of Timer
The Message ID TASK_TIMEOUT can be defined by the task that is using the timer.
5.7.1.4 Data elements
Name Size Value Description
MSG_TMsg [3] - The Message ID of timer.
MSG_TMsgID [3] - The Message ID of timer.
uiInstance uint16 - The instance of the timer.
Bluetooth PC Reference Stack by Ericsson
Page 177
uiInstance uint16 - The instance of the timer, so the receiving Task can check whichtimer elapsed. (will be the same as in the TIM_StartTimer)
uiOccurence uint16 - Incremental parameter that must be Incremented each time thetimer is started.
uiOccurence uint16 - Incremental parameter, so the receiving Task can check that his isa valid occurrence. (will be the same as in the TIM_StartTimer)
ulTime uint32 - Duration. The duration of the timer specified in milliseconds.
Table 5-115: Data Elements of Timer Function/Messages
Communication procedures
Task TIM
TIM_StartTimer ulTime=100, uiInstance=1, uiOccurence =1
TASK_TIMEOUT uiInstance=1, uiOccurence=1
100 mSec
TIM_StartTimer ulTime=100, uiInstance=1, uiOccurence=2
Stopping a timer
TIM_StopTimer uiInstance=1100 mSec
Figure 5-63: MSC of Timer use
TIM_StartTimer starts a timer for the specified number of milliseconds. When the Timer elapses,a message is send to the task that started the Timer, with the tHdr (MessageID(TASK_TIMEOUT)) that was specified in the parameter when the Timer was started. If a taskstarts the same Timer before it has elapsed and with the same ID, it will be set to the new value. Itmay occur that the Timer elapses the same time the Timer was re-started and an unexpectedTimer elapsed will be received with the next VOS_Receive. In order to detect these situations theparameter Occurrence should be incremented each time the Timer is started, the occurrence willbe in the message that is send to the task when the timer does elapse. When this occurrencediffers from the occurrence passed when the Timer was started, the message must be ignoredsince it was the previous occurrence of the timer that did elapse.A Timer may have several instances where each instance is handled as a separate Timer.TIM_StopTimer will stop a previous started timer that was started with the same message ID andinstance. If no such timer exits (anymore) a call to TIM_stoptimer will be ignored.
Bluetooth PC Reference Stack by Ericsson
Page 178
6. TEST SAMPLE APPLICATION SUITE
The sample code on application level consists of sample application and support functions. Thesample application is made in order to demonstrate the message flow towards the stack API. Thesupport functions are used by the sample application and could be used in other applications.
6.1 TestSample application
HCI Driver
RFCOMM
L2CAP
SDP
ClientApplication
VOS Interface
SCM
SecurityApplication
Host Stack
Extended VOSLibrary (evos.c)
Support functionsLibrary (btapi.c)
ApplicationProgrammersInterface
ServerApplication
Figure 6-1 How the different parts of the sample application interacts with each other, theStack and VOS.
The test sample application consists of three parts, the first application acting like a server, thesecond application acting like a client and the third one handling the BT security.
In order to test the executables on two PC’s proceed as follows:
• Register the ‘bt_comserver.exe’ on two PC's see installation chapter.
• Connect a bluetooth device to COM1 on both PC's. The ‘TestSample’ applicationuses COM1, which can be modified.
• Start ‘BT_TestSampleSecurity.exe’ and ‘BT_TestSampleServer.exe on one PC
• Start ‘BT_TestSampleClient.exe’ on the other PC.
• Now you can fill the BD_Address of the server in the 'client' window.
• After doing that, the ‘testsample‘ should run its test-sessions.
The intention with the sample application is to use it together with a debugger.
You need to run one security application on every device running the PC Reference Stack. Youcan then run one or more client application(s) and server application(s) as well on the samedevice.
Bluetooth PC Reference Stack by Ericsson
Page 179
Note 1:The test sample application is intended as a guidance when designing ownapplications for non-windows environment making use of this PC reference stack asa development tool. It is not intended as a “ready to use application”. When writingwindows specific programs it is better to take the Chat application as a guidance.
Sample Component File name Description
Client side application client.c, client.h This module contains an example of a clienttype of application, running on top ofRFCOMM. This client expects a headsetserver in a fixed destination device.
Server sideapplication
server.c, server.h This server acts as a headset server.
Security module. security.c, security.h This component takes care of accepting a newACL connection and provides the stack with aPIN-code when necessary. The stack supportsseveral client and server sessions at a time butonly one can be the security manager. Thesecurity manager in this sample is a stand-alone application.
Table 6-1 File description of the sample application
The interface of the test sample suite is shown below.
Figure 6-2 Test sample client interface.
Bluetooth PC Reference Stack by Ericsson
Page 180
Figure 6-3 Test sample server interface.
Figure 6-4 Test sample security interface.
For the message flow in normal operation, see.
6.1.1 Client type of application
The client type of application, running on top of RFCOMM. This client expects a headset server ina fixed destination device. It has the following simple functionality, showing the basic interaction tothe stack:
1. Perform a device inquiry.2. Check whether the inquiry result contains the fixed destination address.3. Setup an RFCOMM connection to the server.4. Send a message with the text: "who are you?".5. Wait for the message "headset" for a maximum time of 10 sec.6. Attach an SCO (voice) connection.7. The client sends a small data packet (1 byte; SMALL_PACKET_LENGTH)8. The client waits forever for the echo.9. The client sends a large data packet (1000 byte; LARGE_PACKET_LENGTH).10. The client waits forever for the echo.11. Disconnect the SCO (voice) connection.12. Disconnect the RFCOMM connection.
This will be repeated in an endless loop.REMARK1: you can run several different independent clients on top of the stack.REMARK2: Because RFCOMM is only able to handle one packet at a time, and I don't want tomake an extensive state-machine, all data to be transmitted is passed through a TxAdmin usingthe routine ‘SendData'. This TxAdmin is able to handle two Tx data-packets simultaneously (onein it's queue, and one in RFCOMM being processed). This gives a little bit more flexibility onapplication level. If two is not enough, then you have to extend this TxAdmin with a real messagequeue with the desired size.REMARK3: This module uses compiler directive: EMBEDDED When this application should runin a HOST environment with an HCI-driver, the directive may not be set. It may only be set in an'embedded' environment where no HCI-driver is used.REMARK4: This module uses compiler directive: ONE_TIME_INQUIRY When this directive isdefined: the application should run an inquiry session until it finds the programmed destinationaddress (_tDestAddress). After finding it will run the test sessions without doing additionalinquiries (faster sessions).
Bluetooth PC Reference Stack by Ericsson
Page 181
REMARK5: (Only applicable to the TestSample running as a COM-client on the PC referencestack). This version needs some porting because the application should be written as an event-handler for messages from the COM-server. All modifications are marked with "Porting to COM-client environment".Main differences with original TestSample:- TestSample application is a message event handler that is activated by the COM-server, insteadof an endless loop where it should retrieve its own message from the OS.- This TestSample has also a window where the user can provide some input and the TestSamplecan show some test results.- The ONE_TIME_INQUIRY compiler directive is replaced by a global boolean, which can beset/reset by the user via the window.
Table 6-2 Client application flowchart
6.1.2 Server type of application
This module contains an example of a server type of application, running on top of RFCOMM.This server acts as a headset server. It has the following simple functionality, showing the basicinteraction to the stack and to the connected client:
1. On reception of a "who are you?" message, it replies with "headset".2. On reception of other data messages, it echo's them back to the client.
REMARK1: You can run several different independent servers on top of the stack.REMARK2: Because RFCOMM is only able to handle one packet at a time, and I don't want tomake an extensive state-machine, all data to be transmitted is passed through a TxAdmin using
Bluetooth PC Reference Stack by Ericsson
Page 182
the routine ‘SendData'. This TxAdmin is able to handle two Tx data-packets simultaneously (onein it's queue, and one in RFCOMM being processed). This gives a little bit more flexibility onapplication level. If two is not enough, then you have to extend this TxAdmin with a real messagequeue with the desired size.REMARK3: This module uses 1 compiler directive: EMBEDDED When this application should runin a HOST environment with an HCI-driver, the directive may not be set. It may only be set in an'embedded' environment where no HCI-driver is used.
6.1.3 Security type of application
The security component, that could be available in a server type of application, acceptingconnections. This component takes care of accepting a new ACL connection and provides thestack with a PIN-code when necessary. It has the following simple functionality, showing the basicinteraction to the stack:
1. Registration to the stack as being a connection security manager.2. Initialise HCI for accepting ACL connections and inquiries.3. Accept any incoming ACL connection.4. Provide the stack with a fixed PIN-code on request.
REMARK: you can run only one security type of component on top of the stack, because thestack needs only one destination in the application for the ACL connection acceptance and PIN-code request. So, when having several servers on top of the stack, only one of them may act as asecurity manager (or use a separate component like this one for this purpose).
Bluetooth PC Reference Stack by Ericsson
Page 183
6.2 Support API
Sample Component File name Description
Function librarymodule.
btapti.c, btapti.h This module contains fundamental messageexchanges sequences used by most BTapplications. The functions is called from theclient, server and security sample application
BT profile support profile.c, srp.c , profile.h, srp.h The module contains message exchangessequences used when setting up a BT profile.(This component is not completely tested yet)
Enhanced VOSmodule.
evos.c, evos.h This module contains the source code for theextended receive functionallity used by thesupport API. The extended VOS receive is areceive function with as signal selectionmechanism.
Table 6-3 File description of the support component
6.2.1 Function library module
This module contains some library functions, which simplifies the interface to the EricssonBluetooth stack. It simplifies the interface for 3 types of interfaces to the stack which are detectedas rather complicated:
1. Initialisation for a client or server (see BTAPI_InitStackForClient andBTAPI_InitStackForServer)
2. Connection set-up over RFCOMM for a client type of application. (seeBTAPI_ConnectRfcomm)
3. Registration of a service (profile) for a server type of application running on top of RFCOMM.(see BTAPI_RegisterProfile, where 5 profiles are supported).
REMARK:
This BTAPI module is making use of an 'evos' module, which is an extension for the VOS (VirtualOS). Within this evos module, there is an EVOS_Receive function, which may simplify the codeeven more because you can program 'sequentially' where you wait for specific messages withoutloosing other intermediate messages. This BTAPI module does NOT make use of thisEVOS_Receive routine for the following reason:When making use of EVOS_Receive, you will have more then 1 'receive' function in theapplication, which makes it only suitable for multitasking environments. The goal for the sampleapplication making use of this BTAPI is that is should run in any environment where the stack isalso running,using similar (small) adaptations.
So this BTAPI module has build in state-machines, instead of making use of'sequential'programming. So the applications in the TestSample suite may have only 1 VOS_Receive call inits complete application.
BTAPI_ConnectRfcomm
Bluetooth PC Reference Stack by Ericsson
Page 184
Function: void BTAPI_ConnectRfcomm (TProcessAdminElement *ptProcessAdmin, MSG_TMsg **pptMsg, int16 *piResult);
Description: This routine creates an RFCOMM connection to the device with IEEE-address'ptConnectInfo->tAddress', and the first available server identified with the 'ptConnectInfo->uiServiceClass'. This routine starts this RFCOMM connection set-up session (a sequence ofrequests to the stack), where all following received messages will be handled in this BTAPImodule (via the BTAPI_HandleMsg routine) until this session sends the last request to the stack(COM_ReqConnect). After this last request, the messages will be handled in the application againwher the application should handle the reply on this last request (COM_CONNECT_CNF orCOM_CONNECT_CNF_NEG). When something goes wrong during this session, the BTAPImodule is de-activated via the BTAPI_HandleMsg routine, where this routine also returns thecorresponding error code. This function returns whether a state-machine is activated (TRUE) ornot (FALSE). This return value indicates whether BTAPI is activated or not after this function. Inthis case always TRUE is returned.
BTAPI_ HandleMsg
Function: boolean BTAPI_HandleMsg(MSG_TMsg **pptMsg, int16 *piResult)
Description: This routine handles the 'Msg' according the current activated BTAPI-function(session) and state within this BTAPI-function. The administration for this info is located in theglobal '_tProcessAdmin'. When after handling this 'Msg', this session is still active, TRUE will bereturned. When the handling of this message results in ending this session, FALSE will bereturned. When the session is ended (FALSE is returned), caused by a detected error, the 'Result'value will be filled with the error code (negative value) causing this error. Otherwise (session isended successfully) 'Result' will have a positive value. When the message is handled (expectedwithin the state of the BTAPI-function) it will be released by this BTAPI module.
BTAPI_ Init
Function: int16 BTAPI_Init (void)
Description: This routine initialises the BTAPI administration for the process calling this function.It simply adds this process to the global '_tProcessAdmin.' and clears this entry. When this issucceeded, TRUE will be returned. In case the global administration was full or when this processwas allready administrated, FALSE will be returned.
BTAPI_ InitStackForClient
Function: boolean BTAPI_InitStackForClient(BTAPI_TStackInitInfo *ptStackInitInfo)
Description: This routine contains the necessary initialisation commands to the stack, where thestack should be able to support a typical client application. Client means in this case anapplication which initiates a connection. This routine starts this init client session (a sequence ofrequests to the stack), where all following received messages will be handled in this BTAPImodule (via the BTAPI_HandleMsg routine) until this session sends the last request to the stack(HCI_ReqWriteVoiceSettings). After this last request, the messages will be handled in theapplication again where the application should handle the reply on this last request(HCI_WRITE_VOICE_SETTINGS_CNF or HCI_WRITE_VOICE_SETTINGS_CNF_NEG). Whensomething goes wrong during this session, the BTAPI module is de-activated via theBTAPI_HandleMsg routine, where this routine also returns the corresponding error code.
Bluetooth PC Reference Stack by Ericsson
Page 185
BTAPI_ Init Processes
Function: void BTAPI_InitProcesses(void)
Description: This routine initialises all stack processes in case of a single thread environment.
BTAPI_ InitStackForServer
Function: boolean BTAPI_InitStackForServer(BTAPI_TStackInitInfo *ptStackInitInfo)
Description: This routine contains the necessary initialisation commands to the stack, where thestack should be able to support a typical server application.REMARK: When running muliple servers in 1 device making use of this routine; the last one willdefine these settings. Server means in this case an application which waits for (accepts) aconnection. This routine starts this init server session (a sequence of requests to the stack),where all following received messages will be handled in this BTAPI module (via theBTAPI_HandleMsg routine) until this session sends the last request to the stack(HCI_ReqWriteVoiceSettings). After this last request, the messages will be handled in theapplication again where the application should handle the reply on this last request(HCI_WRITE_VOICE_SETTINGS_CNF or HCI_WRITE_VOICE_SETTINGS_CNF_NEG). Whensomething goes wrong during this session, the BTAPI module is de-activated via theBTAPI_HandleMsg routine, where this routine also returns the corresponding error code. Thisfunction returns whether a state-machine is activated (TRUE) or not (FALSE). This return valueindicates whether BTAPI is activated or not after this function. In this case always TRUE isreturned.
BTAPI_ RegisterProfile
Function: boolean BTAPI_RegisterProfile(BTAPI_TRegisterProfileInfo *ptProfileInfo)
Description: This routine registrates the indicated profile in 'ProfileInfo' in the SDP database.This routine starts this profile registration session (a sequence of requests to the stack), where allfollowing received messages will be handled in this BTAPI module (via the BTAPI_HandleMsgroutine) until this session sends the last request to the stack (COM_ReqFillPdl). After this lastrequest, the messages will be handled in the application again where the application shouldhandle the reply on this last request (COM_FILL_PDL_CNF or COM_FILL_PDL_CNF_NEG).When something goes wrong during this session, the BTAPI module is de-activated via theBTAPI_HandleMsg routine, where this routine also returns the corresponding error code. Thisfunction returns whether a state-machine is activated (TRUE) or not (FALSE). This return valueindicates whether BTAPI is activated or not after this function. In this case always TRUE isreturned.
BTAPI_ Start
Function: boolean BTAPI_Start(void)
Description: This routine should be the first routine called by an application, before starting tocommunicate to the stack! It starts the stack by sending a start request to the adapted layers(RFCOMM and SDP). This routine starts this start-up session (a sequence of requests to thestack), where all following received messages will be handled in this BTAPI module (via theBTAPI_HandleMsg routine) until this session sends the last request to the stack (COM_ReqStart).After this last request, the messages will be handled in the application again where the application
Bluetooth PC Reference Stack by Ericsson
Page 186
should handle the reply on this last request (COM_START_CNF or COM_START_CNF_NEG).When something goes wrong during this session, the BTAPI module is de-activated via theBTAPI_HandleMsg routine, where this routine also returns the corresponding error code. Thisfunction returns whether a state-machine is activated (TRUE) or not (FALSE). This return valueindicates whether BTAPI is activated or not after this function. In this case always TRUE isreturned.
6.2.2 BT profile support
Use the BTAPI_RegisterProfile() function in btapi.c to select a service record function. The actualservice routine for setting up the profile is implemented in profile.c.
This module contains all interface functions of the 'profile' component. For most profiles, aregistration routine is available. Missing profiles can easily be added by copying an existing profileroutine and adapt it to your wishes.
This module covers the following profiles:
• Dail-up networking
• Fax
• Headset
• LAN Access
• Serial Port
6.2.3 Enhanced VOS module
EVOS_ Init
Function: boolean EVOS_Init(uint16 uiQueueSize)
Description: This routine initialises the EVOS message queue for the process calling thisfunction. It allocates a queue administration able to store up to 'QueueSize' messages. Thisqueue administration will be cleared and administrated in the global '_tProcessAdmin.' When thisis succeeded, TRUE will be returned. In case the global administration was full or when thisprocess was already administrated, FALSE will be returned
EVOS_ Receive
Function: void *EVOS_Receive(const uint32 *pulSelect)
Description: This routine returns the oldest message according the message list, the Selectparameter, as it was send to this task.
6.2.3.1 EVOS_GetMsg
Function: MSG_TMsg *EVOS_GetMsg(void)
Bluetooth PC Reference Stack by Ericsson
Page 187
Description: This routine returns the oldest message from the message queue (FIFO), belongingto the calling process. This queue is maintained by EVOS.
6.2.3.2 EVOS_PutMsg
Function: void EVOS_PutMsg(MSG_TMsg *ptMsg)
Description: This routine inserts the ‘Msg’ in the EVOS queue, belonging to the calling process.
Bluetooth PC Reference Stack by Ericsson
Page 188
Bluetooth PC Reference Stack by Ericsson
Page 189
7. CHAT APPLICATION SUITE
Besides the earlier mentioned TestSample suite, also a Chat application suite is part of thispackage. These 2 applications have different scopes:
- TestSample application scope:This application is designed in such a way that it can run in several different environments(multitasking, single thread, message event handler), which gives the design someconstraints. This application is indeed running in several environments, where it is e.g. usedas a tool to check interoperability between the several environments.So the included TestSample application is a general application which is ported to run in awindows environment, which means that it is not recognisable as a specific windows type ofprogram.The focus of this application is also not to show a fancy user application, but the basicinteraction with the stack.
- Chat application scope:Because there was a need to show a ‘real’ application on top of the Stack, this chatapplication is developed. This application is designed as a windows program, which meansthat for each message popping up from the Stack, an event-handler can be programmed.You can see this application as an extra shell on top of the stack API which provides thewindows programmer a convenient event driven environment, where this application haschoosen to implement a chat application on top of it as an example.
If you want to develope applications for non-windows environments, making use of this PCreference stack, you can take the TestSample application as a guideline for the architecture touse. The same is true if you want to run your non-windows Bluetooth application on this PCreference stack, which is then used as a reference.If you want to develop a windows type of application on top of this PC reference stack, it is betterto take the cghat application as a start.
The chat application suite consists of 3 parts, which act as 3 separate applications (COM-clients)on top of the stack:
- Bluetooth neighbourhood
- Chat Client
- Chat Server
Via ‘Bluetooth neigbourhood’ the user can select de device from the Bluetooth neighbourhoodand select a service from the selected device. Now the user can make a connection to theselected service where ‘Chat Client’ application will startup on the initiating side and a ‘ChatServer’ application on the destination side.
7.1 Bluetooth neighbourhood
Bluetooth PC Reference Stack by Ericsson
Page 190
This application acts as the ‘SecurityManager’ on top of the stack (see SCM interface for detailsabout the security manager). The window is splitted into 2 main parts; client (left) + server (right)
The client (left) part contains functionality that is necessary at the client side of a connection(initiating side). Here you find functionality for device discovery and service discovery. The upperpart is able to discover all Bluetooth devices in the neighbourhood via the Inquiry button, whereaddress and name are displayed. From this list a device can be selected. In the lower part youcan request for a list of services in the selected device which results in an SDP session, retrievingall services from the remote device in a list. Now you can choose a service by selecting one fromthe list. After this selection you setup a session with the selected service by pressing the‘Connect’ button. Now the ‘Chat Client’ application will pop up.
The server (right) part contains functionality to registrate a server to the stack. In this applicationonly 1 server is implemented via a ‘Chat Service’ button; the Chat server. After pushing thisbutton, the Chat Server is registrated to the stack and can be discovered by another Bleutoothdevice.
7.2 Chat Client
Bluetooth PC Reference Stack by Ericsson
Page 191
The Chat Client window shows the connected service (device address + service name) and givesthe user a simple chatbox interface. In coming data from the remote server is prefixes with !<, andoutgoing data is prefixed with !>.This windows is activated when the ‘Connect’ butten is activated in the ‘Bleutooth Neighbourhood”window. The session can be stopped by pressing the ‘End Chat’ button in this window.
7.3 Chat Server
Bluetooth PC Reference Stack by Ericsson
Page 192
The Chat Server window shows the connected device (device address) + the name of its ownservice and gives the user a simple chatbox interface. In coming data from the remote server isprefixes with !<, and outgoing data is prefixed with !>.This windows is activated when somebody sets up an RFCOMM connection to it The session canbe stopped by pressing the ‘End Chat’ button in this window.
Bluetooth PC Reference Stack by Ericsson
Page 193
8. APPENDIX 1 - DELIVERY STRUCTURE
This release is delivered as an install shield, where you have to run ‘setup’ after unpacking thezip-file. This setup will also install the PC reference stack as a COM-server to your PC.The complete delivery is organised in a file structure with two main level folders, the BT_Chatfolder and the BT_TestSample folder. These contain the 2 examples of COM-clients asdescribed earlier. These 2 share some information, which are located in the following directorieson the same level:
• doc – The folder for the users manual and release notes.
• exp – Interface definitions which are necessary to communicate to the PC referencestack and some header files which are common to all COM-clients.
• lib – 2 libraries with interface routines to the PC reference stack.
The BT_TestSample folder contains the following sub-folders:
• exe – The samples executable files.
• project – The visual studio project files helps you to get an overview of the deliveredsoftware.
• sw – This folder contains the Stack interface files and is organised in the followingsub-folders.
• application – Sample applications organised in the following sub-folders.
• cmp - This folder consists of test sample suite. One is a BT server, one is aclient and the third as a security manager.
• exp – Export header files of the server, client and security manager
• support – Support function files
• cmp – Sub-folders with source code for all enhanced functionality used bythe sample application.
• exp - Export files for the support components.
The BT_Chat folder contains the following sub-folders:
• exe – The samples executable files.
• project – The visual studio project files helps you to get an overview of the deliveredsoftware.
• sw – This folder contains the Stack interface files and is organised in the followingsub-folders.
• client – Sample applications source code of BT chat client.
• security – Sample applications source code of BT chat security manager.
• server - Sample applications source code of BT chat server.
Bluetooth PC Reference Stack by Ericsson
Page 194
9. APPENDIX 2 – MSC TEST SAMPLE
This message chart shows the complete message sequence of the TestSample application suite,where all possible exeptions are not included otherwise the overview is lost. Due to the size of it,it is splitted into 3 parts which should be read as if they where sequentially connected. TheTestSample will perform an endless loop, starting after the ‘INIT’ part.
COMServer
SCM_ReqStart()
SCM_START_CNF
SCM_ReqRegister()SCM_SECURITY_HANDLER
SCM_REGISTER_CNF
BTAPI_Init() BTAPI_Init()
HCI_ReqConfigurePort() HCI_ReqConfigurePort()
HCI_CONFIGURE_PORT_CNF HCI_CONFIGURE_PORT_CNF
BTAPI_Start() BTAPI_Start()
COM_START_CNF INIT COM_START_CNF
SCM_ReqRegister() SCM_ReqRegister()SCM_VOICE_HANDLER SCM_VOICE_HANDLER
SCM_REGISTER_CNF SCM_REGISTER_CNF
SCM_ReqRegister()SCM_MONITOR_GROUP
SCM_REGISTER_CNF
BTAPI_InitStackForClient() BTAPI_InitStackForServer()
HCI_WRITE_VOICE_SETTINGS_CNF HCI_WRITE_VOICE_SETTINGS_CNF
BTAPI_RegisterProfile()
COM_FILL_PDL_CNF
HCI_ReqInquiry()
HCI_INQUIRY_EVT
DISCOVERY HCI_INQUIRY_EVT +
DATA CONNECTHCI_INQUIRY_CNF
BTAPI_ConnectRfcomm() SCM_CONNECT_ACCEPT_IND
SCM_RspConnectAccept()
COM_PARAMETER_NEGOTIATION_IND
COM_RspParameterNegotiation()
COM_CONNECT_IND
COM_CONNECT_CNF COM_RspConnect()
StackAPILIB
StackAPILIB
BTAPIBT_TestSample
ServerBT_TestSample
SecurityBTAPI
StackAPI StackAPIBTAPI BT_TestSampleS
BT_TestSampleS iBTAPI
BT_TestSampleClient
BT_TestSampleCli
Bluetooth PC Reference Stack by Ericsson
Page 195
COM_DataAlloc()
COM_DataSend() COM_DATA_IND"who are you?"
COM_DATA_CNF COM_DataExtract()
QUESTION COM_RspData()
+ANSWER COM_DataAlloc()
COM_DATA_IND COM_DataSend()"headset"
COM_DataExtract()
COM_RspData()
SCM_ReqAddSco() SCM_ADD_SCO_ACCEPT_IND
VOICESCM_ADD_SCO_CNF CONNECT SCM_RspAddScoAccept()
SCM_ADD_SCO_EVT
COM_DataAlloc()
COM_DataSend() COM_DATA_IND
COM_DATA_CNF COM_DataExtract()
SMALL COM_RspData()
DATAPACKET COM_DataAlloc()
(1 byte)COM_DATA_IND COM_DataSend()
COM_DataExtract() COM_DATA_CNF
COM_RspData()
StackAPILIB
StackAPILIB
BTAPIBT_TestSample
ServerBT_TestSample
SecurityBTAPIBT_TestSample
Client
Bluetooth PC Reference Stack by Ericsson
Page 196
COM_DataAlloc()
COM_DataSend() COM_DATA_IND
COM_DATA_CNF COM_DataExtract()
LARGE COM_RspData()
DATAPACKET COM_DataAlloc()
(1000 byte)COM_DATA_IND COM_DataSend()
COM_DataExtract() COM_DATA_CNF
COM_RspData()
SCM_ReqRemoveSco() SCM_REMOVE_SCO_EVT
SCM_REMOVE_SCO_CNF
COM_ReqDisconnect() COM_DISCONNECT_EVT
COM_DISCONNECT_CNF
SCM_ReqDisconnect() DISCONNECT SCM_DISCONNECT_EVT
SCM_DISCONNECT_CNF
DBM_ReqUnregisterService()
DBM_UNREGISTER_SERVICE_CNF
StackAPILIB
StackAPILIB
BTAPIBT_TestSample
ServerBT_TestSample
SecurityBTAPIBT_TestSample
Client
Bluetooth PC Reference Stack by Ericsson
Page 197
10. APPENDIX 3 – SDC EXAMPLES
10.1 Appendix 3.A : Example Service Attribute
See also the SDP-specification in [1], SDP example 2 Service Attribute.Note : This is a rather difficult way to get attribute values, but with the support functionSD_GetValue the user can obtain a particular value easily using a query.
10.2 Appendix 3.B : Example (Service Search Attribute)
This function returns an list of attribute-lists. See for the structure of an attributelist Appendix 3.A.The complete list of attribute-lists are preceded by a type SD_DET_SEQUENCE8/16/32 and fieldfor the length of this complete list of attributelists.
AttributeList :
tType :- SD_detSequence8/16/32- Additional 8/16/32 bits indicating length of list
FIRST ATTRIBUTE (Service Record Handle) :
AttrID : tType = SD_DET_UINT16, Value = 0x0000 AttrValue : tType = SD_DET_UINT32, Value = 32 bits value
SECOND ATTRIBUTE (Protocol Descriptor List, PDL) :
AttrID : tType = SD_DET_UINT16, Value = 0x0004 AttrValue : tType: SD_DET_SEQUENCE8/16/32 - Additional 8/16/32 bits indicating length of PDL tType: SD_DET_SEQUENCE8/16/32 - Additional 8/16/32 bits indicating length of Descriptor L2CAP tType : SD_DET_UUID32, Value = L2CAP UUID 32 bits tType:SD_DET_SEQUENCE8/16/32 - Additional 8/16/32 bits indicating length of Descriptor RFCOMM tType : SD_DET_UUID32, Value = RFCOMM 32 bits tType : SD_DET_UINT8, Value = Serverchannel 1
Bluetooth PC Reference Stack by Ericsson
Page 198
You can use support functions SD_GetNrOfAttributeLists, SD_GetAttributeList andSD_GetServiceRecord returned list of attribute-lists.
10.3 Appendix 3.C : Example (SearchPattern)The SearchPatternList (parameter of the function SD_ReqServiceSearch) is a data elementsequence where each element in the sequence is a UUID. The sequence must contain at leastone UUID. The maximum number of UUIDs in the sequence is 12. The list of UUIDs constitutesa service search pattern.The following example shows how a SearchPatternList should be filled if an application want tosearch for a Bluetooth device that supports the Headset-profile :First, there are 3 UUID-types (from Table 5-51 : Struct TDataElement in SDC) :- SD_DET_UUID16- SD_DET_UUID32- SD_DET_UUID128You can find in Bluetooth Assigned Numbers Document in [1] that the ServiceClass of Headset isa UUID16, so in sourcecode it will look something like :
Example: SearchPatternList/* Declaration */SD_TUuid *ptSearchPatternList;uint8 ucNrOfUuids = 1;
/* Do memory allocation*/ptSearchPatternList = (SD_TUuid*)VOS_Alloc((uint16)(ucNrOfUuids * sizeof(SD_TUuid)));
/* Assign values Headset Service Class */ptSearchPatternList[0].eUuidType = SD_detUUID16;ptSearchPatternList[0].TUuid.uiUuid16 = 0x1108;
This will result in a possible return of those recordhandles that match this pattern of the HeadsetService Class.If the application wants to extend the search pattern with an extra service class, say GenericAudio Service Class, then this will return in a possible return of only those recordhandles thatmatch the pattern of BOTH Headset AND Generic Audio Service Class. So a returnedrecordhandle belongs to a Service Record that contain BOTH Service Classes an not only one ofthem!
Bluetooth PC Reference Stack by Ericsson
Page 199
11. APPENDIX 4 – DBM EXAMPLES
11.1.1 Example of generating a typical DBM database service recordThis Appendix shows the creation (in c-code) of a typical service record as defined in the severalBluetooth Profiles. The example covers the Headset Service Record. In 11.1.2 more examples ofother attributes are given.
Headset Service Record
Notes :
• The Headset Profile Document in [1] should be referenced to verify the example• Typical defines for AttributeID’s or UUID’s are located in the ‘Bluetooth Defined Numbers
Document’ ( [1] ). Therefor, if an application wants to create a service record, one mustalways have this document present to obtain the specific numbers for his particular servicerecord.
• The example contains the demonstrative value of 0 for the SeqNr, that is required for eachfunction
• Throughout the code the functions VOS_Free(..) and VOS_Alloc(..), are used for allocatingand freeing memory.
• Throughout the code local variables are used. Some are struct variables and are mentionedhere : tDescriptorUUID is of type DBM_TDescriptorUuid and tDescriptor is of typeDBM_TDescriptorValue.
• Attributes that have the following types : DBM_DET_STRING8, DBM_DET_STRING16,DBM_DET_STRING32, DBM_DET_SEQUENCE8, DBM_DET_SEQUENCE16,DBM_DET_SEQUENCE32, DBM_DET_ALTERNATIVE8, DBM_DET_ALTERNATIVE16,DBM_DET_ALTERNATIVE32, DBM_DET_URL8 DBM_DET_URL16 or DBM_DET_URL32should contain an additional 8/16/32 bits with the length of the actual value. These bitfieldsshould precede the actual value. See in the example the ServiceName attribute forclarification.
• If the function DBM_ReqAddDescriptor wants to add a descriptor to an attribute that does notyet exist, then the attribute is created immediately.
• For the Headset, the ProtocolDescriptorList attribute is filled in this example. Usually, this isdone by the different protocols themselves. In the BT Stack this done by the functionsCOM_ReqFillPdl() and L2CA_ReqFillPdl().
• The code contains a macro for the following attribute BT_SERVICE_NAME(0).This macro contains offsetvalue 0 to indicate that it’s attribute 0x0100 (see[1]). If for example the Service Description Attribute should be added toDBM, then offset 1 is chosen : BT_SERVICE_DESCRIPTION(1)
Example: Add Headset Service Record via DBM/* Create the HEADSET Service Record */DBM_ReqRegisterService (0, DBM_ServiceDiscoveryDB);ptRegisterServiceCnf = (DBM_TRegisterServiceCnf *) ptMsg;ulDbmHandle = ptRegisterServiceCnf->ulDbmHandle;
/*** Add Descriptor ServiceClass 0 UUID Generic Audio ******************/uiAttributeId = BT_SERVICE_CLASS_ID_LIST; /* AttributeId : see [1] */uiUUIDValue = 0x1203; /* ServiceClass 0 UUID Generic Audio */tDescriptorUUID.tType = DBM_DET_UUID16;tDescriptorUUID.pucDescriptorUuidValue = (uint8 *) VOS_Alloc(sizeof(uint16));memcpy(tDescriptorUUID.pucDescriptorUuidValue, &uiUUIDValue,sizeof(uint16));tDescriptor.uiNrOfParams = 0;tDescriptor.uiSizeOfValueInBytes = 0;tDescriptor.pucValue = NULL;
DBM_ReqAddDescriptor (0, ulDbmHandle, uiAttributeId, &tDescriptorUUID, &tDescriptor);VOS_Free((void**) &tDescriptorUUID.pucDescriptorUuidValue);
Bluetooth PC Reference Stack by Ericsson
Page 200
/*** Add Descriptor ServiceClass 1 UUID Headset ************************/uiAttributeId = BT_SERVICE_CLASS_ID_LIST; /* AttributeId : see [1] */uiUUIDValue = 0x1108; /* ServiceClass 1 UUID Headset */tDescriptorUUID.tType = DBM_DET_UUID16;tDescriptorUUID.pucDescriptorUuidValue = (uint8 *) VOS_Alloc(sizeof(uint16));memcpy(tDescriptorUUID.pucDescriptorUuidValue, &uiUUIDValue, sizeof(uint16));tDescriptor.uiNrOfParams = 0;tDescriptor.uiSizeOfValueInBytes = 0;tDescriptor.pucValue = NULL;
DBM_ReqAddDescriptor (0, ulDbmHandle, uiAttributeId, &tDescriptorUUID, &tDescriptor);VOS_Free((void**) &tDescriptorUUID.pucDescriptorUuidValue);
/*** Add Descriptor Protocol 1 (RFCOMM) UUID Headset **************/uiAttributeId = BT_PROTOCOL_DESCRIPTOR_LIST; /* AttributeId : see [1] */uiUUIDValue = BT_UUID_RFCOMM; /* Protocol 1 UUID RFCOMM */tDescriptor.tType = DBM_DET_UUID16;tDescriptor.pucDescriptorUuidValue = (uint8*) &uiUUIDValue;tDescriptorValue.uiNrOfParams = 1;tDescriptorValue.uiSizeOfValueInBytes = 2;tDescriptorValue.pucValue = (uint8 *) VOS_Alloc( (sizeof(uint16)));*tDescriptorValue.pucValue = DBM_DET_UINT8;tDescriptorValue.pucValue++;*tDescriptorValue.pucValue = tRFComm->ucServerChannel;tDescriptorValue.pucValue--;
DBM_ReqAddDescriptor(0, ulDbmHandle, &tDescriptor, &tDescriptorValue);VOS_Free((void **)&tDescriptorValue.pucValue);
/*** Add Descriptor Protocol 1 (L2CAP) UUID Headset **************/uiAttributeId = BT_PROTOCOL_DESCRIPTOR_LIST;/* AttributeId : see [1] */uiUUIDValue = BT_UUID_L2CAP; /* Protocol 1 UUID L2CAP */tDescriptor.tType = DBM_DET_UUID16;tDescriptor.pucDescriptorUuidValue = (uint8*) &uiUUIDValue;
tDescriptorValue.uiNrOfParams = 0;tDescriptorValue.uiSizeOfValueInBytes = 0;tDescriptorValue.pucValue = NULL;
VOS_Free((void **)&tDescriptorValue.pucValue);
/*** Add Descriptor BT Profile Descriptor List Profile 0 ***************/uiAttributeId = BT_BLUETOOTH_PROFILE_DESCRIPTOR_LIST;/* AttributeId : see [1]*/uiUUIDValue = 0x1108; /* Profile 0 UUID Headset */tDescriptorUUID.tType = DBM_DET_UUID16;tDescriptorUUID.pucDescriptorUuidValue = (uint8 *) VOS_Alloc(sizeof(uint16));memcpy(tDescriptorUUID.pucDescriptorUuidValue, &uiUUIDValue, sizeof(uint16));tDescriptor.uiNrOfParams = 1;tDescriptor.uiSizeOfValueInBytes = 3;tDescriptor.pucValue = (uint8 *) VOS_Alloc(tDescriptor.uiSizeOfValueInBytes );*tDescriptor.pucValue = DBM_DET_UINT16;tDescriptor.pucValue++;uiValue = 0x0100;memcpy(tDescriptor.pucValue, &uiValue, (sizeof(uint16)));tDescriptor.pucValue--;DBM_ReqAddDescriptor (0, ulDbmHandle, uiAttributeId, &tDescriptorUUID, &tDescriptor);VOS_Free((void**) &tDescriptor.pucValue);VOS_Free((void**) &tDescriptorUUID.pucDescriptorUuidValue);
/*** Add Attribute Service Name *************************/uiAttributeId = BT_SERVICE_NAME(0);/* AttributeId with Offset 0 : see [1]*/tAttribute.tType = DBM_DET_STRING8;ucLength = strlen(pcString);tAttribute.pucValue = (uint8 *) VOS_Alloc( (sizeof(uint8) + ucLength);/* pucValue should first contain the length of the string : see also *//* the notes and [1] ! *//* sizeof(uint8) indicates the byte (additional bitfield) for this length */*tAttribute.pucValue = ucLength;tAttribute.pucValue++;memcpy(tAttribute.pucValue, pcString, (uint16)ucLength);tAttribute.pucValue--;
DBM_ReqAddAttribute (0, ulDbmHandle, uiAttributeId, &tAttribute);VOS_Free((void**) &tAttribute.pucValue);
/*** Add Attribute Remote Audio Volume Control *************************/uiAttributeId = BT_REMOTE_AUDIO_VOLUME_CONTROL;/* AttributeId : see [1]*/
Bluetooth PC Reference Stack by Ericsson
Page 201
tAttribute.tType = DBM_DET_BOOLEAN;uiValue = FALSE;tAttribute.pucValue = (uint8 *) VOS_Alloc(sizeof(uint16));memcpy(tAttribute.pucValue, &uiValue, sizeof(uint8));DBM_ReqAddAttribute (0, ulDbmHandle, uiAttributeId, &tAttribute);VOS_Free((void**)&tAttribute.pucValue);
11.1.2 Examples of other attributes
Example: Add Headset Service Record via DBM
/* Add BrowseGroupList attribute *************************//* Assign */uiAttributeId = BT_BROWSE_GROUP_LIST; /* see bt.h */uiUuidValue = 0x1002; /* Public BrowseGroup Uuid -> see Bluetooth Assigned numbersdocument */tDescriptorUuid.tType = DBM_DET_UUID16;tDescriptorUuid.pucDescriptorUuidValue = (uint8*) &uiUuidValue;tDescriptor.uiNrOfParams = 0;tDescriptor.uiSizeOfValueInBytes = 0 ;tDescriptor.pucValue = NULL;
/* Add to this particular DbmHandle (service record) */DBM_ReqAddDescriptor (uiSeqNr, ulDbmHandle, uiAttributeId, &tDescriptorUuid,&tDescriptor);
/* Free memory */VOS_Free((void**)& tDescriptorUuid.pucDescriptorUuidValue);
/* Add External Network attribute *************************/uiAttributeId = BT_EXTERNAL_NETWORK;/* AttributeId : see [1]*/tAttribute.tType = DBM_DET_UINT8;ucValue = 0x02; /* ISDN */tAttribute.pucValue = (uint8 *) &ucValue ;
DBM_ReqAddAttribute (0, ulDbmHandle, uiAttributeId, &tAttribute);VOS_Free((void**)&tAttribute.pucValue);
/*** Add Language Base Attribute Id List Attribute *************************/uiAttributeId = BT_LANGUAGE_BASE_ATTRIBUTE_ID_LIST;/* AttributeId : see [1]*/
/* The languagebase attributeidlist consists in this example of the folowing */ /*information (triplets) *//* - 0x09 0x656E : Uint16 “en” (English) *//* - 0x09 0x006A : Uint16 UFT-8 encoding *//* - 0x09 0x0100 : Uint16 PrimaryLanguageBaseId */
tAttribute.tType = DBM_DET_SEQUENCE8;pcLanguageBase = “096E65096A00090001”; /* memory in Little Endian */ucLength = strlen(pcLanguageBase);tAttribute.pucValue = (uint8 *) VOS_Alloc( (sizeof(uint8) + ucLength);/* pucValue should first contain the length of the Sequence : see also *//* the notes and [1] ! *//* sizeof(uint8) indicates the byte (additional bitfield) for this length */*tAttribute.pucValue = ucLength;tAttribute.pucValue++;memcpy(tAttribute.pucValue, pcLanguageBase, (uint16)ucLength);tAttribute.pucValue--;DBM_ReqAddAttribute (0, ulDbmHandle, uiAttributeId, &tAttribute);
VOS_Free((void**) &tAttribute.pucValue);
/*** Add Service Description Attribute *************************/uiAttributeId = BT_SERVICE_DESCRIPTION(1);/* AttributeId with Offset 1 : see [1]*/tAttribute.tType = DBM_DET_STRING8;ucLength = strlen(pcString);tAttribute.pucValue = (uint8 *) VOS_Alloc( (sizeof(uint8) + ucLength);/* pucValue should first contain the length of the string : see also *//* the notes and [1] ! *//* sizeof(uint8) indicates the byte (additional bitfield) for this length */*tAttribute.pucValue = ucLength;tAttribute.pucValue++;
Bluetooth PC Reference Stack by Ericsson
Page 202
memcpy(tAttribute.pucValue, pcString, (uint16)ucLength);tAttribute.pucValue--;DBM_ReqAddAttribute (0, ulDbmHandle, uiAttributeId, &tAttribute);
VOS_Free((void**) &tAttribute.pucValue);
/*** Add Service Availability Attribute *************************/See External Network attribute (also of type Uint8)
/*** Add Client Executable Url Attribute *************************/Client Executable Url attribute is of type DBM_DET_URL8. See ServiceName attribute(same structure as of type DBM_DET_STRING). See also [1].
/*** Add Documentation Url Attribute *************************/Documentation Url attribute is of type DBM_DET_URL8. See ServiceName attribute (samestructure as of type DBM_DET_STRING). See also [1].
/*** Add Icon Url Attribute *************************/Icon Url attribute is of type DBM_DET_URL8. See ServiceName attribute (same structureas of type DBM_DET_STRING). See also [1].
/*** Add Supperted Fornat List Attribute *************************/See LanguageBaseAttributeIdList attribute (also of type Sequence)
/*** Add Supperted Data Stores List Attribute *************************/See LanguageBaseAttributeIdList attribute (also of type Sequence)
/*** Add Audio Feedback Support Attribute *************************/See Headset example for Remote Audio Volume Control attribute (also of type Boolean)
/*** Add Fax Class 1 Attribute *************************/See Headset example for Remote Audio Volume Control attribute (also of type Boolean)
/*** Add Fax Class 2.0 Attribute *************************/See Headset example for Remote Audio Volume Control attribute (also of type Boolean)
/*** Add Fax Class 2 Attribute *************************/See Headset example for Remote Audio Volume Control attribute (also of type Boolean)