bluestack user manual - pudn.comread.pudn.com/downloads164/sourcecode/unix_linux/...bluestack user...

BlueStack User Manual

BlueStack User Manual C6066-UM-001 v1.6

General Information

© 2001 2

General InformationOwnership of Information

© Mezoe 2001 (Mezoe is a division of Cambridge Consultants Ltd)

All information contained in this document is owned by Mezoe and should not be copied or reused for anypurpose.

Trademarks

BlueStack® is a trademark of Mezoe that is registered in the United Kingdom

StackPrimer is a trademark of Mezoe

Proto Developer is a trademark of Mezoe

Interface Express is a trademark of Mezoe

Mezoe is a trademark of Cambridge Consultants Ltd.

CCL is a trademark of Cambridge Consultants Ltd that is registered in the United Kingdom and Germany

Bluetooth is a trademark owned by the Bluetooth SIG, Inc. and used by Mezoe under license

Bluecore is a trademark of Cambridge Silicon Radio

All other trademarks are acknowledged as owned by their respective proprietors

Confidentiality

This document contains confidential information that is proprietary to Mezoe. This information must onlybe used for its intended purpose and should not be disclosed to third parties.

Fitness for Purpose and Liability

Mezoe makes no warranty of any kind with regard to the information contained in this document,expressed or implied, including but not limited to implied warranties of fitness for purpose or satisfactoryquality. Mezoe does not warrant that the Software to which this document refers or this documentitself is error free or suitable for use in safety-critical applications. The user shall take fullresponsibility for ensuring that the Software and the document is suitable for the user’s intended purposesand for its subsequent use.

Mezoe does not accept any liability for any loss or damage arising from the use of this document or theinformation within it, howsoever caused, including but not limited to direct, indirect, unforeseen orconsequential loss or damage, other than death or personal injury resulting from Mezoe’s provennegligence.

Contact Mezoe

Mezoe,Cambridge Consultants LtdScience parkMilton RoadCambridge CB4 0DWUKTel. +44 (0) 1223 425093Fax. +44 (0) 1223 392323Email [email protected]

mailto:[email protected]

http://www.mezoe.com/


Contents

© 2001 3

ContentsContents 3List of Figures 11List of Tables 12

1 Introduction 151.1 Audience 151.2 In This Document 151.2.1 About this Manual 151.2.2 Finding Your Way Around 151.3 Conventions 161.3.1 Getting More Information 17

2 Overview 182.1 Introducing BlueStack 182.2 BlueStack as a Software Component 192.2.1 Standard Two-Processor Solution 222.2.2 Embedded Two-Processor Solution 222.2.3 Wholly Embedded Solution 222.3 The Application Interface to BlueStack 232.3.1 Scheduler and BlueStack Initialisation 232.3.2 Memory Management Functions 242.3.3 HCI Transport Driver Configuration 242.3.4 Scheduler Services 252.4 BlueStack Layers 262.4.1 Link Manager 262.4.2 L2CAP 262.4.3 Device Manager 262.4.4 Service Discovery 272.4.5 RFCOMM 272.4.6 TCS Binary 282.4.7 Host Controller Interface 292.5 Internal Communications Model Adopted for BlueStack 292.5.1 Interface Library Functions 322.5.2 Registration and phandles 332.6 Error Handling and Debug Facilities 342.7 Management Entity 342.8 Partitioning 362.9 Porting and Building 36

3 BlueStack Application Interface 373.1 Overview 373.2 Key Concepts 383.2.1 The Scheduler 383.2.2 Inter-process Communication, Messaging and Events 393.2.3 Communications Services 403.2.4 Timed Events 413.3 Configurability and Tuners 413.4 Application Interface Functions – Initialisation 423.4.1 BST_InitScheduler 423.4.2 BST_ConfigureStack 423.4.3 BST_StartScheduler 433.4.4 BST_sched_protect_tasks 443.4.5 BST_ReconfigurePool 44


Contents

© 2001 4

3.4.6 BST_InitHCIdrv 453.4.7 BST_HCIdrv_enum_drivers 463.4.8 BST_HCIdrv_select_driver 473.4.9 BST_HCIdrv_get_current_driver 473.4.10 BST_HCIdrv_query_driver_available 483.4.11 BST_HCIdrv_get_driver_name 483.4.12 BST_HCIdrv_get_driver_description 493.4.13 BST_HCIdrv_get_driver_id 493.5 Application Interface Functions – Scheduler Services 503.5.1 BST_putMessage 503.5.2 BST_getMessage 513.5.3 BST_put_message_at 513.5.4 BST_put_message_in 523.5.5 BST_cancel_timed_message 533.5.6 BST_timed_event_at 543.5.7 BST_timed_event_in 553.5.8 BST_cancel_timed_event 553.5.9 BST_get_time 563.5.10 BST_sched_claim_task_mutex 563.5.11 BST_sched_release_task_mutex 573.5.12 BST_CallbackOnPanic 573.6 Application Interface Functions – Memory Management 583.6.1 BST_pmalloc 583.6.2 BST_pfree 583.6.3 BST_zpmalloc 593.6.4 BST_xpmalloc 593.6.5 BST_xzpmalloc 593.6.6 BST_RFC_DLC_malloc 603.6.7 BST_prealloc 603.6.8 BST_xprealloc 613.6.9 BST_pcopy 623.6.10 BST_xpcopy 623.6.11 BST_pstrdup 633.6.12 BST_xpstrdup 633.7 Application Interface Functions – Utilities 643.7.1 bd_addr_copy 643.7.2 bd_addr_zero 643.7.3 bd_addr_eq 653.7.4 BST_ReportPoolStats 653.7.5 BST_ReportPoolUsage 663.7.6 BST_SendWatchText 663.7.7 BST_send_watch_text 673.7.8 BST_get_config_string 683.7.9 BST_get_scheduler_identifier 683.8 Usage Scenarios and Examples 693.8.1 Scheduler and BlueStack Initialisation 693.8.2 Sending Messages 713.8.3 Getting Messages 713.8.4 Callback on Panic 71

4 RFCOMM 724.1 Overview 724.2 Key Concepts 734.2.1 Mux ID 744.2.2 Local Server Channel 74


Contents

© 2001 5

4.2.3 RFCOMM Flow Control 744.3 Configurability and Tuners 784.4 RFCOMM API Primitives 794.4.1 RFC_INIT 794.4.2 RFC_REGISTER 804.4.3 RFC_START 814.4.4 RFC_STARTCMP 834.4.5 RFC_CLOSE 854.4.6 RFC_PARNEG 864.4.7 RFC_ESTABLISH 884.4.8 RFC_RELEASE 904.4.9 RFC_CONTROL 914.4.10 RFC_PORTNEG 934.4.11 RFC_FCON 964.4.12 RFC_FCOFF 974.4.13 RFC_DATA 984.4.14 RFC_DATAWRITE 994.4.15 RFC_LINESTATUS 1004.4.16 RFC_TEST 1014.4.17 RFC_NSC 1024.5 Usage Scenarios and Examples 1034.5.1 Starting and Configuring a Multiplexer Session – As an Initiator 1034.5.2 Starting and Configuring a Multiplexer Session – As a Recipient 1054.5.3 Opening a Server Channel and Negotiating Parameters 107

5 Service Discovery Protocol 1115.1 Overview of SDP and its API 1115.1.1 Service Discovery Client (SDC) Interface 1115.1.2 Service Discovery Server (SDS) Interface 1125.2 Key Concepts within SDP 1125.2.1 Service Record Formats 1125.3 Configurability and Tuners 1155.4 SDP API Primitives– SDC 1165.4.1 SDC_SERVICE_SEARCH 1165.4.2 SDC_SERVICE_ATTRIBUTE 1185.4.3 SDC_SERVICE_SEARCH_ATTRIBUTE 1195.4.4 SDC_TERMINATE_PRIMITIVE 1205.4.5 SDC_OPEN_SEARCH 1215.4.6 SDC_CLOSE_SEARCH 1225.4.7 SDC_CONFIG 1225.5 SDP API Primitives– SDS 1235.5.1 SDS_REGISTER 1235.5.2 SDS_UNREGISTER 1245.5.3 SDS_CONFIG 1245.6 Usage Scenarios and Examples 1255.6.1 Service Registration 1255.6.2 Service Search Request 1295.6.3 Service Attribute Request 132

6 TCS 1366.1 Overview 1366.2 Key Concepts 1396.2.1 Attach 1396.2.2 SCO Bearer Call Management 1396.2.3 Connectionless Call Management 140


Contents

© 2001 6

6.2.4 Group Management 1416.2.5 Memory Management 1426.2.6 TCS Constraints 1426.2.7 Race Conditions / Multiple Resources 1436.3 Configurability and Tuners 1436.4 TCS API Primitives 1446.4.1 TCS_REGISTER 1446.4.2 TCS_UNREGISTER 1456.4.3 TCS_ATTACH 1466.4.4 TCS_PREATTACH 1486.4.5 TCS_DETACH 1496.4.6 TCS_SETUP 1506.4.7 TCS_CL_SETUP 1546.4.8 TCS_INFO 1586.4.9 TCS_CALL_PROCEEDING 1616.4.10 TCS_ALERTING 1636.4.11 TCS_OPEN_SCO 1656.4.12 TCS_CONNECT 1676.4.13 TCS_PROGRESS 1696.4.14 TCS_DISCONNECT 1706.4.15 TCS_RELEASING 1726.4.16 TCS_RELEASED 1746.4.17 TCS_CL_RELEASE 1766.4.18 TCS_CL_RELEASED 1786.4.19 TCS_START_DTMF 1796.4.20 TCS_STOP_DTMF 1816.4.21 TCS_ACCESS_RIGHTS 1826.4.22 TCS_WUG_INFO 1846.4.23 TCS_LISTEN_REQUEST 1866.4.24 TCS_LISTEN_SUGGEST 1886.4.25 TCS_LISTEN_QUERY 1906.4.26 TCS_CL_INFO 192

7 L2CAP 1947.1 Overview of L2CAP and its API 1947.2 Key Concepts 1957.2.1 PSM 1957.2.2 CID 1957.2.3 MTU 1957.2.4 RTX 1957.2.5 ERTX 1967.3 Configurability and Tuners 1967.4 L2CAP API Primitives 1977.4.1 L2CA_REGISTER 1977.4.2 L2CA_CONNECT 1987.4.3 L2CA_CONFIG 2007.4.4 L2CA_DATAWRITE 2027.4.5 L2CA_DATAREAD 2037.4.6 L2CA_DISCONNECT 2047.4.7 L2CA_TIMEOUT 2057.4.8 L2CA_QOSVIOLATION 2057.4.9 L2CA_PING 2067.4.10 L2CA_GETINFO 2077.4.11 L2CA_GROUP_CREATE 2087.4.12 L2CA_GROUP_CLOSE 209


Contents

© 2001 7

7.4.13 L2CA_ENABLE_CONNECTIONLESS 2107.4.14 L2CA_DISABLE_CONNECTIONLESS 2107.5 Usage Scenarios and Examples 2117.5.1 Registration 2117.5.2 Connection Establishment and Configuration–Outgoing 2127.5.3 Connection Establishment and Configuration–Incoming 2147.5.4 Data Transfer 2167.5.5 Disconnection – Local Initiation 2177.5.6 Disconnection – Remote Initiation 217

8 Device Manager 2198.1 Overview 2198.2 Key Concepts 2208.2.1 Device Discoverability and Inquiry 2218.2.2 Security Manager 2218.2.3 Link Policy 2228.2.4 ACL Link Management 2238.2.5 SCO Flow Control 2248.2.6 Local Name 2258.2.7 Parameter Caching 2258.3 Configurability and Tuners 2258.4 Device Manager API Primitives – General 2258.5 Device Manager API Primitives – Application Manager Related 2268.5.1 DM_AM_REGISTER 2268.5.2 DM_WRITE_CACHED_PAGE_MODE 2278.5.3 DM_WRITE_CACHED_CLOCK_OFFSET 2288.5.4 DM_CLEAR_PARAM_CACHE 2298.6 Device Manager API Primitives – Link Control 2308.6.1 DM_HCI_INQUIRY 2308.6.2 DM_HCI_INQUIRY_RESULT 2318.6.3 DM_HCI_INQUIRY_COMPLETE 2328.6.4 DM_HCI_INQUIRY_CANCEL 2338.6.5 DM_HCI_INQUIRY_CANCEL_COMPLETE 2338.6.6 DM_HCI_CHANGE_PACKET_TYPE 2348.6.7 DM_HCI_CHANGE_LINK_KEY 2358.6.8 DM_HCI_MASTER_LINK_KEY 2358.6.9 DM_HCI_REMOTE_NAME_REQUEST 2368.6.10 DM_HCI_READ_REMOTE_FEATURES 2368.6.11 DM_HCI_READ_REMOTE_VERSION 2378.6.12 DM_HCI_READ_CLOCK_OFFSET 2378.6.13 DM_HCI_REMOTE_NAME_COMPLETE 2388.7 Device Manager API Primitives – Link Policy 2398.7.1 DM_SET_DEFAULT_LINK_POLICY 2398.7.2 DM_HCI_WRITE_LP_SETTINGS 2408.7.3 DM_HCI_WRITE_LP_SETTINGS_COMPLETE 2418.7.4 DM_HCI_READ_LP_SETTINGS 2428.7.5 DM_HCI_READ_LP_SETTINGS_COMPLETE 2428.7.6 DM_HCI_PARK_MODE 2438.7.7 DM_HCI_EXIT_PARK_MODE 2448.7.8 DM_HCI_HOLD_MODE 2458.7.9 DM_HCI_SNIFF_MODE 2468.7.10 DM_HCI_EXIT_SNIFF_MODE 2478.7.11 DM_HCI_ROLE_DISCOVERY 2488.7.12 DM_HCI_SWITCH_ROLE 248


Contents

© 2001 8

8.8 Device Manager API Primitives – Host Controller and Baseband 2498.8.1 DM_HCI_CHANGE_LOCAL_NAME 2498.8.2 DM_HCI_CHANGE_LOCAL_NAME_COMPLETE 2498.8.3 DM_HCI_WRITE_SCAN_ENABLE 2508.8.4 DM_HCI_WRITE_CURRENT_IAC_LAP 2518.8.5 DM_HCI_FLUSH 2528.8.6 DM_HCI_READ_AUTO_FLUSH_TIMEOUT 2528.8.7 DM_HCI_WRITE_AUTO_FLUSH_TIMEOUT 2538.8.8 DM_HCI_READ_TX_POWER_LEVEL 2548.8.9 DM_HCI_READ_SCO_FLOW_CONTROL_ENABLE 2558.8.10 DM_HCI_WRITE_SCO_FLOW_CONTROL_ENABLE 2558.8.11 DM_HCI_READ_LINK_SUPERV_TIMEOUT 2568.8.12 DM_HCI_WRITE_LINK_SUPERV_TIMEOUT 2568.9 Device Manager API Primitives – Status Parameters 2578.9.1 DM_HCI_FAILED_CONTACT_COUNTER 2578.9.2 DM_HCI_RESET_CONTACT_COUNTER 2578.9.3 DM_HCI_GET_LINK_QUALITY 2588.9.4 DM_HCI_READ_RSSI 2588.10 Device Manager API Primitives – SCO Control Related 2598.10.1 DM_SCO_INCOMING_REGISTER 2598.10.2 DM_SCO_INCOMING_UNREGISTER 2608.10.3 DM_SCO_CONNECT 2618.10.4 DM_SCO_DISCONNECT 2628.10.5 DM_SCO_BUFFER_SIZE 2638.10.6 DM_SCO_ DATA_SENT 2648.11 Device Manager API Primitives – Security Manager Related 2658.11.1 DM_SM_PIN_REQUEST 2658.11.2 DM_SM_LINK_KEY_REQUEST 2668.11.3 DM_SM_SET_DEFAULT_SECURITY 2678.11.4 DM_SM_REGISTER 2688.11.5 DM_SM_REGISTER_OUTGOING 2698.11.6 DM_SM_UNREGISTER 2708.11.7 DM_SM_UNREGISTER_OUTGOING 2718.11.8 DM_SM_ACCESS 2728.11.9 DM_SM_SET_SEC_MODE_REQ 2738.11.10 DM_SM_ADD_DEVICE_REQ 2748.11.11 DM_SM_REMOVE_DEVICE 2758.11.12 DM_SM_AUTHORISE 2768.11.13 DM_SM_AUTHENTICATE 2778.11.14 DM_SM_ENCRYPT 2788.11.15 DM_SM_ENCRYPTION_CHANGE 2798.12 ACL link management and monitoring 2808.12.1 DM_ACL_OPEN 2808.12.2 DM_ACL_OPENED_IND 2818.12.3 DM_ACL_CLOSED_IND 2818.13 Usage Scenarios and Examples 2818.13.1 Registration 2828.13.2 SCO Connection Establishment 2838.13.3 Inquiry 2858.13.4 Limited Discoverability Mode 288

9 HCI Transport 2939.1 HCI Top Interface 2949.1.1 Overview 294


Contents

© 2001 9

9.2 Downstream SCO Data Interface 2969.2.1 HCI_Send_SCO_Data_Packet 2969.2.2 Example 2979.3 Upstream SCO Data Interface 2989.3.1 HCI_SCO_DATA_PACKET 2989.3.2 Example 2999.4 SCO data application management 3019.5 UART Driver Function Interface and USB Interface 301

Annex A Writing a Port Entity 302A.1 Overview 302A.2 Example Action Functions 308Send_Start_Req 308Send_ParNeg_Req 309Send_Establish_Req 310Send_Close_Req 310Send_Established_ok 310Send_Data 310Read_Data 311Store_Data 311Close_Connection 311

Annex B Error Codes 313B.1 GENERAL_ERROR 313B.2 RFCOMM_ERROR 313B.3 L2CAP_ERROR 313B.4 DM_ERROR 314B.5 HCI_ERROR 314B.6 LM_ERROR 314B.7 SDP_ERROR 314B.8 CS_ERROR 314

Annex C Changes in this version 315C.1 General 315C.2 Introduction 315C.3 Overview 315C.4 BlueStack Application Interface 315C.5 RFCOMM 315C.6 SDP 315C.7 TCS 316C.8 L2CAP 316C.9 Device Manager 316C.10 HCI Transport 317C.11 Annex A – Writing a port entity 317C.12 Annex B – Error Codes 317

Glossary 318event 318Big Endian 318downstream 318host 318host controller 318phandle 318server channel 318upstream 318


Contents

© 2001 10

Acronyms 319


Contents

© 2001 11

List of Figures

Figure 2-1: Bluetooth Protocol Stack as Specified by the Bluetooth SIG....................................18Figure 2-2: BlueStack Protocols Layers ......................................................................................19Figure 2-3: Layers Required in an Application Running over Bluetooth .....................................20Figure 2-4: Showing the relationship between the Application Interface to BlueStack

(bluestack.h) and the Interface Library Functions. ...............................................................21Figure 2-5: Three Integration Approaches Illustrated..................................................................22Figure 2-6: RFCOMM Devices Type 1 and Type 2 .....................................................................28Figure 2-7: HCI showing physical split between Host and Host Controller .................................29Figure 2-8: Use of Primitives with Layered Protocols..................................................................30Figure 2-9: Protocol Message Construction Within a Layered Architecture................................30Figure 2-10: Management Entity in the Integrated Application ...................................................35Figure 3-1: The Application Interface to BlueStack. ....................................................................37Figure 3-2: Illustration of Event Handling and Message Passing................................................40Figure 3-3: Primitive Definition Format ........................................................................................41Figure 4-1: RFCOMM Overview Architecture..............................................................................73Figure 4-2: MUX and Service Channel Relationship Example....................................................74Figure 4-3: RFCOMM Credit-based Flow Control, successful negotiation .................................75Figure 4-4: RFCOMM Credit-based Flow Control, unsuccessful negotiation .............................76Figure 4-5: Updating flow control with no user data ....................................................................77Figure 4-6: Starting a Multiplexer Session – As an Initiator ......................................................103Figure 4-7: Starting a Multiplexer Session – As a Recipient .....................................................105Figure 4-8: Opening a Server Channel and Negotiating Parameters .......................................107Figure 5-1: Service Record Attribute List...................................................................................112Figure 5-2: Service Record Structure ........................................................................................115Figure 5-3: Service Registration ................................................................................................125Figure 5-4: COM1 Service Record Example .............................................................................129Figure 5-5: Service Search Request .........................................................................................130Figure 5-6: Service Attribute Request .......................................................................................132Figure 6-1: TCS Binary Relationship to Other Entities ..............................................................136Figure 6-2: Cordless Telephony Application supporting multiple profiles .................................137Figure 6-3: Cordless Telephony Scenario .................................................................................138Figure 7-1: Registration .............................................................................................................211Figure 7-2: Connection Establishment–Outgoing......................................................................212Figure 7-3: Connection Establishment–Incoming......................................................................214Figure 7-4: Data Transfer ..........................................................................................................216Figure 7-5: Disconnection – Local Initiation...............................................................................217Figure 7-6: Disconnection–Remote Initiation.............................................................................217Figure 8-1: Device Manager Interfaces .....................................................................................219Figure 8-2: SCO Control Entity Credit Counter .........................................................................224Figure 8-3: Registration Example ..............................................................................................282Figure 8-4: SCO Connection Establishment..............................................................................284Figure 8-5: Inquiry......................................................................................................................285Figure 8-6: Inquiry–Flowchart ....................................................................................................286Figure 9-1: HCI Transport Component Relationship .................................................................294Figure 9-2: SCO Control and Data Flows..................................................................................295Figure 9-3: Layers Required in an Application Running over Bluetooth ...................................302Figure 9-4: Differences in Data Transfer ...................................................................................304Figure 9-5: Port Entity Phases...................................................................................................304Figure 9-6: Port Entity Application to RFCOMM Calls...............................................................305Figure 9-7: Message Exchange.................................................................................................306Figure 9-8: Basic Flow Control ..................................................................................................307


Contents

© 2001 12

List of Tables

Table 2-1: Allowable BlueStack Partitioning Combinations.........................................................36Table 4-1: RFC_INIT Primitives...................................................................................................79Table 4-2: RFC_REGISTER Primitives .......................................................................................80Table 4-3: RFC_START Primitives..............................................................................................81Table 4-4: RFC_STARTCMP Primitive .......................................................................................83Table 4-5: RFC_CLOSE Primitives .............................................................................................85Table 4-6: RFC_PARNEG Primitives ..........................................................................................86Table 4-7: RFC_ESTABLISH Primitives......................................................................................88Table 4-8: RFC_RELEASE Primitive...........................................................................................90Table 4-9: RFC_CONTROL Primitives........................................................................................91Table 4-10: Mapping From the Control Signal Octet by a Receiving Entity ................................92Table 4-11: Mapping To the Control Signal Octet by a Sending Entity.......................................92Table 4-12: RFC_PORTNEG Primitives......................................................................................93Table 4-13: RFC_FCON Primitives .............................................................................................96Table 4-14: RFC_FCOFF Primitives ...........................................................................................97Table 4-15: RFC_DATA Primitives..............................................................................................98Table 4-16: RFC_DATAWRITE Primitives ..................................................................................99Table 4-17: RFC_LINESTATUS Primitives ...............................................................................100Table 4-18: RFC_TEST Primitives ............................................................................................101Table 4-19: RFC_NSC Primitive................................................................................................102Table 5-1: Data Types from Bluetooth Specification .................................................................113Table 5-2: Size Indexes from Bluetooth Specification...............................................................114Table 5-3: SDC_SERVICE_SEARCH Primitives ......................................................................116Table 5-4: SDC_SERVICE_ATTRIBUTE Primitives .................................................................118Table 5-5: SDC_SERVICE_SEARCH_ATTRIBUTE Primitives ................................................119Table 5-6: SDC_TERMINATE_PRIMITIVE Primitives ..............................................................120Table 5-7: SDC_OPEN_SEARCH Primitives ............................................................................121Table 5-8: SDC_CLOSE_SEARCH Primitive............................................................................122Table 5-9: SDC_CONFIG Primitive ...........................................................................................122Table 5-10: SDS_REGISTER Primitives ...................................................................................123Table 5-11: SDS_UNREGISTER Primitives..............................................................................124Table 5-12: SDS_CONFIG Primitive .........................................................................................124Table 5-13: Serial Port Profile Service Database Entries..........................................................126Table 6-1: TCS Primitives and wug_master Flag Relationship ...............................................142Table 6-2: TCS_REGISTER Primitives .....................................................................................144Table 6-3: TCS_UNREGISTER Primitives ................................................................................145Table 6-4: TCS_ATTACH Primitives .........................................................................................146Table 6-5: TCS_ PRE_ATTACH Primitives...............................................................................148Table 6-6: TCS_DETACH Primitives.........................................................................................149Table 6-7: TCS_SETUP Primitives...........................................................................................150Table 6-8: TCS_CL_SETUP Primitives ....................................................................................154Table 6-9: TCS_INFO Primitives ..............................................................................................158Table 6-10: TCS_CALL_PROCEEDING Primitives .................................................................161Table 6-11: TCS_ALERTING Primitives....................................................................................163Table 6-12: TCS_OPEN_SCO Primitives..................................................................................165Table 6-13: TCS_CONNECT Primitives....................................................................................167Table 6-14: TCS_PROGRESS Primitives .................................................................................169Table 6-15: TCS_DISCONNECT Primitives..............................................................................170Table 6-16: TCS_RELEASING Primitives .................................................................................172Table 6-17: TCS_RELEASED Primitives ..................................................................................174Table 6-18: TCS_CL_RELEASE Primitive ................................................................................176Table 6-19: TCS_CL_RELEASED Primitive..............................................................................178


Contents

© 2001 13

Table 6-20: TCS_START_DTMF Primitives..............................................................................179Table 6-21: TCS_STOP_DTMF Primitives................................................................................181Table 6-22: TCS_ACCESS_RIGHTS Primitives .......................................................................182Table 6-23: TCS_WUG_INFO Primitives ..................................................................................184Table 6-24: TCS_LISTEN_REQUEST Primitives .....................................................................186Table 6-25: TCS_LISTEN_SUGGEST Primitives .....................................................................188Table 6-26: TCS_LISTEN_QUERY Primitives ..........................................................................190Table 6-27: TCS_CL_INFO Primitives ......................................................................................192Table 7-1: L2CA_REGISTER Primitives ...................................................................................197Table 7-2: L2CA_CONNECT Primitives ....................................................................................198Table 7-3: L2CA_CONFIG Primitives........................................................................................200Table 7-4: L2CA_DATAWRITE Primitives.................................................................................202Table 7-5: L2CA_DATAREAD Primitives ..................................................................................203Table 7-6: L2CA_DISCONNECT Primitives ..............................................................................204Table 7-7: L2CA_TIMEOUT Primitives......................................................................................205Table 7-8: L2CA_QOSVIOLATION Primitives...........................................................................205Table 7-9: L2CA_PING Primitives .............................................................................................206Table 7-10: L2CA_GETINFO Primitives....................................................................................207Table 7-11: L2CA_GROUP_CREATE Primitives......................................................................208Table 7-12: L2CA_GROUP_CLOSE Primitives ........................................................................209Table 7-13: L2CA_ENABLE_CONNECTIONLESS Primitives ..................................................210Table 7-14: L2CA_DISABLE_CONNECTIONLESS Primitives .................................................210Table 8-1: DM_AM_REGISTER Primitives ...............................................................................226Table 8-2: DM_WRITE_CACHED_PAGE_MODE Primitives ...................................................227Table 8-3: DM_WRITE_CACHED_CLOCK_OFFSET Primitives..............................................228Table 8-4: DM_CLEAR_PARAM_CACHE Primitives................................................................229Table 8-5: DM_HCI_INQUIRY Primitive....................................................................................230Table 8-6: DM_HCI_INQUIRY_RESULT Primitive ...................................................................231Table 8-7: DM_HCI_INQUIRY_COMPLETE Primitive..............................................................232Table 8-8: DM_HCI_INQUIRY_CANCEL Primitive ...................................................................233Table 8-9: DM_HCI_INQUIRY_CANCEL_COMPLETE Primitive .............................................233Table 8-10: DM_HCI_CHANGE_PACKET_TYPE Primitive .....................................................234Table 8-11: DM_HCI_CHANGE_LINK_KEY Primitive ..............................................................235Table 8-12: DM_HCI_MASTER_LINK_KEY Primitive ..............................................................235Table 8-13: DM_HCI_REMOTE_NAME_REQUEST Primitive .................................................236Table 8-14: DM_HCI_READ_REMOTE_FEATURES Primitive ................................................236Table 8-15: DM_HCI_READ_REMOTE_VERSION Primitive ...................................................237Table 8-16: DM_HCI_READ_CLOCK_OFFSET Primitive ........................................................237Table 8-17: DM_HCI_REMOTE_NAME_COMPLETE Primitive ...............................................238Table 8-18: DM_SET_DEFAULT_LINK_POLICY Primitive ......................................................239Table 8-19: DM_HCI_WRITE_LP_SETTINGS Primitive...........................................................240Table 8-20: DM_HCI_WRITE_LP_SETTINGS_COMPLETE Primitive.....................................241Table 8-21: DM_HCI_READ_LP_SETTINGS Primitive ............................................................242Table 8-22: DM_HCI_READ_LP_SETTINGS_COMPLETE Primitive ......................................242Table 8-23: DM_HCI_PARK_MODE Primitive ..........................................................................243Table 8-24: DM_HCI_EXIT_PARK_MODE Primitive ................................................................244Table 8-25: DM_HCI_HOLD_MODE Primitive ..........................................................................245Table 8-26: DM_HCI_SNIFF_MODE Primitive..........................................................................246Table 8-27: DM_HCI_EXIT_SNIFF_MODE Primitive ...............................................................247Table 8-28: DM_HCI_ROLE_DISCOVERY Primitive................................................................248Table 8-29: DM_HCI_SWITCH_ROLE Primitive.......................................................................248Table 8-30: DM_HCI_CHANGE_LOCAL_NAME Primitive .......................................................249Table 8-31: DM_HCI_CHANGE_LOCAL_NAME_COMPLETE Primitive .................................249Table 8-32: DM_HCI_WRITE_SCAN_ENABLE Primitive.........................................................250Table 8-33: DM_HCI_WRITE_CURRENT_IAC_LAP Primitive.................................................251


Contents

© 2001 14

Table 8-34: DM_HCI_FLUSH Primitive .....................................................................................252Table 8-35: DM_HCI_READ_AUTO_FLUSH_TIMEOUT Primitive...........................................252Table 8-36: DM_HCI WRITE_AUTO_FLUSH_TIMEOUT Primitive..........................................253Table 8-37: DM_HCI_READ_TX_POWER_LEVEL Primitive ...................................................254Table 8-38: DM_HCI_READ_SCO_FLOW_CONTROL_ENABLE Primitive ............................255Table 8-39: DM_HCI_WRITE_SCO_FLOW_CONTROL_ENABLE Primitive...........................255Table 8-40: DM_HCI_READ_LINK_SUPERV_TIMEOUT Primitive..........................................256Table 8-41: DM_HCI_WRITE_LINK_SUPERV_TIMEOUT Primitive........................................256Table 8-42: DM_HCI_FAILED_CONTACT_COUNTER Primitive.............................................257Table 8-43: DM_HCI_RESET_CONTACT_COUNTER Primitive .............................................257Table 8-44: DM_HCI_GET_LINK_QUALITY Primitive..............................................................258Table 8-45: DM_HCI_READ_RSSI Primitive ............................................................................258Table 8-46: DM_SCO_INCOMING_REGISTER primitive.........................................................259Table 8-47: DM_SCO_INCOMING_UNREGISTER primitive ...................................................260Table 8-48: DM_SCO_CONNECT Primitive .............................................................................261Table 8-49: DM_SCO_DISCONNECT Primitives .....................................................................262Table 8-50: DM_SCO_BUFFER_SIZE Primitive.......................................................................263Table 8-51: DM_SCO_DATA_SENT Primitive ..........................................................................264Table 8-52: DM_SM_PIN_REQUEST Primitive ........................................................................265Table 8-53: DM_SM_LINK_KEY_REQUEST Primitive.............................................................266Table 8-54: DM_SM_SET_DEFAULT_SECURITY Primitives ..................................................267Table 8-55: DM_SM_REGISTER Primitives .............................................................................268Table 8-56: DM_SM_REGISTER_OUTGOING_REQ Primitives..............................................269Table 8-57: DM_SM_UNREGISTER Primitives ........................................................................270Table 8-58: DM_SM_UNREGISTER_OUTGOING Primitives ..................................................271Table 8-59: DM_SM_ACCESS Primitives .................................................................................272Table 8-60: DM_SM_SET_SEC_MODE Primitives ..................................................................273Table 8-61: DM_SM_ADD_DEVICE Primitives.........................................................................274Table 8-62: DM_SM_REMOVE_DEVICE Primitives.................................................................275Table 8-63: DM_SM_AUTHORISE Primitive.............................................................................276Table 8-64: DM_AUTHENTICATE Primitive .............................................................................277Table 8-65: DM_SM_ENCRYPT Primitive ................................................................................278Table 8-66: DM_SM_ENCRYPTION_CHANGE Primitive ........................................................279Table 8-67: DM_ACL_OPEN Primitives ....................................................................................280Table 8-68: DM_ACL_OPENED_IND Primitive.........................................................................281Table 8-69: DM_ACL_CLOSED_IND Primitive.........................................................................281Table 9-1: HCI_SCO_DATA_PACKET .....................................................................................298Table 9-2: Message Exchange State Table ..............................................................................307


Introduction

© 2001 15

1 IntroductionThis chapter describes the BlueStack User Guide and the conventions used within. It containsthe following sections:

� Audience on page 15

� In This Document on page 15

� Conventions on page 16

1.1 Audience

This User Guide is written for systems and product developers who want to incorporateBlueStack as a software component into their designs. The Guide assumes that the reader isfamiliar with ‘C’, the language BlueStack is written in.

It is assumed that the reader is familiar with the basic Bluetooth concepts; it is possible to applyBlueStack without a need for a detailed understanding of the Bluetooth specification.

Different sections of the manual are applicable to different application areas. Consequently,product developers can omit sections that are not relevant to them.

1.2 In This Document

This document is the user’s guide to BlueStack, the Bluetooth protocol software developed byMezoe. It provides an overview of BlueStack that covers the design philosophy of the softwareand the Application Programming Interfaces (APIs). It does not provide a detailed description ofthe design of the individual software sub-systems that comprise BlueStack, nor does it describethe operation of Bluetooth.

1.2.1 About this ManualEach of the API’s is described in detail. The information provided for the API primitives isillustrated with individual examples. Examples are also included for more complicatedscenarios.

This User Guide does not describe in detail how to design a Bluetooth system, nor does itprovide any sample applications. Sample applications are included with Proto Developer forBlueStack (the BlueStack software development toolkit).

1.2.2 Finding Your Way AroundWe have provided some guideposts within the document concerning the relevancy of sections -see Conventions on page 16 for details. It is suggested that you begin by reading the Overviewon page 18 if you are new to BlueStack. Once you become familiar with the overall philosophy,you can concentrate on those detailed sections that are of direct relevance.


Introduction

© 2001 16

The BlueStack User Guide contains the following sections:

Introduction on page 15 An overview of the BlueStack User Guide

Overview on page 18 An overview of BlueStack and its various components.

BlueStack ApplicationInterface on page 37

An overview of the BlueStack Application Interface and anintroduction to the API.

RFCOMM on page 72 An overview of RFCOMM - a protocol that provides serial portemulation over the L2CAP protocol - and an introduction to itsAPI.

Service Discovery Protocolon page 111

An overview of SDP and an introduction to its API.

TCS on page 136 An overview of TCS – the Telephony Control Specification(also know as TCS binary) - and an introduction to its API.

L2CAP on page 194 An overview of L2CAP - the Logical Link Control andAdaptation Protocol - and an introduction to its API.

Device Manager on page 219 An overview of the Device Manager - the managementfunctions that relate to the Management aspects of Bluetooth.An introduction to the DM API is also provided.

HCI Transport on page 293 An overview of the HCI transport function – and anintroduction to its associated APIs.

Annex A – Writing a PortEntity on page 302

A description of the process of writing a Port Entity, along witha simple model.

Annex B – Error Codes onpage 313

A list of the error codes that BlueStack can return at its API’s

Annex C – Changes in thisversion on page 315

A list of the changes made to this document since its lastformal release.

Glossary on page 315 A list of terms and acronyms associated with BlueStack,which have been used throughout this document.

1.3 Conventions

The following conventions are used in the BlueStack User Guide:

Narrative text is always in the Arial font.

Example ‘C’ code is in the Courier New font.

Note: Where possible, the example ‘C’ code can be compiled and executed.

The Times New Roman font is used for illustrative text, for example pseudo code. This text isalso indented.

Italicized text is used to indicate a note of explanation and is accompanied with thenote symbol.

The warning symbol is used to draw to the reader’s attention where a situationcould occur that could result in an undesirable side effect. This is accompaniedby text in bold.


Introduction

© 2001 17

The light bulb symbol is used to indicate an idea or hint that the reader may finduseful. This text is also italicized.

The ‘C’ code includes both source code (.c) and header (.h) files. The header files:

� declare all the necessary information to provide the interface to the functionality provided byan identically named .c file.

� define the interface parameters (‘primitives’) of a protocol layer interface.

For all files there is a naming convention adopted whereby the file is preceded with an identifierthat shows the owning layer. For example l2cap_prim.h is the primitive header file for L2CAP.Common files are not preceded with an identifier.

There are a number of different product types that can be realised using BlueStack. Within themanual the following symbols are used to identify sections that are of particular relevance toproduct designers.

1.3.1 Getting More InformationThe Bluetooth website, www.Bluetooth.com, contains the Bluetooth specification, profiles andother documents relevant to Bluetooth.

General information regarding BlueStack, Proto Developer for BlueStack1, Interface Express2

and other Bluetooth products from Mezoe can be found on the Mezoe websitewww.mezoe.com.

Technical support is available to licensees of BlueStack. The email address [email protected] .

Cambridge Consultants Ltd. can provide design services on a contract basis to those peoplerequiring professional assistance with the design and/or development of Bluetooth products.For further information, visit the CCL website: www.cambridge-consultants.com.

Further information on the BlueCore™ single-chip solution, which is used in some examples inthis manual, can be obtained from Cambridge Silicon Radio, www.csr.com.

1 Proto Developer is a software toolkit to assist you developing with BlueStack.2 Interface Express provides an application abstraction for BlueStack tailored to the Bluetooth profiles. It also providesBluetooth management functions that expand the capability of the BlueStack Device Manager.

http://www.bluetooth.com/

http://www.mezoe.com/


http://www.cambridge-consultants.com/

http://www.csr.com/


Overview

© 2001 18

2 OverviewThis chapter introduces the Bluetooth protocol stack and the BlueStack layers. The differenttypes of products that can incorporate BlueStack as a component are also discussed.

It contains the following sections:

� Introducing BlueStack on page 18

� BlueStack as a Software Component on page 19

� The Application Interface to BlueStack on page 23

� BlueStack Layers on page 26

� Internal Communications Model Adopted for BlueStack on page 29

� Error Handling and Debug Facilities on page 34

� Registration and phandles on page 33

� Management Entity on page 34

� Partitioning on page 36

� Porting and Building on page 36

2.1 Introducing BlueStack

The layered model proposed by the Bluetooth Special Interest Group (SIG) is shown in Figure2-1. The shaded boxes indicate the layers defined in version 1.1 of the Bluetooth specification.

Figure 2-1: Bluetooth Protocol Stack as Specified by the Bluetooth SIG


Overview

© 2001 19

BlueStack is a software implementation in ‘C’ of the Bluetooth protocol stack, as shown inFigure 2-2 on page 19. It has been designed to be applicable to a wide range of Bluetoothapplications. It does not include Obex1, WAP, VCal or VCard.

Baseband and RF

Link Manager

HCI bottom

HCI lower driver

HCI Upper driver

HCI Top

L2CAP Device Mgr

RF

CO

MM

TC

S B

inar

y

SD

P

Figure 2-2: BlueStack Protocols Layers

BlueStack introduces the Device Manager. This provides a number of stack managementfunctions, such as security management, and allows access to the HCI command and eventinterface.

2.2 BlueStack as a Software Component

BlueStack is a software component that is designed to allow product developers to incorporateBluetooth functionality within their products.

BlueStack is supplied with the following elements:

• Device Manager (DM)• SDP• RFCOMM• TCS• L2CAP• HCI Top• HCI Upper Driver (H:4 or BCSP)• Scheduler services 1 Supplied as part of Interface Express from Mezoe


Overview

© 2001 20

BlueStack is intended to be used in conjunction with Bluetooth hardware. Since the HCI is astandard interface, BlueStack works with Bluetooth hardware from a range of silicon vendors.

The BlueStack HCI Bottom and Link Manager are not supplied as standard as part ofBlueStack. HCI Bottom and the Link Manager have been implemented for the BlueCore™1

single chip device from Cambridge Silicon Radio, however they can be ported to other siliconvendors host controller devices – please contact Mezoe at [email protected] for furtherinformation if you need to incorporate the BlueStack Link Manager in your design and wish topurchase it. See also page 26.

As a software component, BlueStack requires integrating with other software to realise acomplete product. Typically, this software is some form of application. It may be an existingapplication, or a completely new application.

The integration model adopted for BlueStack is based on integrating the stack with anapplication. The integration can be carried out in an integration layer, which sits between theapplication and BlueStack. An example of such an integration layer is defined in the serial portprofile, the Port Entity. This sits between the Application and RFCOMM.

Baseband and Link Control

Link Manager

HCI

L2CAP and Device Manager

SDP

RFCOMM

Port EntityApplication

Management Entity

Application BT AppApplication Layer

Integration Layer

Profile Specific Layer

Bluetooth GenericStack Layers

Figure 2-3: Layers Required in an Application Running over Bluetooth

RFCOMM is a profile specific layer. For example, when developing a Bluetooth cordlesstelephone that meets the interoperability requirements laid down in the Cordless Telephonyprofile, TCS binary would be used as the profile specific layer, and not RFCOMM. Theexamples in this User Guide use applications that run over RFCOMM.

In Figure 2-3 RFCOMM is the Port Entity - this is the integration layer between RFCOMM andthe application. When the application is wholly new, the application could be designed tointerface directly to the RFCOMM API. However, in many cases the application already exists,

1 BlueCore is a Trademark of Cambridge Silicon Radio Ltd.



Overview

© 2001 21

so the Port Entity is introduced to adapt the RFCOMM API to the form required by theapplication.

The integration layer can also provide the adaptation between the application’s environmentand the BlueStack operating environment.

BlueStack is designed to be portable. Part of the porting decision that a designer must make iswhether to wholly integrate each of the host-resident software subsystems (‘layers’) into thehost operating system. However, an easier alternative is to take the environment of BlueStack -the scheduler and memory manager - and to port them with the host layers onto the host.Porting is dealt with in detail in the document BlueStack Porting Guide.

Access to the BlueStack operating environment services, and hence to the BlueStack APIs, isvia the interface defined in the file bluestack.h. This is referred to as the Application Interface toBlueStack and is further described in the section The Application Interface to BlueStack onpage 23.

HCI Top

L2CAP

SDP

Device Mgr

RF

CO

MM

BlueStackOperating

Environment

DM LibSDP LibRFCOMM Libbluestack.h

Application and Integration Layer

Figure 2-4: Showing the relationship between the Application Interface to BlueStack(bluestack.h) and the Interface Library Functions.

The application can access the APIs directly, using the operating environment servicesprovided by bluestack.h, or can access the APIs using the Interface Library Functions. Therelationship between the Application Interface and the Interface Library Functions is shown inFigure 2-4. The Interface Library Functions are described further on page 32.

The exact integration approach taken also depends on the type of product being developed.For example, performance will be different depending on the integration approach adopted.Broadly speaking, there are three categories of products that designers might consider:

� two-processor standard solutions involving a host and host controller, where the higherlayers have to be ported to and implemented on the host, the physical split at the Bluetooth- defined HCI (for example, a PC-based application)

� two-processor embedded solutions where the split between host and embedded (host)controller does not take place at the HCI (for example, an embedded host with limitedresources, such as a mobile phone)


Overview

© 2001 22

� wholly embedded single processor solutions, where there is no external host, for example,a wireless headset

The protocol layer models for the different categories can be represented as shown inFigure 2-5.

Hardware

Drivers

BASEBAND and RF

Application

LINK MANAGER

APPLICATION INTERFACE

BASEBAND and RF

HCI

L2CAP

Port Entity

Application

ServiceDiscovery

LINK MANAGER

RF

CO

MM

BASEBAND and RF

L2CAP

RFCOMM

Port Entity

Application

DeviceManager

LINK MANAGER

HCI HCI HCI

DeviceManager

SDP RFCOMM SDP

L2CAPDevice

Manager

Standard Two-ProcessorArchitecture

Embedded Two-ProcessorArchitecture

Wholly-Embedded Single-Processor Architecture

Figure 2-5: Three Integration Approaches Illustrated

2.2.1 Standard Two-Processor SolutionFor the standard two-processor solution, where the split between higher and lower layers of thestack takes place at the HCI, it is assumed that the host is a personal computer of somedescription. However, in general this category can include any computing platform withcommunications capability that is not resource limited.

2.2.2 Embedded Two-Processor SolutionThe embedded two-processor category is a feature of BlueStack demonstrated by BlueCore™.This allows products to be designed that incorporate Bluetooth, where the host is resourcelimited and cannot readily support the addition of the Bluetooth functionality. One such exampleis a mobile phone; not all mobile phones have the spare resources to readily implementadditional protocol stacks.

2.2.3 Wholly Embedded SolutionThe wholly embedded solution, for example a single chip Bluetooth product, also shows wherethe additional hardware drivers sit within the architecture. One example is of a cordlessheadset, however the model is equally applicable to any small wireless device that wouldbenefit from a single processor solution.


Overview

© 2001 23

2.3 The Application Interface to BlueStackThe application interface to BlueStack is defined in the file bluestack.h. This file #includes allthe header files required to define the application interfaces that are needed to access theindividual layer APIs. An overview of the individual layers is given in the section BlueStackLayers that starts on page 26.

The services provided via this interface allow the application to:

• initialise the scheduler and BlueStack

• access the memory management functions

• configure the driver for the HCI transport layer

• use the scheduler services such as message passing and timed events.

This section provides an overview for each of these services.

A full description of the functions that comprise this interface can be found in the sectionBlueStack Application Interface that starts on page 37.

The same application interface is used both for the portable code of BlueStack, and theBlueStack library supplied with Proto Developer. This allows users to develop code using ProtoDeveloper, in conjunction with the Microsoft Developer Studio and Visual C++ tools.Developing products using Proto Developer is described in the Proto Developer User Guide.

2.3.1 Scheduler and BlueStack InitialisationThe scheduler and BlueStack initialisation services allow the application to control the start upof the scheduler and BlueStack. Specifically, the application:

• initialises the scheduler

• initialises the HCI transport driver

• configures BlueStack and

• starts the scheduler running.

The configuration of BlueStack controls which BlueStack layers have been implemented on thehost. This configuration code does NOT control the configuration of any higher layers that areimplemented in firmware on the host controller device. Hence the configuration of the layers onthe host must reflect the configuration of the firmware on the host controller.

If there is a mis-match in the configuration code between the host and the hostcontroller then the protocol software may behave in a unpredictable manner.

Configuring BlueStack via the Application Interface does not control which layers are presentwithin the build, and which are absent. For example, if an application requires RFCOMM andnot TCS Binary, then it is possible to build BlueStack without TCS Binary, thus saving memory.In this case, if any configuration settings are made for TCS Binary via the Application Interface,then they will be ignored.

Additionally, the dynamic configuration of the resources assigned to the memory manager canbe selected, provided that this option has been set up by use of the compiler flagPMALLOC_DYNAMIC_LINK. Further configuration options allow the protection of tasks usingmutex.


Overview

© 2001 24

The function calls are described in detail in the section BlueStack Application Interface on page37. Within that section is an example scenario for Scheduler and BlueStack Initialisation onpage 69.

2.3.2 Memory Management FunctionsThe memory manager is a library that provides a pool of memory blocks that are available forthe dynamic allocation of storage.

The memory management functions primarily allow the application to access the same memorymanagement services that the BlueStack protocol software uses. Thus an application canallocate, using pmalloc(), and free memory blocks, using pfree(); typically allocating memoryblocks for downstream messages and freeing the memory blocks of received upstreammessages once the data has been dealt with (consumed).

The memory manager services also include a number of utility functions that:

• allocate memory and set the contents to zero, and

• report the memory pool status.

Optionally, the memory pool configuration can be modified dynamically during BlueStackinitialisation as described on page 44. With the source code portable version of BlueStack, thistask is normally carried out by editing the appropriate files prior to building the code. Furtherdetails are given in the document BlueStack Porting Guide.

The memory manager library is not a true malloc()-style memory allocator - it does not obtainmemory from any underlying operating system nor does it perform defragmentation of returnedmemory.

2.3.3 HCI Transport Driver ConfigurationThe HCI Transport driver configuration allows the application to set up the driver for the HCITransport.

The functions available via the Application Interface allow the application to:

• find the identifier for the next available driver,• select a driver,• initialise the selected driver,• find the identifier of any installed drivers, then query for a specific driver,• obtain the driver’s name and its description and• obtain the identifier of a driver from its name.

The HCI Transport itself is described in the section HCI Transport on page 293


Overview

© 2001 25

2.3.4 Scheduler ServicesTbe BlueStack protocol software uses a lightweight scheduler to co-ordinate the execution ofthe stack layers. The scheduler has many similarities to a STREAMS1 scheduler and istherefore well suited for use with protocol stacks. The scheduler is designed to be portable.

There are two options for the porting of the scheduler, either as the sole operatingsystem or as an adaptation layer to work within another operating systemenvironment.

The scheduler provides a single-threaded co-operative non pre-emptive multi-taskingenvironment. This places a requirement on the programmers to ensure that the length of anysingle task execution time is as short as possible so that control is returned to the scheduler assoon as possible.

If tasks take too long to execute, it results in buffer overflows, which couldcause the stack to miss events.

Where there is a possibility that a single task may take too long to execute, it canusually be broken down into several shorter tasks. In this case, the software moduleposts a message back to itself via the scheduler queue, to ensure that the schedulercalls it again to continue the execution later.

A direct consequence of the use of this simple scheduler is that there can be noblocking calls. These cause the stack to halt.

The BlueStack interface philosophy follows on from the use of the scheduler; the APIs to thelayers cannot block. A message passing method is used where a message is sent to aparticular task via the scheduler, using a queue identifier as the destination.

Queue identifiers are set up for the tasks at build time and are part of the schedulerconfiguration. The protocol stack layer queues are pre-assigned to tasks at buildtime.

Queue identifiers are also referred to within the software as protocol handles, or ‘phandles’. Forthe higher layers of BlueStack, a registration procedure is used whereby the phandle of theupper layer is registered with the lower layer before communication starts. This is to allow thedynamic configuration of protocol stacks. Phandles are dealt with in detail in Registration andphandles on page 33.

The scheduler executes the tasks that have messages pending. It is up to the software moduleto pull the message or messages from the queue and to act on them. The result of this is thatthe BlueStack protocol stack is message driven.

The scheduler provides timer support. Timer support is hardware dependent and any port to adifferent platform needs to take this fact into consideration.

1 STREAMS was originally developed as a framework for communications services under Unix.


Overview

© 2001 26

2.4 BlueStack Layers

This section provides an overview for each of the BlueStack layers.

Within BlueStack, the protocol layers above the HCI: L2CAP, SDP, RFCOMM andDevice Manager, are referred to as the ‘Higher Layers’ and the layers below the HCI:Link Manager and Link Controller, are referred to as the ‘Lower Layers’.

2.4.1 Link ManagerThe Link Manager implements the Link Management Protocol (LMP) as defined by theBluetooth SIG. The Link Manager is not supplied as standard with BlueStack and is includedhere only for completeness.

The Link Manager is responsible for the establishment of Asynchronous ConnectionLess (ACL)and Synchronous Connection Oriented (SCO) links and as a consequence, is also responsiblefor both Paging and Page Scanning. Similarly, it is responsible for the initiation and control ofInquiry and Inquiry Scanning, plus Hold, Sniff and Park modes.

Authentication and encryption is controlled by the Link Manager, which includes theimplementation of the authentication algorithms.

The Link Manager also implements the event filters. Event filters are mechanisms specified bythe Bluetooth SIG to allow automatic link establishment without reference to the higher layers.The event filters constrain which links can be established without higher layer intervention.

There is no direct API provided for the control of the Link Manager from the application. Controlof the Link Manager from the application may be achieved indirectly using the HCI calls that areavailable via the Device Manager API. The Link Manager layer is not covered in detail in thisUser Guide.

2.4.2 L2CAPL2CAP implements the Logical Link Control and Adaptation Protocol (L2CAP) as defined by theBluetooth SIG. The purpose of L2CAP is to provide connection oriented and connectionlessdata services to higher layer protocols. In order to do this, it provides:

� multiplexing of higher layer protocols

� segmentation and re-assembly of large data packets

� establishment and maintenance of logical connections between L2CAP entities

Although the L2CAP protocol layer is used by both SDP and RFCOMM, it can also supportother services above it. Therefore, there is an API defined to allow developers to use L2CAPwith transport services other than RFCOMM applications. L2CAP is probably of little interest todevelopers who are developing applications that only use RFCOMM and SDP.

2.4.3 Device ManagerFor BlueStack, the Bluetooth protocol model has been expanded to include the DeviceManager. This is part of the management entity, which is discussed in more detail later in thisoverview (Management Entity on page 34).

The Device Manager is a collection of functions that relate to the management aspects ofBluetooth. These functions include resource management, which is responsible for ensuringthat the available resources (typically at the air interface) are not over-allocated to the differentapplications, which can all make service requests independently of each other.


Overview

© 2001 27

Device specific (silicon vendor dependent) management is not a function of the DeviceManager. However the HCI interface can be readily extended to incorporate the requiredfunctionality and the Management Entity may interface directly to the extension.

The Device Manager API is provided to allow more sophisticated control of the Bluetooth stack.This is an API that allows Bluetooth-aware applications to exploit the full capabilities ofBluetooth. For example, Bluetooth Inquiries should be handled via this API.

It is not necessary to write an integration layer that explicitly uses the HCI commandsvia the Device Manager interface – much of the service provision is managed by theDevice Manager in response to requests made to L2CAP.

2.4.4 Service DiscoverySDP is the implementation of the Service Discovery Protocol, as defined by the Bluetooth SIG.It consists of the Service Discovery Database for the device and subsequently, the ServiceDiscovery Server and the Service Discovery Client.

The Service Discovery API provides both Server and Client interfaces. The Server interface isused for the registration of services in the Service Discovery Database. The local Clientinterface allows an application, sometimes referred to as the Service Discovery Application, tobrowse for services on a remote device. SDP does not include this application.

2.4.5 RFCOMMRFCOMM implements the RFCOMM protocol as defined by the Bluetooth SIG. RFCOMM is aprotocol that provides an emulation of serial ports over the L2CAP protocol, including thetransfer of the state of non-data circuits, for example RS-232 Clear to Send (CTS).

The RFCOMM architecture supports two device types (see Figure 2-6):

� Type 1 is a communication end point, such as a computer.

� Type 2 is a device that is part of a communication segment such as a modem.

The Port Emulation Entity (PEE) maps a system specific communication interface (API) to theRFCOMM services. The Port Proxy Entity (PPE) relays data from RFCOMM to an externalserial interface, for example RS-232, linked to a Data Communication Equipment (DCE), suchas a modem.


Overview

© 2001 28

Port Emulation Entity

RFCOMM

Application

L2CAP L2CAP

RFCOMM

Port Proxy Entity

DCE

RFCOMMService Interface


Port Interfacee.g. VCOMM

Low LevelInterfaceData (Tx, Rx)

Data (Tx, Rx)Data (Tx, Rx)

ControlControl

Control

Type 1 Device Type 2 Device

Figure 2-6: RFCOMM Devices Type 1 and Type 2

RFCOMM does not include the Port Emulation or Port Proxy Entities. It can work with either ofthese and it is possible to support both concurrently on a single device.

The RFCOMM API interfaces to a Port Emulation or Port Proxy Entity. Port Emulation and PortProxy interfaces are discussed further in RFCOMM on page 72 and in Writing a Port Entity onpage 302.

2.4.6 TCS BinaryTCS Binary is a protocol that provides support for cordless telephony functionality over theBluetooth air interface. It defines call control functionality for the establishment and clearing ofcalls, procedures for the management of Bluetooth TCS devices, and a limited number ofsupplementary services.

The supplementary services included within the TCS Binary specification are explicit support forCalling Line Identity Presentation (CLIP). TCS Binary also provides a mechanism for sendingDual-Tone Multi-Frequency (DTMF) and Register Recall signals across the air interface. Thisallows a means whereby additional supplementary services within the (fixedtelecommunications) network may be accessed.

The Bluetooth specification includes two profiles that utilise the TCS Binary as defined by theBluetooth specification Part F:3:

The Cordless Telephony profile defines the interoperability requirements of Bluetooth devicesacting as either a Gateway (GW) or as Terminals (TL), where a gateway is a ‘base station’ thatconnects to the ISDN or fixed telecommunications network1, and provides cordlesscommunications services to the Terminals. The Terminals are typically, but not exclusively,cordless handsets.

The Intercom Profile defines the interoperability requirements for direct Terminal to Terminalcommunication. A Cordless Telephony Application may support either or both profiles. Whilst itis unlikely that a Gateway will directly support the Intercom Profile, it can include (group)

1 or provides a gateway to a fixed radio access network, CATV based communications network, satellite link or acellular communications network.


Overview

© 2001 29

management functionality that allows direct Terminal to Terminal communication to be achievedwith reduced call set up times.

2.4.7 Host Controller InterfaceHCI is the Host Controller Interface as specified by the Bluetooth SIG. Being an interface it isnot a protocol layer. The HCI drivers are considered to be protocol layers; these drivers providethe physical transport mechanism between HCI Top and Bottom. HCI implies a physicalseparation within the protocol stack, for example a serial link.

The Bluetooth Specification provides support for RS-232, UARTs and USB. BlueStack isdesigned to work with all of the Bluetooth specified HCI transport protocols.

BlueStack is supplied to work with the UART interface as defined in the Bluetooth specificationH:4 and the proprietary BlueCore Serial Protocol (BCSP). The UART interface for H:4 use iscovered in detail later in this User Guide, see page 301.

BlueStack is supplied to work with the USB PC driver for the BlueCore™1 single chip devicefrom Cambridge Silicon Radio Ltd. Please contact Mezoe support by e-mail [email protected] if you have specific requirements for your HCI, for example if you needto support USB on a particular host for a particular silicon vendor’s host controller device.

HCI Bottom

HCI Top

HCI Physical

Host

Host Controller

Figure 2-7: HCI showing physical split between Host and Host Controller

The terms ‘Top’ and ‘Bottom’ are used to distinguish between the HCI on the host andon the Host Controller.

Within BlueStack there is only direct access to HCI Top for SCO data. HCI commandsand events are accessible via the Device Manager API. ACL data is routed to / fromL2CAP via HCI Top.

2.5 Internal Communications Model Adopted for BlueStack

This section introduces the communications model used within BlueStack. It is fundamental tothe operation of the protocol stack, and has significant influence on the form of the APIs. It isrecommended that this section is read by all.

The implementation of BlueStack relies on control information and data being passed betweenthe different layers. In BlueStack this is achieved by passing internal messages between thelayers.

1 BlueCore is a Trademark of Cambridge Silicon Radio Ltd.



Overview

© 2001 30

For message passing between layers of the protocol stack, and indeed at the top of the stack, aservice primitive model has been adopted. The actual primitives used follow those defined inthe Bluetooth specification. The BlueStack APIs follow this service primitive model.

Service primitives follow a model that originates in the ISO 7 layer reference model for OpenSystems Interconnection (OSI). When a higher layer entity requests a service from the lowerlayer we use the notation _REQ. This typically results in some subsequent exchange of protocolmessages between layer N and its peer, as shown in Figure 2-8 on page 30.

Protocol Layer (N) Peer Protocol Layer (N)

Communication Link

Layer N+1 REQuests a service

Peer layer (N) passes aservice INDication to

peer layer N+1

Peer layer N+1RESponds to theservice indicationLayer N+1 is sent a

service confirm (CFM)

Figure 2-8: Use of Primitives with Layered Protocols

The APIs are defined in detail later in this User Guide. Figure 2-9 shows how a protocolmessage is built up through the layers using service primitives.

DATAServiceRequest

Layer N Service DataUnit

Layer N HeaderServiceRequest

Layer N - 1 Service Data UnitLayer N - 1

Header

Layer N Protocol Data Unit

Protocol Message Construction Protocol Layers

Dow

nstr

eam

Ups

trea

m

Layer N - 1

Layer N

Layer N + 1

Figure 2-9: Protocol Message Construction Within a Layered Architecture

If layer N+1 wants to send data to its peer, it presents this data along with a service request tolayer N, requesting the service that sends the data. The service request can be considered tobe control information. Layer N uses the control information to create its protocol message.The service primitive provides both this control information and a reference as to where to findthe associated user data. Therefore, the service primitive is the service request and thereference to the user data.

On arrival of the protocol message, the peer layer N sends an indication, for example aservice_IND to the peer layer N+1. In the most complete realization of the model, the peer


Overview

© 2001 31

layer N+1 responds with service_RES, and this results in a protocol message being sent toprotocol layer N. (In the L2CAP specification the notation _RSP has been adopted for response,instead of _RES). Finally, protocol layer N sends a confirmation, service_CFM, to Layer N+1.The _CFM notation is used for both successful and unsuccessful outcomes of the servicerequest. The result of the service request is recorded in a parameter in the CFM.

Not all service primitives have _REQ, _RES, _IND and _CFM structures defined. For example,an unsolicited event may have a _IND primitive only. Often the _RES (or _RSP) is unnecessary.One such case is a data transfer where there is a reliable transfer provided at a lower layer; thehigher layer has no need to respond to acknowledge correct receipt of the data – this is done bya lower layer.

_REQ and _RES (_RSP) are referred to as ‘Downstream’ primitives and _IND and_CFM as ‘Upstream’ primitives.

A service primitive takes the form in software of a structure, for example, the L2CAP primitiveL2CA_DataWrite has the structure:

typedef struct{ l2cap_prim_t type; /* Always L2CA_DATAWRITE_REQ */ cid_t cid; /* Local channel ID */ uint16_t length; /* Length of packet */ void *data; /* Pointer to data */

} L2CA_DATAWRITE_REQ_T;

Whereas the Bluetooth specification refers to this simply as L2CA_DataWrite, the formaldefinition of the service interface adds the service primitive extensions _REQ, _IND, _RES (or_RSP) and _CFM to show whether the primitive is a service request, indication, response orconfirmation respectively.

In the L2CAP primitive structure there is a member that shows the primitive type. This memberis present in all L2CAP primitives and is used by the recipient to determine what the primitive is.The primitive types are defined in the header file that describes the interface to the moduleconcerned, in this example it would be L2CAP and the header file is l2cap_prim.h.

The scope of the service primitive is limited to the interface to which it relates. It isgenerally defined in a form that is convenient between the layers concerned.

BlueStack includes library functions that generate the downstream service primitives.The user can choose which method to use.

Finally, the primitive can contain a pointer to the location where the userdata is stored. This is presented separately for a number of reasons.

One reason is that the primitive has to be presented to the layer in aform suitable for transmission across a communications link.

In this example, the user data passed to layer N has to be in the formatthat the receiving layer N-1 expects. This is to avoid the need for layerN to have to manipulate this data.

Layer N - 1

Layer N

Layer N + 1

In order to avoid copying data between layers, only a reference to the user data is passedbetween the layers. To support this it must be possible for a layer at one end of the stack toallocate an area of memory that can be identified and freed by a layer at the other end of thestack, once the data has been dealt with. This is achieved in BlueStack by the provision of amemory pool. The memory pool is an area of memory that is available as a shared resource,


Overview

© 2001 32

and is allocated on demand in blocks; the size of block allocated being the nearest size equal toor above the size of the data to be stored. This can be considered to be part of the schedulerservices, although it is independent. Like the rest of the code, it is portable.

An extension of this philosophy is to allow the service primitive to become messages that canbe transmitted across a physical interface. This allows nominally adjoining layers to be locatedon different platforms, which requires a transport mechanism between the two platforms, forexample a serial link. Such a mechanism requires a number of additional rules to be applied toensure that the format of the message is unambiguous. The application of this requires a PortProxy Interface on the host – please contact Mezoe support by e-mail: [email protected] more details.

2.5.1 Interface Library FunctionsFor each API, BlueStack provides a set of interface library functions. These are functions that,when called, generate the required downstream primitive. They are provided to make thewriting of application code simpler.

For example, the code required to create the primitives to read the local device’s Bluetoothaddress and local name can be represented as follows:

/* Request the local BDADDR and the local device name */ DM_HCI_READ_BD_ADDR_T * bdaddr_prim; DM_HCI_READ_LOCAL_NAME_T * name_prim;

bdaddr_prim = (DM_HCI_READ_BD_ADDR_T *) pmalloc(sizeof(DM_HCI_READ_BD_ADDR_T)); bdaddr_prim->common.op_code = DM_HCI_READ_BD_ADDR; dmPutMessage(bdaddr_prim);

name_prim = (DM_HCI_READ_LOCAL_NAME_T *) pmalloc(sizeof(DM_HCI_READ_LOCAL_NAME_T)); name_prim->common.op_code = DM_HCI_READ_LOCAL_NAME;

dmPutMessage(name_prim);

Using the library functions provided by the library file rfcommlib.h, the application codesimplifies to:

/* Request the local BDADDR and the local device name */ dm_hci_read_bd_addr(NULL); dm_hci_read_local_name(NULL);

It is necessary to include the header file rfcommlib.h in the application source codefile in order to be able to use the library functions for the RFCOMM API.

The application developer is free to use either method.

This is an additional feature of BlueStack for version 1.1.1. Application code alreadydeveloped for BlueStack prior to this version does not need to be changed.

The library functions are defined for the following APIs

RFCOMM,- rfcommlib.h



Overview

© 2001 33

TCS Binary- tcs_lib.h– tcs_free_lib.h

SDP– sdclib.h– sdslib.h

DM– dmlib.h– dmlib_sco.h– dmlib_sm.h

L2CAP– l2caplib.h

2.5.2 Registration and phandlesThis section discusses the protocol handles (phandle) and the associated registration processused in the higher layers.

A protocol handle is an abstract reference that identifies a task, for example, in the upper layersof the stack; protocol handles are present in all upstream primitives. A protocol handle, orphandle, in the context of an implementation based on the lightweight scheduler, is the queueidentifier of the upstream protocol software sub-system that a primitive event is being posted to.

Within the upper layers the phandles have two important roles. Firstly, its inclusion within anupstream primitive allows the ‘message’ to be sent via a physical transport mechanism (forexample BCSP) from a software entity on the embedded (host) controller and then routed to thecorrect software sub-system on the host. This is necessary, because the embedded (host)controller does not have any previous knowledge of the scheduler queue assignments on thehost. It gains some knowledge from the registration procedure.

This mechanism is particularly important where the higher layer software sub-systemimplemented on the embedded (host) controller is a multiplexing protocol layer, for exampleRFCOMM or L2CAP. In this case there can be more than one higher layer entitycommunicating via the same API. RFCOMM needs to be able to determine which queue thatan indication received for a specific server channel should be posted.

The registration mechanism allows the higher layer protocols to ‘register’ the queue id as aphandle with the protocol layer below it. In addition, the registration mechanism includes aprotocol specific discriminator so that the association between phandle and the layer specificdiscriminator is made. In the case of RFCOMM, this is the local server channel; in the case ofL2CAP, the Protocol/Service Multiplexer (PSM).

The registration mechanism also allows for future protocols to be registered with L2CAP, forexample, without any need to modify the existing Bluetooth protocol layers.

The dynamism afforded by this can be exploited if required to support different configurations ofhigher layer protocols on top of, for example, L2CAP. This registration must be made intandem with the service registration in the Service Discovery Database. Therefore, it ispossible to alter service configurations on a platform during run-time.


Overview

© 2001 34

2.6 Error Handling and Debug Facilities

BlueStack provides an error handling mechanism, implemented in the error.c file whichcontains the error handling functionality. The error.h file contains the defined error codes.The error handler uses the STRLOG facility. An application may register a call-back function tobe called when BlueStack indicates an error by calling the error handler.

BlueStack proves a debug facility based on a modified version of STRLOG, the STREAMSlogging facility. This facility allows text based debugging to be incorporated within the stack,including the embedded version. The debug messages can be the error codes, or other textmessages.

The STRLOG facility is defined as a macro. Its inclusion is controlled by the compiler directiveSTRLOG_DEBUG. In the non-debug version (release build) the STRLOG is completely absentfrom the compiled code and therefore, the facility is true zero overhead.

When using the STRLOG facility with the BlueStack DLL, the log messages are automaticallyrouted to the Watch Window, if present. Again the compiler directive STRLOG_DEBUG must bedefined.

When the compiler directive is defined, STRLOG may optionally route the logging messages toa file output.log. For further details see BlueStack Porting Guide.

Error messages are listed in Error Codes on page 313.

2.7 Management Entity

The original OSI 7-layer reference model, which has influenced layered protocols such asBluetooth, introduced the concept of a management entity. Within the Bluetooth specification,the HCI is the management interface for the lower layer, the HCI commands and events usethis interface. However, the Bluetooth specification is devoid of any formally defined layermanagement above the HCI.

The integration model, as shown in Figure 2-5 on page 22 is extended to include the stack layermanagement entity elements.

Figure 2-10 on page 35 introduces the Application Management Entity. This is a managemententity element that is specific to the application or applications, and is therefore outside thescope of BlueStack. The management entity above the HCI comprises the ApplicationManagement Entity and the Device Manager. There is a logical partitioning between theApplication Management Entity and the Device Manager. The Device Manager operates at theservice management level, but has no knowledge of the applications; this is the domain of theApplication Management Entity.


Overview

© 2001 35


Link Manager

HCI


SDP

RFCOMM


Management Entity

Provided Application BT AppApplication Layer

Integration Layer



Figure 2-10: Management Entity in the Integrated Application

The purpose of a management entity is best illustrated by means of an example. RFCOMMcan be used to establish a communications link with a remote device, providing that the(Bluetooth device) address of the device is known. In the case of Bluetooth, a facility exists forthe discovery of devices that are within the range of the ‘Inquiring’ device and this facility isavailable within the management entity.

The management entity is also used where there is a conflict for resources. For example, theability to set up a high-bandwidth data link may be compromised by the existence of a SCOconnection. The management entity (with some knowledge of the applications and the relativepriorities as seen by the user) can then take the decision whether to accept a lower bandwidthfor the data connection or to disconnect the SCO link, thus freeing up the bandwidth resource.

A further area where the management entity plays a role is in scenario management. Here themanagement entity takes the decision whether to put connections on hold, or slaves into Parkmode, depending on the applications’ priorities and operational requirements.


Overview

© 2001 36

2.8 Partitioning

BlueStack is configurable to support any one of the following combinations:

Host Embedded Controller

Standard L2CAP, DM, HCI, SDP,PEE/PPE, RFCOMM

LM and HCI

SDP, RFCOMM, PEE/PPE LM, HCI (null), L2CAP, DM

RFCOMM, PEE/PPE LM, HCI (null), L2CAP, DM,SDP

SDP, PEE/PPE LM, HCI (null), L2CAP, DM,RFCOMM

PEE/PPE LM, HCI (null), L2CAP, DM,RFCOMM, SDP

Table 2-1: Allowable BlueStack Partitioning Combinations

In Table 2-1, PEE is the Port Emulation Entity, PPE is the Port Proxy Entity.

In the wholly embedded single processor case, the PEE/PPE is resident on that singleprocessor.

The partitioning configurations listed in Table 2-1 allow the product designer some flexibility inusing the system partitioning model adopted.

If you wish to use a partitioning scheme other than the Standard one shown in Table 2-1 orproxy interfaces please contact Mezoe support by e-mail: [email protected] .

2.9 Porting and Building

The BlueStack protocol software is designed to be portable.

This manual does not include specific details on porting and building, this is described in thedocument BlueStack Porting Guide.



BlueStack Application Interface

© 2001 37

3 BlueStack Application InterfaceThis section provides an overview of the BlueStack Application Interface and an introduction tothe API. This chapter contains the following sections:

� Overview on page 37.

� Key Concepts on page 38.

� Configurability and Tuners on page 41

� Application Interface Functions - Initialisation on page 42

� Application Interface Functions – Scheduler Services on page 50

� Application Interface Functions – Memory Management on page 58

� Application Interface Functions – Utilities on page 64

� Usage Scenarios and Examples on page 69

3.1 Overview

The BlueStack Application Interface provides access to the BlueStack operating environmentservices, and hence to the BlueStack APIs. This interface is defined in the file bluestack.h.This file #includes all the header files required to define the application interfaces that areneeded to access the individual layer APIs.

HCI Top

L2CAP

SDP

Device Mgr

RF

CO

MM

BlueStackOperating

Environment

Application and Integration Layer

bluestack.h

Figure 3-1: The Application Interface to BlueStack.

The services provided via the Application Interface allow the application to:

• initialise the scheduler and BlueStack

• access the memory management functions

• configure the driver for the HCI transport layer

• use the scheduler services such as message passing and timed events.



© 2001 38

The same application interface is used both for the portable code of BlueStack, and theBlueStack library supplied with Proto Developer. This allows users to develop code using ProtoDeveloper, in conjunction with the Microsoft Developer Studio and Visual C++ tools.Developing using Proto Developer is described in the Proto Developer User Guide.

The scheduler and BlueStack initialisation services allow the application to control the start upof the scheduler and BlueStack. Specifically, the application: initialises the scheduler, initialisesthe HCI transport driver, configures BlueStack and starts the scheduler running.

The configuration of BlueStack controls which BlueStack layers have been implemented on thehost. This configuration code does NOT control the configuration of any higher layers that areimplemented in firmware on the host controller device. Hence the configuration of the layers onthe host must reflect the configuration of the firmware on the host controller.

Additionally, the dynamic configuration of the resources assigned to the memory manager canbe selected, provided that this option has been set up by use of the compiler flagPMALLOC_DYNAMIC_LINK. Further configuration options allow the protection of tasks usingmutex.

The memory management functions primarily allow the application to access the same memorymanagement services that the BlueStack protocol software uses. Thus an application canallocate, using pmalloc(), and free memory blocks, using pfree(); typically allocating memoryblocks for downstream messages and freeing the memory blocks of received upstreammessages once the data has been dealt with (consumed).

The memory manager services also include a number of utility functions. These are describedin detail in the section Application Interface Functions - Utilities that starts on page 64.

The HCI Transport driver configuration allows the application to set up the driver for the HCITransport. The functions available via the Application Interface allow the application to find theidentifier for the next available driver, to select a driver, to initialise the selected driver, to findthe identifier of any installed drivers, the query for a specific driver, obtain the driver’s name andits description and to obtain the identifier of a driver from its name.

3.2 Key Concepts

This section discusses the key concepts behind the BlueStack Operating Environment.

3.2.1 The SchedulerThis section introduces the scheduler used by BlueStack, which is fundamental to the operationof the protocol stack. It is recommended that this section is read by all.

The wholly embedded solution uses a lightweight scheduler to co-ordinate the execution of thestack layers. The scheduler has many similarities to a STREAMS1 scheduler and is thereforewell suited for use with protocol stacks. The scheduler is designed to be portable.

There are two options for the porting of the scheduler, either as the sole operatingsystem or as an adaptation layer to work within another operating systemenvironment.

The scheduler provides a single-threaded co-operative non pre-emptive multi-taskingenvironment. This places a requirement on the programmers to ensure that the length of anysingle task execution time is as short as possible so that control is returned to the scheduler assoon as possible.

1 STREAMS was originally developed as a framework for communications services under Unix.



© 2001 39

If tasks take too long to execute, it results in buffer overflows, which couldcause the stack to miss events.

Where there is a possibility that a single task may take too long to execute, it canusually be broken down into several shorter tasks. In this case, the software moduleposts a message back to itself via the scheduler queue, to ensure that the schedulercalls it again to continue the execution later.

A direct consequence of the use of this simple scheduler is that there can be noblocking calls. These cause the stack to halt.

The BlueStack interface philosophy follows on from the use of the scheduler; the APIs to thelayers cannot block. A message passing method is used where a message is sent to aparticular task via the scheduler, using a queue identifier as the destination.

Queue identifiers are set up for the tasks at build time and are part of the schedulerconfiguration. The protocol stack layer queues are pre-assigned to tasks at buildtime.

Queue identifiers are also referred to within the software as protocol handles, or ‘phandles’. Forthe higher layers of BlueStack, a registration procedure is used whereby the phandle of theupper layer is registered with the lower layer before communication starts. This is to allow thedynamic configuration of protocol stacks. Phandles are dealt with in detail in Registration andphandles on page 33.

Although multiple queues can be defined for a task, there is no concept of priority within thescheduler. At best, the task that is called as a result of a message pending can check all of thequeues that are assigned to it, and deal with the messages according to its own definition ofpriority.

When porting to an application environment that uses blocking API calls, choose anoperating system that supports multiple threads and port BlueStack as a singlethread.

The scheduler executes the tasks that have messages pending. It is up to the software moduleto pull the message or messages from the queue and to act on them. The result of this is thatthe entire protocol stack is message driven.

The scheduler provides timer support. Timer support is hardware dependent and any port to adifferent platform needs to take this fact into consideration.

As part of the scheduler and communications services environment support, a mechanism forthe management of memory pools is included. This allows an entity to allocate a block ofmemory for some data using pmalloc(), and for this block of memory to be returned to thepool, via pfree(), once the data in it has been transmitted or consumed internally.

3.2.2 Inter-process Communication, Messaging and EventsInter-process communication (other than direct function calls) is handled using messages thatare posted via the operating system to the destination task. There is a scheduler function callput_message(QID, MID, *data), where the QID is the centrally defined queue ID (which maybe provided as a phandle), MID is a message type that is valid for this task, and *data is apointer to data. The message types are globally defined in the common file bluetooth.h.

#define Reserved 1#define Reserved 2#define Reserved 3#define DM_PRIM 4#define L2CAP_PRIM 5



© 2001 40

#define RFCOMM_PRIM 6#define SDP_PRIM 7#define Reserved 8#define Reserved 9#define Reserved 10#define Reserved 11#define TCS_PRIM 12

Additional local message types can be defined. In this case, care must be taken indesign to ensure that the actual numerical values assigned for local and globalmessages do not overlap.

We can illustrate the message passing as follows. In the example (Figure 3-2) Task 1 is‘putting’ a message to the scheduler. The message is destined for Task 2 and has a queue idthat corresponds to Task 2.

Task 1

Task 2

put_message(qid = 2, mid,data)

when scheduled, callsTask 2

Scheduler

Figure 3-2: Illustration of Event Handling and Message Passing

The scheduler is a simple, equal priority (round-robin) scheduler and calls Task 2 when itdetects that there is an event pending for it. When Task 2 is called it reads the events from theevent queue.

3.2.3 Communications ServicesThe inter-process communication method is used for the provision of basic communicationservices. This allows the interfaces between (layer) sub-systems to be defined in terms ofservice primitives, as discussed earlier (Internal Communications Model Adopted for BlueStackon page 29). The service primitives are associated with a specific message id, so that thescope is restricted to a specific interface.

The communication method can be illustrated by means of the following example. If event typeof prim_msg is defined, the event handler for a particular process would switch on this messagetype and send all prim_msg events to a message handler.

The message handler then has a structure:

static void message_handler(UPRIM_MSG_T* msg_ptr){ /* Switch on the type of message */ switch(msg_ptr->type) {



© 2001 41

case CONNECTION_REQ:

In order to achieve this, all primitives are defined in a consistent manner and are placed into aunion (of type UPRIM_MSG_T). The consistency of the primitives is restricted to the commonfields that appear at the beginning of a structure e.g. type. All other data elements can bespecific to the primitive.

The primitives can include a pointer to a data buffer. This is useful where the buffer containsdata that is going to be sent over the air (effectively the Service Data Unit).

prim_type

primitivespecific data

msg_ptr

Union

Figure 3-3: Primitive Definition Format

3.2.4 Timed EventsThe scheduler supports timed events. The events can be either the passing of messages, asalready described in the section that starts on page 39, or function calls. The schedulerservices include function calls to deliver a message, or call the specified function, at a certaintime or after a time delay.

The timed event mechanism for calling specified functions is useful for call back functions fromthe BlueStack protocol software to the application. By using the function callBST_timed_event_in() with zero delay, the call back function is called at the first opportunityby the scheduler, rather than from within the same thread as the BlueStack protocol software.

3.3 Configurability and Tuners

The memory manager allows for both a dynamic and static build of the memory pool. The buildtime flag PMALLOC_DYNAMIC_LINK is used to set the configuration option for the dynamic build.Using the dynamic build allows the memory pool block sizes, and number of blocks, to beconfigured from the application during initialisation, using the BST_ReconfigurePool()function.

Proto Developer uses a dynamic implementation of the Application Interface, whereas theBlueStack portable source code uses a static implementation of this interface. These areconfigured automatically in the delivered code and there is no need for user configuration of thisoption.



© 2001 42

3.4 Application Interface Functions – Initialisation

This section covers the functions related to stack and HCI driver initialisation

3.4.1 BST_InitScheduler

void BST_InitScheduler( uint16_t u_instance )

Description

Initialises the BlueStack scheduler. The u_instance argument is the stack instance to use forregistering the task ids with the BSDK comms DLL (Proto Developer). It is only used if thecompile flag for the Watch Window, BSDKWATCH, is defined.

Parameters

u_instance The instance identifier of the associated watch window. This is only used whenBlueStack is being used with Proto Developer. Set to 0 for non ProtoDeveloper use.

Returns

Void

3.4.2 BST_ConfigureStack

void BST_ConfigureStack( bst_configuration_t configuration )

Description

Configures which layers run on the host and which layers are proxied onto the host controller.This only applies for any layers which have been built to support both configurations; layers builtwith only one configuration cannot be configured differently.

If used, this function must be called after BST_InitScheduler() and beforeBST_StartScheduler().

Parameters

configurationThe configuration of the higher layers of the protocol stack on the host. Thismust be set to complement the configuration of the protocol layers on the hostcontroller. The following values are defined, there being 1 bit in the bit fielddefined per layer to indicate whether it is on the host or accessed via a proxywhere it is on the host controller. A second bit indicates whether the protocollayer is present at all within the particular implementation.

BST_CONF_DM_PROTOCOLBST_CONF_DM_PROXY



© 2001 43

BST_CONF_L2CAP_PROTOCOLBST_CONF_L2CAP_PROXYBST_CONF_RFCOMM_PROTOCOLBST_CONF_RFCOMM_PROXYBST_CONF_SDP_PROTOCOLBST_CONF_SDP_PROXYBST_CONF_TCS_PROTOCOLBST_CONF_TCS_PROXY

For example, the configuration for a cordless telephony example with no RFCOMM andall higher layers on the host would beconfiguration = BST_CONF_DM_PROTOCOL + BST_CONF_L2CAP_PROTOCOL +BST_CONF_SDP_PROTOCOL + BST_CONF_TCS_PROTOCOL;

Alternatively, the configuration for a serial port profile example (no TCS) and all higherlayers on the host controller (on chip) would beconfiguration = BST_CONF_DM_PROXY + BST_CONF_L2CAP_PROXY +BST_CONF_SDP_PROXY + BST_CONF_RFCOMM_PROXY;

Returns

Void

3.4.3 BST_StartScheduler

void BST_StartScheduler( bool_t block )

Description

Starts the BlueStack scheduler. This function must be preceded by calls to BST_Register()(Windows applications using the BlueStack DLL only), BST_InitScheduler(), andBST_InitHCIdrv().

Parameters

block This flag controls whether the scheduler runs in the calling thread (block = TRUE, inwhich case the function never returns), or whether the scheduler is started in a newthread (block = FALSE).

Returns

void



© 2001 44

3.4.4 BST_sched_protect_tasks

void BST_sched_protect_tasks( bool_t protect )

Description

Configures the scheduler to wrap all task entry points in a mutex. This includes task messagehandler functions, timed event handlers, and background interrupt handlers. The mutex canalso be claimed from outside the scheduler by calling sched_claim_task_mutex(), andthen sched_release_task_mutex() when no longer required.

The reason for this is to ensure that task code which may be called from an application runningin a separate thread does not pre-empt task code which is being run from the scheduler, andvice-versa. Such an application should call sched_protect_tasks(TRUE) at initialisation,and should then wrap all calls into task code between calls to thesched_claim_task_mutex() and sched_release_task_mutex() functions.

It is recommended that scheduler tasks should only be protected in systems which implementmutexes through use of proper synchronisation objects, provided by the underlying operatingsystem. Mutexes that simply disable interrupts could cause the system to run for long periodsof time with interrupts disabled.

Parameters

protect This flag controls whether the scheduler is configured to wrap all task entrypoints in a mutex (protect = TRUE) or not (protect = FALSE).

Returns

void

3.4.5 BST_ReconfigurePool

void BST_ReconfigurePool( const PDB_T new_pdbs[],const uint32_t new_n_pools )

Description

Reconfigure the memory pool blocks available to pmalloc(), if the dynamic configurationmechanism is selected (PMALLOC_DYNAMIC_LINK build option). If called, this function must becalled AFTER BST_InitScheduler() and BEFORE BST_StartScheduler().

The memory referenced by new_pdbs[] MUST be either static or malloc()ed from the system’smemory resources.

If the compiler flag PMALLOC_DYNAMIC_LINK is not defined, the pool blocks are configuredstatically by the application's own pool.c file.



© 2001 45

This function is optional. If it is not called, the pools will default as follows:

el_size n_els4 9012 6020 2040 1572 8

132 40260 2

Parameters

new_pdbs[] This is an array of the structure type PDB_T

typedef struct

{

uint32_t el_size; /* Size of elements in the pool */

uint32_t n_els; /* How many elements in the pool */

uint32_t pool_size; /* (el_size * n_els) */

} PDB_T;

n_els Number of elements in the array.

An example of the use of this command is found in the Scheduler and BlueStack Initialisationexample on page 69.

Returns

void

3.4.6 BST_InitHCIdrv

bool_t BST_InitHCIdrv( uint8_t *sz_config )

Description

Initialise the HCI driver. This function must be called AFTER BST_InitScheduler() andBEFORE BST_StartScheduler().

Parameters

*sz_config Driver-specific configuration string

For the "bc01USB" driver, "[device:<USB device name>]"Examples:

NULL"""device:\\\\.\\CSR0"



© 2001 46

For the "bcsp" and "h4" drivers,"[port:<COM port name>] [baud:<baud rate, 9600, 115200 etc>] [data:<number of data bits, 5,

6, 7, 8>] [parity:<parity, n, e, o, m, s>] [stop:<stop bits, 1, 1.5, 2>] [flow:<flowcontrol, none, dtrdsr, rtscts, xonxoff>]"

Examples:NULL"""port:com2""baud:115200""port:com4 baud:57600 parity:n"

Default settings for USB:device:\\\\.\\CSR0

Default settings for BCSP:port:COM1 or port:/dev/ttyS0 on Linuxbaud:115200data:8parity:estop:1flow:none

Default settings for H4:port:COM1baud:115200data:8parity:nstop:1flow:rtscts

Returns

bool_t - TRUE if successful, FALSE on failure.

3.4.7 BST_HCIdrv_enum_drivers

hcidrv_driver_id_t BST_HCIdrv_enum_drivers(hcidrv_driver_id_t previous,const uint8_t **psz_driver_name,const uint8_t **psz_driver_description )

Description

HCI driver enumeration function. Call it first with HCIDRV_NONE, and it will return the id, nameand description of the first available driver. Call it again with the previously returned id to get thenext available driver. Returns HCIDRV_NONE at the end of the available drivers.



© 2001 47

Parameters

previous Set to HCIDRV_NONE to request the first available driver, or the identifier of adriver to request the next available driver.

**psz_driver_name Location where HCIdrv can write the pointer to the drivername.

**psz_driver_description Location where HCIdrv can write the pointer to thedriver description.

Returns

hcidrv_driver_id_t the identifier of next available driver, or HCIDRV_NONE.

3.4.8 BST_HCIdrv_select_driver

bool_t BST_HCIdrv_select_driver( hcidrv_driver_id_t driver_id )

Description

Requests the selection of the specified HCI driver, which will then be used for communicationwith the Host Controller. Any subset of all HCI drivers may be included in a build of the stack.The user must select a valid driver before calling BST_InitHCIdrv().

The function must be called successfully before any call to BST_InitHCIdrv(), and it mustnever be called after a call to BST_InitHCIdrv() has been made. It is not possible to changethe driver once it has started.

Parameters

Driver_id Identifier of the required driver.

Returns

Boolean, returns TRUE if the specified driver is available, and has been installed correctly orFALSE if it is unknown or unavailable.

3.4.9 BST_HCIdrv_get_current_driver

hcidrv_driver_id_t BST_HCIdrv_get_current_driver(void)



© 2001 48

Description

Requests the identifier of the current HCI driver.

Parameters

void.

Returns

Identifier of the installed driver. Returns HCIDRV_NONE if no driver installed.

3.4.10 BST_HCIdrv_query_driver_available

bool_t BST_HCIdrv_query_driver_available(hcidrv_driver_id_t driver_id )

Description

Query whether the HCI driver identified by ’driver_id’ is available in this build of the stack.

Parameters


Returns

Boolean, returns TRUE if the specified driver is available, or FALSE if it is unknown orunavailable.

3.4.11 BST_HCIdrv_get_driver_name

const uint8_t * BST_HCIdrv_get_driver_name(hcidrv_driver_id_t driver_id )

Description

Requests the name of the driver specified in ’driver_id’.

Parameters




© 2001 49

Returns

const uint8_t* pointer to name of the driver, can be NULL

3.4.12 BST_HCIdrv_get_driver_description

const uint8_t * BST_HCIdrv_get_driver_description(hcidrv_driver_id_t driver_id )

Description

Requests the description of the driver specified in ’driver_id’.

Parameters


Returns

const uint8_t* pointer to description of the driver, can be NULL

3.4.13 BST_HCIdrv_get_driver_id

hcidrv_driver_id_t BST_HCIdrv_get_driver_id(const uint8_t *sz_name )

Description

Converts the textual name of a driver, eg "bcsp", "usb", into a driver identifier. The name stringmay contain additional characters after the driver name, as long as the driver name itself isseparated by one of nul, space, tab, comma, or quotation marks.

Parameters

*sz_name Pointer to the null terminated string containing the driver name.

Returns

The identifier of the driver. Returns HCIDRV_NONE if no driver identified from the suppliedstring.



© 2001 50

3.5 Application Interface Functions – Scheduler Services

This section covers the functions related to the scheduler services, including timers.

3.5.1 BST_putMessage

void BST_putMessage( bst_task_queue_id_t queue,uint16_t id,void *pv_message)

Description

Send a message to a BlueStack task queue. The queue identifier must be one of the valuesdefined in the bst_xxx_queue identifiers which are exported by this module.

Parameters

queue Identity of the destination queue. The queue identities are defined within the filebluestack.h:bst_am_queue;bst_sco_queue;bst_pe_queue;bst_ts_queue;bst_sda_queue;bst_test_queue;bst_dm_iface_queue;bst_rfcomm_iface_queue;bst_sdp_iface_queue;bst_l2cap_iface_queue;bst_tcs_iface_queue;

id Identifier of the message. The message types are globally defined in the common filebluetooth.h. See also the section Inter-process Communication, Messaging andEvents on page 39.

*pv_message Pointer to the memory containing the message.

Returns

void



© 2001 51

3.5.2 BST_getMessage

void BST_getMessage( bst_task_queue_id_t queue,uint16_t *p_id,void **ppv_message )

Description

Receives a message from a BlueStack task queue. The queue identifier must be one of thevalues defined in the bst_xxx_queue identifiers which are exported by this module.

Parameters

queue Identity of the destination queue. The queue identities are defined within the filebluestack.h:bst_am_queue;bst_sco_queue;bst_pe_queue;bst_ts_queue;bst_sda_queue;bst_test_queue;bst_dm_iface_queue;bst_rfcomm_iface_queue;bst_sdp_iface_queue;bst_l2cap_iface_queue;bst_tcs_iface_queue;

*p_id Pointer to the identifier of the message. The message types are globally defined in thecommon file bluetooth.h. See also the section Inter-process Communication,Messaging and Events on page 39.

**ppv_message Pointer to the memory containing the pointer to the message.

Returns

void

3.5.3 BST_put_message_at

msgid BST_put_message_at( TIME when,bst_task_queue_id_t q,uint16_t mi,void *mv );



© 2001 52

Description

Sends a message consisting of the integer mi and the void* pointer mv to the message queue qat time when. The values of mi and mv are neither inspected nor changed by the scheduler -the task that owns q is expected to make sense of the values.

The pointer mv may be NULL.

The period of when must be less than half the range of a TIME. TIME is defined as auint32_t with a tick time of 1 microsecond.

Parameters

when Time at when the message is to be delivered.

q Identity of the destination queue. The queue identities are defined within the filebluestack.h:bst_am_queue;bst_sco_queue;bst_pe_queue;bst_ts_queue;bst_sda_queue;bst_test_queue;bst_dm_iface_queue;bst_rfcomm_iface_queue;bst_sdp_iface_queue;bst_l2cap_iface_queue;bst_tcs_iface_queue;

mi Identifier of the message. The message types are globally defined in the common filebluetooth.h. See also the section Inter-process Communication, Messaging andEvents on page 39.

*mv Pointer to the memory containing the message.

Returns

msgid - A message identifier, can be used with cancel_timed_message().

3.5.4 BST_put_message_in

msgid BST_put_message_at( TIME delay,bst_task_queue_id_t q,uint16_t mi,void *mv );



© 2001 53

Description

Sends a message consisting of the integer mi and the void* pointer mv to the message queue qafter a time delay. The values of mi and mv are neither inspected nor changed by thescheduler - the task that owns q is expected to make sense of the values.

The pointer mv may be null.

The period delay must be less than half the range of a TIME.

Parameters

delay Time after which the message is to be delivered. TIME is defined as a uint32_t witha tick time of 1 microsecond.

q Identity of the destination queue. The queue identities are defined within the filebluestack.h:bst_am_queue;bst_sco_queue;bst_pe_queue;bst_ts_queue;bst_sda_queue;bst_test_queue;bst_dm_iface_queue;bst_rfcomm_iface_queue;bst_sdp_iface_queue;bst_l2cap_iface_queue;bst_tcs_iface_queue;

mi Identifier of the message. The message types are globally defined in the common filebluetooth.h. See also the section Inter-process Communication, Messaging andEvents on page 39.

*mv Pointer to the memory containing the message.

Returns

msgid - A message identifier, can be used with cancel_timed_message().

3.5.5 BST_cancel_timed_message

bool_t BST_cancel_timed_message( bst_task_queue_id_t q,msgid mid,uint16_t *pmi,void **pmv )



© 2001 54

Description

Attempts to prevent delivery of the message with message identifier mid which was previouslyscheduled to be delivered to message queue q"using either put_message_at() orput_message_in().

Parameters

q Identity of the queue on which there is a message pending.

mid Message identifier of the message to be cancelled. This will have been returned from acall to put_message_at() or put_message_in().

*pmi Pointer to the identifier of the message. The message types are globally defined in thecommon file bluetooth.h. See also the section Inter-process Communication,Messaging and Events on page 39.

**pmv Pointer to the memory containing the pointer to the message.

Returns

TRUE if the message was cancelled before the task owning the queue was scheduled, elseFALSE.

3.5.6 BST_timed_event_at

tid BST_timed_event_at( TIME when,void (*fn)(uint16_t, void *),uint16_t fniarg,void *fnvarg )

Description

Causes the void function fn to be called with the arguments fniarg and fnvarg at timewhen.

The function will be called at or after when; the actual delay will depend on the timing behaviourof the scheduler’s tasks.

Parameters

when Time at when the specified function is to be called. This must be less than half therange of TIME. TIME is defined as a uint32_t with a tick time of 1 microsecond.Thus the maximum time is then of the order of 35 hours.

fn Name of the function to be called.



© 2001 55

fniarg Argument associated with the function. This is application dependent and notmodified in any way by timed_event_at().

*fnvarg Argument associated with the function. This is application dependent and notmodified in any way by timed_event_at().

Returns

tid - A timed event identifier, can be used in cancel_timed_event().

3.5.7 BST_timed_event_in

tid BST_timed_event_in( TIME delay,void (*fn)(uint16_t, void *),uint16_t fniarg,void *fnvarg )

Description

Causes the void function fn to be called with the arguments fniarg and fnvarg after a timedelay has elapsed.

The function will be called at or after delay; the actual delay will depend on the timingbehaviour of the scheduler’s tasks.

Parameters

delay Time after which the specified function is to be called. TIME is defined as a uint32_twith a tick time of 1 microsecond.

fn Name of the function to be called.

fniarg Argument associated with the function. This is application dependent and notmodified in any way by timed_event_in().

*fnvarg Argument associated with the function. This is application dependent and notmodified in any way by timed_event_in().

Returns

tid - A timed event identifier, can be used in cancel_timed_event().

3.5.8 BST_cancel_timed_event

bool_t BST_cancel_timed_event( tid eventid,uint16_t *pmi,void **pmv )



© 2001 56

Description

Attempts to prevent the timed event with identifier eventid from occurring.

Parameters

eventid Identifier of the timed event to be cancelled.

*pmi Pointer to the identifier of the message. The message types are globally defined in thecommon file bluetooth.h. See also the section Inter-process Communication,Messaging and Events on page 39.

**pmv Pointer to the memory containing the pointer to the message.

Returns

TRUE if the event was cancelled before the event was scheduled, else FALSE.

3.5.9 BST_get_time

TIME BST_get_time(void)

Description

Gets the current BlueStack scheduler time.

Parameters

void

Returns

TIME. - the current system time

3.5.10 BST_sched_claim_task_mutex

void BST_sched_claim_task_mutex(void)

Description

Called by an application to ensure safe entry into task code from another thread, assuming thatthe scheduler has been configured to protect its tasks by a previous call tosched_protect_tasks(TRUE).



© 2001 57

Parameters

void

Returns

void

3.5.11 BST_sched_release_task_mutex

void BST_sched_release_task_mutex(void)

Description

If an application calls sched_claim_task_mutex(), it must make a corresponding call tosched_release_mutex() on exit from the task code.

Parameters

void

Returns

void

3.5.12 BST_CallbackOnPanic

void BST_CallbackOnPanic( void (*fn)(char *) )

Description

Registers a function to be called should the scheduler panic, as it may do if it runs out ofmemory blocks for example. The registered function is passed a string giving the reason for thepanic. See the Callback on Panic example on page 71.

If this function is not called, then if and when panic() is called the application will executeexit(1).

Parameters

(*fn)(char *) Pointer to the function fn to be called when panic*() and passed astring.

Returns

void



© 2001 58

3.6 Application Interface Functions – Memory Management

This section covers the functions related to the memory management services.

3.6.1 BST_pmalloc

void* BST_pmalloc(uint32_t size)

Description

Allocates a memory block of size from the pool to the requesting module. If the memorymanager is unable to allocate a memory block that satisfies the request, will cause the memorymanager to panic().

See the section Memory Management Functions on page 24 for further details of the memoryblocks and pool.

Parameters

size Size (in bytes) of the memory block required.

Returns

A void* pointer to allocated memory block

3.6.2 BST_pfree

void BST_pfree(void *ptr)

Description

Returns a memory block previously obtained to the pool.

Parameters

*ptr Pointer to the memory block that is now no longer required.

Returns

void



© 2001 59

3.6.3 BST_zpmalloc

void* BST_zpmalloc(uint32_t size)

Description

Allocates a memory block of size from the pool to the requesting module and sets it to allzeroes. If the memory manager is unable to allocate a memory block that satisfies the request,will cause a panic().

Parameters


Returns

A void* pointer to allocated block

3.6.4 BST_xpmalloc

void* BST_xpmalloc(uint32_t size)

Description

Allocates a memory block of size from the pool to the requesting module. If the memorymanager is unable to allocate a memory block that satisfies the request, will return NULL.

Parameters


Returns

A void* pointer to the allocated block, NULL on failure.

3.6.5 BST_xzpmalloc

void* BST_xzpmalloc(uint32_t size)

Description

Allocates a memory block of size from the pool to the requesting module and sets it to allzeroes. If the memory manager is unable to allocate a memory block that satisfies the request,will return NULL.



© 2001 60

Parameters


Returns

A void* pointer to allocated block, NULL on failure.

3.6.6 BST_RFC_DLC_malloc

void *BST_RFC_DLC_malloc( uint8_t mux_id,uint8_t server_channel,uint32_t size )

Description

Allocates a memory block of size from either the reserve list or the general pool to therequesting module. The function must be used the Port Entity for memory allocation of all dataframes. If the memory manager is unable to allocate a memory block that satisfies the request,NULL is returned.

Parameters


mux_id RFCOMM multiplexor ID, see page 74 for further details.

server_channel RFCOMM local server channel, see page 74 for further details.

Returns

A void* pointer to allocated block, NULL on failure.

3.6.7 BST_prealloc

void* BST_prealloc(void *ptr, uint32_t size)

Description

Changes the size of the memory block referenced by ptr to size bytes, and returns a pointerto the block satisfying the request. It is presumed that ptr has previously been obtained byone of the Memory Management routines. The memory block’s contents will be unchanged upto the lesser of the new and old sizes.

If ptr is null then the function behaves as pmalloc().



© 2001 61

If the memory manager is unable to allocate a memory block that satisfies the request, willcause a panic().

Parameters


*ptr Pointer to the existing memory block containing the data that is to be resized

Returns

A void* pointer to resized pool memory block.

3.6.8 BST_xprealloc

void* BST_xprealloc(void *ptr, uint32_t size)

Description

Changes the size of the memory block referenced by ptr to size bytes, and returns a pointerto the block satisfying the request. It is presumed that ptr has previously been obtained byone of the Memory Management routines. The memory block’s contents will be unchanged upto the lesser of the new and old sizes.

If ptr is null then the function behaves as xpmalloc().

If the memory manager is unable to allocate a memory block that satisfies the request, willreturn NULL.

Parameters


*ptr Pointer to the existing memory block containing the data that is to be resized

Returns

A void* pointer to resized pool memory block, NULL on failure.



© 2001 62

3.6.9 BST_pcopy

void* BST_pcopy(void *s, uint32_t n)

Description

Allocates a block of memory suitable to store n bytes of data and copies n bytes of data fromthe buffer pointed to by s into it. If the memory manager is unable to allocate a memory blockthat satisfies the request, will cause a panic().

Parameters

n Size (in bytes) of the memory block to be copied.

*s Pointer to the existing memory block containing the data that is to be copied.

Returns

A void* pointer to copied pool memory block containing the copy of the buffer.

3.6.10 BST_xpcopy

void* BST_xpcopy(void *s, uint32_t n)

Description

Allocates a block of memory suitable to store n bytes of data and copies n bytes of data fromthe buffer pointed to by s into it. If the memory manager is unable to allocate a memory blockthat satisfies the request, will return NULL.

Parameters

n Size (in bytes) of the memory block to be copied.

*s Pointer to the existing memory block containing the data that is to be copied

Returns

A void * pointer to copied pool memory block, NULL on failure.



© 2001 63

3.6.11 BST_pstrdup

void* BST_pstrdup(void *s)

Description

Allocates a block of memory suitable to store the null terminated string in the buffer pointed toby s, and copies that string into the memory block. If the memory manager is unable to allocatea memory block that satisfies the request, will cause a panic().

Parameters

*s Pointer to the existing memory block containing the null terminated string that is to becopied.

Returns

A void* pointer to copied pool memory block containing the copy of the buffer.

3.6.12 BST_xpstrdup

void* BST_xpstrdup(void *s)

Description

Allocates a block of memory suitable to store the null terminated string in the buffer pointed toby s, and copies that string into the memory block. If the memory manager is unable to allocatea memory block that satisfies the request, will return NULL.

Parameters

*s Pointer to the existing memory block containing the null terminated string that is to becopied.

Returns

A void* pointer to copied pool memory block containing the copy of the buffer, NULL onfailure.



© 2001 64

3.7 Application Interface Functions – Utilities

This section covers the utility functions that provide services such as sending text to ProtoDeveloper Watch Windows, obtaining queue identitifers, and manipulating Bluetooth deviceaddresses.

3.7.1 bd_addr_copy

void bd_addr_copy( BD_ADDR_T *p_bd_addr_dest,const BD_ADDR_T *p_bd_addr_src )

Description

Copies the source Bluetooth device address into the destination Bluetooth device address.

Parameters

*p_bd_addr_src Pointer to the memory containing the Bluetooth device address that isto be copied.

*p_bd_addr_dest Pointer to the memory into which the Bluetooth device address is to becopied.

Returns

void

3.7.2 bd_addr_zero

void bd_addr_zero( BD_ADDR_T *p_bd_addr )

Description

Set the Bluetooth address structure to all zeroes.

Parameters

*p_bd_addr Pointer to the memory containing the Bluetooth device address structure that isto be set to zero

Returns

void



© 2001 65

3.7.3 bd_addr_eq

bool_t bd_addr_eq( const BD_ADDR_T *p_bd_addr_1,const BD_ADDR_T *p_bd_addr_2)

Description

Compares two BD Addresses for equality.

Parameters

*p_bd_addr_1 Pointer to the memory containing the first Bluetooth device addressstructure that is to be compared.

*p_bd_addr_2 Pointer to the memory containing the second Bluetooth device addressstructure that is to be compared with the first.

Returns

TRUE if equal, FALSE if different.

3.7.4 BST_ReportPoolStats

void BST_ReportPoolStats(char *sz_buf, uint32_t buf_size )

Description

Write a string into the buffer sz_buf of size buf_size, that describes the Memory Manager’s useof its resources.

The report is a string written into the buffer provided. The string is returned in the followingformat:

%u,%u,%u,%u,%u*%u,%u,%u,%u,%u*%u,%u,%u,%u,%u*...*%u,%u

Where each set of 5 integers (seperated by *) represent the statistics for each block sizeavailable in the pool. The 5 integers are:

1. The size of the block,2. The total number of blocks of this size,3. The number of blocks currently in use (i.e. that have been obtained by pmalloc),4. The maximum number of blocks of this size that have ever been ‘taken’ at one time,5. The number of times that a block of this size has been requested but not been available

(overflows). In this case a block of the next highest size will be allocated.

The final two integers represent the current total pmalloc memory use (in bytes) and themaximum pmalloc memory used at any one time.

Parameters

buf_size Size (in bytes) of the buffer. The function will truncate the data if the buffer sizeis less than the data size. As a guide, a buffer size of about 200 bytes shouldbe sufficient for most purposes.



© 2001 66

*sz_buf Pointer to the buffer into which the data is to be written into.

Returns

void

3.7.5 BST_ReportPoolUsage

void BST_ReportPoolUsage(char *sz_buf, uint32_t buf_size )

Description

Write a string into the buffer sz_buf of size buf_size, that describes which software modulesare using the Memory Manager’s resources.

The report is a string written into the buffer provided. The string is a list of references to lines ofcode that allocated a pmalloc block.

The references are in the form:

123=appcode.c:456,…

Which is interpreted as block index number 123 being allocated at line 456 of file appcode.c.

Parameters

buf_size Size (in bytes) of the buffer.

*sz_buf Pointer to the buffer into which the data is to be written into.

Returns

void

3.7.6 BST_SendWatchText

void BST_SendWatchText( uint32_t layer,uint32_t dirn,char *sz_string,void *p_format_argument );

Description

This function sends a text string to the currently connected Watch Window. A layer anddirection can be specified, in which case, the string will be formatted in the same way as aprimitive.



© 2001 67

The main use for this function however is to display debugging information, progress reports,comments, etc. from the application. In this case, use NO_LAYER for the layer andDIRN_NOSTREAM for the direction.

The pString and pFormatArgument are in effect passed through sprintf before going to theWatch Window, as:

sprintf( outputString, pString, *pFormatArgument );

Notice the dereference. This example shows correct use of pFormatArgument:

unsigned int uiInstance = 0;BST_SendWatchText(NO_LAYER, DIRN_NOSTREAM, "Instance number is%d", &uiInstance);

If no Watch Window is connected, this function has no effect.

Parameters

layer Sending layer, of type layer_t, can take a value of:DM_LAYERHCI_LAYERL2CAP_LAYERNO_LAYERDATA_LAYERCONTROL_LAYERMACRO_LAYERRFCOMM_LAYERSDP_LAYERTCS_LAYER

dirn Direction, of type direction_t, can taka a value of:DIRN_UPSTREAMDIRN_DOWNSTREAMDIRN_NOSTREAM

*sz_string Pointer to the printf() style formatting string.

*p_format_argument Pointer the the variable argument list. If this is not used, itmust be set to NULL.

Returns

void

3.7.7 BST_send_watch_text

void BST_send_watch_text(char *sz_string)

Description

Sends a string to the watch window.

Parameters



© 2001 68

*sz_string Pointer to the string.

Returns

void

3.7.8 BST_get_config_string

void BST_get_config_string( uint32_t argc,uint8_t *argv[],uint8_t *sz_dest,uint32_t size_dest)

Description

A utility function which applications may use to concatenate their command-line arguments intoa single string. This is useful for HCI driver configuration, as the drivers take a single stringcontaining their settings.

Parameters

argc Number of elements (strings) in the array argv[].

*argv[] Pointer to the array containing the strings.

*sz_dest Pointer to the destination buffer into which the strings are to be concatenated.

size_dest Maximum size of the destination buffer.

Returns

void

3.7.9 BST_get_scheduler_identifier

scheduler_identifier BST_get_scheduler_identifier(void)

Description

A utility function which applications may use to obtain a unique identifier.

Identifiers are used to number various dynamic elements in the scheduler. Identifiers can alsobe used by dynamic elements outside the scheduler, e.g. for identifying messages.

Parameters

void



© 2001 69

Returns

A scheduler identifier that is currently unused.

3.8 Usage Scenarios and Examples

This section provides a number of usage scenarios for the BlueStack Application Interface.

3.8.1 Scheduler and BlueStack InitialisationInitialisation consists of a number of steps, some of which are optional. What is shown is thegeneral case of initialisation for BlueStack. The BlueStack demonstration application providedwith Proto Developer also shows the intitialisation of BlueStack, but for the case where there isa Watch Window launched as part of the procedure.

Initialise Scheduler

/* Initialise the BlueStack Scheduler. */ uint16_t instance = 0; BST_InitScheduler(instance);

Configure Scheduler to be thread safe

Optional – use if in a multi-threaded environment

/* We may be running in a multithreaded environment, so make sure that * task code is threadsafe. */ BST_sched_protect_tasks(TRUE);

Configure Memory Pools

Optional – use only if PMALLOC_DYNAMIC_LINK has been set as a compiler flag

This should be restricted to developments using the BlueStack DLL supplied withProto Developer.

/* Set the pools configuration *//* this uses BST_ReconfigurePool(new_pdbs, n_pools); */

The new_pdbs argument is a const array of type PDB_T, which is defined in"BlueStack/src/scheduler/pmalloc/pools.h" as:

typedef struct

{

uint32_t el_size; /* Size of elements in the pool */

uint32_t n_els; /* How many elements in the pool */

uint32_t pool_size; /* (el_size * n_els) */

} PDB_T;

Each array entry defines a pool containing n_els elements of el_size bytes each. Theparameter pool_size must be el_size * n_els. The entries in the array must be in orderof increasing element size. There is no array terminator.

The n_els argument is the number of entries in the array.



© 2001 70

For example:

const PDB_T pools_pdbs[] =

{

/* { el_size, n_els, pool_size }, */

{ 4, 80, 320 },

{ 12, 60, 720 },

{ 20, 20, 400 },

{ 40, 15, 600 },

{ 72, 8, 576 },

{ 264, 20, 5280}

};

BST_ReconfigurePool(pools_pdbs, 6);

Configure Scheduler for the partitioning configuration, i.e. on-chip or on host.

/* Configure BlueStack to use proxies or protocols */ if (proxies)) { BST_ConfigureStack(BST_CONF_ALL_PROXIES); } else { BST_ConfigureStack(BST_CONF_ALL_PROTOCOLS); }

Configure and select the HCI Driver.

In this example the bcsp driver for the CSR device is selected

driver_id = BST_HCIdrv_get_driver_id("bcsp");

/* Select the HCI driver */ if (BST_HCIdrv_select_driver(driver_id)) { /* Initialise the HCI driver */ if (!BST_InitHCIdrv((uint8_t *) sz_phys_config)) { /* report error, initialisation of driver failed */ } } else { /* report error, driver not available */ }

Start Scheduler

For the case where the scheduler runs in the calling thread.

BST_StartScheduler(TRUE);



© 2001 71

3.8.2 Sending MessagesFor example, to send the Device Manager a command to read the local name:

name_prim = pnew(DM_HCI_READ_LOCAL_NAME_T);name_prim->common.op_code = DM_HCI_READ_LOCAL_NAME;put_message(DM_IFACEQUEUE, DM_PRIM, name_prim);

3.8.3 Getting MessagesThe code fragment below shows an application manager handler function:

void am_handler_fn( uint16_t unused_iface,void *unused_prim,void *unused_apdata)

{ uint16_t m;

void * prim;char buf[80];

/* Retrieve the message */ get_message(amqueue, &m , &prim);

/* Determine what type of message is being sent */switch(m){case DM_PRIM:

/* Decide what type of DM primitive is being sent */switch((DM_UPRIM_T *)prim->type) { case DM_HCI_REMOTE_NAME_COMPLETE:

/* Do something useful – perhaps display it */ break; /* ……… */ }break;/* ………… */}

/* ALWAYS pfree the primitive – otherwise the pool will leak */pfree(prim);}

3.8.4 Callback on PanicDefine a callback function to be called if and when the scheduler panic()s, and register it.

static void PanicHandler ( char * panicMsg ){

BST_SendWatchText ("PANIC: %s ", panicMsg);ExitThread(1);

}

/* Register a function to be called should the scheduler 'panic' */BST_CallbackOnPanic(PanicHandler);


RFCOMM

© 2001 72

4 RFCOMM

This section provides an overview of RFCOMM and an introduction to the API. This chaptercontains the following sections:




� RFCOMM API Primitives on page 79


4.1 Overview

RFCOMM is a protocol that provides an emulation of serial ports over the L2CAP protocol. It isbased on the ETSI GSM specification TS 07.10 1. The concept is basically to allow a laptop orother computing device, to be plugged into a GSM phone via a COM serial port on the laptop.This allows the GSM phone to be used as a radio modem for the remote accessing of dataservices via the GSM network. This functionality is currently achievable at 9600 baud on mostGSM systems. RFCOMM effectively provides the serial cable replacement when used with theBluetooth radio air interface.

The communications capability of RFCOMM is not restricted to GSM phones. RFCOMM iscentral to many of the Bluetooth profiles and is correspondingly applicable to a range ofdevices.

RFCOMM supports two device types (illustrated in Figure 4-1 on page 73):

� Type 1 is a communication end point, such as a computer.

� Type 2 is a device that is part of a communication segment. A GSM phone acting as aradio modem is a Type 2 device.

Port Emulation Entity

RFCOMM

Application

L2CAP L2CAP

RFCOMM

Port Proxy Entity

DCE



Port Interfacee.g. VCOMM

Low LevelInterfaceData (Tx, Rx)

Data (Tx, Rx)Data (Tx, Rx)

ControlControl

Control

Type 1 Device Type 2 Device

1 Digital cellular telecommunications system (Phase 2+); Terminal Equipment to Mobile Station (TE-MS) multiplexerprotocol (GSM 07.10 version 6.3.0 Release 1997). ETSI TS 101 369 v6.3.0 (1999-03)


RFCOMM

© 2001 73

Figure 4-1: RFCOMM Overview Architecture

RFCOMM emulates RS-232 serial ports, including the transfer of the state of non-data circuits,for example Clear to Send (CTS). The implementation of RFCOMM is based on the ETSI GSMspecification. This implementation does not distinguish between Data Terminal Equipment(DTE) and Data Communication-terminating Equipment (DCE) devices, and correspondinglydoes not distinguish between Data Set Ready (DSR) and Data Terminal Ready (DTR), orbetween Ready To Send (RTS) and Clear To Send (CTS) RS-232 control signals. Essentially,this implementation creates a null modem by implication when two devices are connectedtogether.

RFCOMM emulates multiple serial ports between two devices. It supports up to 60 such openports. The port instance is identified by the Data Link Connection Identifier (DLCI). DLCIvalues 2 to 61 are used to identify the emulated ports, DLCI 0 is the RFCOMM dedicatedcontrol channel. The dedicated control channel provides link signalling between the twoRFCOMM peer entities. The link protocol has a similar format to HDLC. DLCI values 1, 62 and63 are reserved.

The reservation of the DLCI value 1 is a consequence of RFCOMM server channels. There is amapping of the server channel to the DLCI part of the address field in the TS 07.10 frame.

LSB MSB

Bit No. 3 4 5 6 7 8

TS 07.10 DLCI

RFCOMM D Server Channel

Server applications registering with an RFCOMM service are assigned a Server Channelnumber in the range 1 to 30 (0 and 31 are not allowed because the corresponding DLCIs arereserved in the ETSI GSM specification). The server channel assignment is made byRFCOMM, and therefore a higher layer entity must register with RFCOMM first, before thehigher layer entity (even a port entity) can register the application with SDP. Registration withSDP allows remote devices to locate the services.

For an RFCOMM session, the initiating device is given the direction bit D=1 (and conversely,D=0 in the other device). As a consequence, server channel 1 on the initiating device becomesDLCI 3, and server channel 1 on the other device becomes DLCI 2.

For a Type 1 device the Port Emulation Entity maps the system specific communicationinterface to the RFCOMM services. For a Type 2 device the Port Proxy Entity relays data fromRFCOMM to an external low-level interface, for example RS-232, which is linked to a DCE, forexample a modem.

In the description of the API, the primitives are grouped so that the description coversthe _REQ, _RES, _IND and _CFM for each type. RFCOMM users are only required tosend the downstream primitive types _REQ and _RES. The _IND and _CFM primitivesmust also be understood because they are received from RFCOMM.

4.2 Key Concepts

This section discusses the concepts introduced by the Bluetooth specification(www.Bluetooth.com) that are key to RFCOMM that a user of RFCOMM requires knowledge ofin order to understand and use the API.

There are two key concepts within RFCOMM that the user needs to be aware of – the Mux IDand the Local Server Channel.



RFCOMM

© 2001 74

4.2.1 Mux IDThere is logically one multiplexer associated between two Bluetooth devices. The Mux ID is theidentifier used locally between RFCOMM and the application above it. It is assigned byRFCOMM, usually as a result of a RFC_Start_Req primitive.

Each multiplexer instance supports one or more server channels.

4.2.2 Local Server ChannelThe local server channel is an association between a service and a logical ID in RFCOMM.Applications register themselves with RFCOMM, and in doing so provide a server channelidentity to RFCOMM and a protocol handle (phandle) by which events can be sent to thisservice. This server channel identity should be registered in the Service Discovery Database,allowing remote devices to locate, and connect to, the service.

The relationship between the server channel and the mux is best explained by way of theexample, illustrated in Figure 4-2 on page 74.

Mux 3Mux 2

Mux 1

Ser

ver

Cha

nnel

3

Ser

ver

Cha

nnel

4

Master

Mux 1

Ser

ver

Cha

nnel

3

Mux 2S

erve

r C

hann

el 3

Ser

ver

Cha

nnel

4

Ser

ver

Cha

nnel

4

Slave 1 Slave 2

Figure 4-2: MUX and Service Channel Relationship Example

In this example there is a master device communicating with two slaves. The master devicehas two server channels, 1 and 2, that correspond to specific services. There is a 1-to-1correspondence between a mux instance (identified by a mux_id) and a slave. Therefore,either slave can access the services that are associated with the server channels 1 and 2 onthe master, the differentiator being the mux_id, in other words, mux 1 in the example isassociated with slave 1, and mux 2 with slave 2.

Mux 3 would be associated with slave 3 in this example.

4.2.3 RFCOMM Flow ControlRFCOMM offers two mechanisms for flow control for data channels.

The first mechanism, introduced in version 1.0 of the Bluetooth specification, uses theRFC_FCON and RFC_FCOFF primitives to gate data flow to and from RFCOMM. This is themechanism described in section 6.3 of the Bluetooth Specification Part F-1.


RFCOMM

© 2001 75

The second mechanism is credit based as described in section 6.5 of the BluetoothSpecification Part F-1. The BlueStack implementation of the credit based mechanism,introduced in version 1.1 of the Bluetooth specification, is described below.

These two flow control mechanisms are mutually exclusive. You should notattempt to use them both at the same time.

Credit Based Flow Control Mechanism

Credit-based Flow Control (CFC) is provided on a per DLC basis. The request that Credit-based Flow Control is to beg used (by the Port Entity) and the associated initial credit valuesare passed between the Port Entity and RFCOMM using the RFC_PARNEG primitives.

Within this primitive is a structure DLC_PAR_T, which contains the DLC parameters. The fieldcredit_flow_ctrl is set TRUE if Credit-based Flow Control is to be used. If it is to be used,then the field initial_credits contains the initial number of credits. This initial_creditsfield is a 16-bit field, and therefore it is possible to specify a significantly large number of credits.However, we would recommend selecting a decimal value in the range 4 to 7.

Port Entity RFCOMM Remote RFCOMM Remote Port Entity

4: RFC_PARNEG_REQdlc_pars.credit_flow_control = TRUEdlc_pars.initial_credit = A

5: PN

6: RFC_PARNEG_INDdlc_pars.credit_flow_control = TRUEdlc_pars.initial_credit = B

1: RFC_PARNEG_RES

dlc_pars.credit_flow_control = TRUEdlc_pars.initial_credit = C

2: PN

3: RFC_PARNEG_CFMdlc_pars.credit_flow_control = TRUEdlc_pars.initial_credit = D

Figure 4-3: RFCOMM Credit-based Flow Control, successful negotiation

Figure 4-3 illustrates how Credit-based Flow Control is set up. The Port Entity requests the useof Credit-based Flow Control by setting in the RFC_PARNEG_REQ primitive the parameterdlc_pars.credit_flow_ctrl to TRUE. It also supplies to RFCOMM the initial credit that it willgive RFCOMM for upstream packets in the parameter dlc_pars.initial_credits. This isshown as value A. The two peer RFCOMM entities communicate, using the PN command forparameter negotiation. The remote RFCOMM entity will indicate this communication to theremote Port Entity by the use of the RFC_PARNEG_IND primitive. This primitive contains theparameter dlc_pars.credit_flow_ctrl set to TRUE, indicating a request to use Credit-basedFlow Control. The parameter dlc_pars.initial_credits, shown as value B, contains theinitial credit that the remote RFCOMM entity gives the remote Port Entity for the Port Entity’stransmitted packets.

The remote Port Entity responds to the RFC_PARNEG_IND primitive with a RFC_PARNEG_RESprimitive. If the remote Port Entity is willing to accept the use of Credit-based Flow Control,then it sets the parameter dlc_pars.credit_flow_ctrl to TRUE, in the RFC_PARNEG_RESprimitive. The value of the dlc_pars.initial_credits, shown as C, that it supplies to the remote


RFCOMM

© 2001 76

RFCOMM entity, is the initial number of credits that it gives RFCOMM for packets destined forthe remote Port Entity. The PN command is further used to communicate between the peerRFCOMM entities.

Finally, RFCOMM sends a RFC_PARNEG_CFM primitive to the Port Entity. If the negotiation touse Credit-based Flow Control is successful, then the parameter dlc_pars.credit_flow_ctrlis set TRUE. The value of dlc_pars.initial_credits, shown as D, is the number of creditsthat RFCOMM gives the Port Entity for downstream packets that the Port Entity may wish totransmit.

To summarise, the values of A to D represent the following:

A – The number of credits for data receipt by the Port Entity

B – The number of credits for data transmission by the Remote Port Entity

C – The number of credits for data receipt by the Remote Port Entity

D – The number of credits for data transmission by the Port Entity

Although the negotiation for the type of flow control is made on a particular DLC instance (asidentified by the server channel), RFCOMM does not support a mixture of flow control methodson a single multiplexer. Thus once a flow control method is agreed between two Bluetoothdevices, then all DLC channels using that multiplexer will use the same flow control method.

It should be noted that the number of credits is not negotiated. In all cases the value ofdlc_pars.initial_credits is used to pass to the entity on the other side of the RFCOMM interface,the initial number of credits that it has. Thus, if in a RFC_PARNEG_CFM, thedlc_pars.initial_credits value is set to 4, then the Port Entity can send a maximum of 4packets to RFCOMM, without further acknowledgement from RFCOMM.

Port Entity RFCOMM Remote RFCOMM Remote Port Entity

dlc_pars.credit_flow_control = TRUEdlc_pars.initial_credit = A

dlc_pars.credit_flow_control = TRUEdlc_pars.initial_credit = B

dlc_pars.credit_flow_control = FALSEdlc_pars.initial_credit = 0

dlc_pars.credit_flow_control = FALSEdlc_pars.initial_credit = 0

4: RFC_PARNEG_REQ

3: RFC_PARNEG_CFM

5: PN

2: PN

6: RFC_PARNEG_IND

1: RFC_PARNEG_RES

Figure 4-4: RFCOMM Credit-based Flow Control, unsuccessful negotiation

In Figure 4-4 we illustrate the unsuccessful case. In this example, although the Port Entity hasrequested Credit-based Flow Control, the remote Port Entity is unable to support this feature. Itindicates this by setting the parameter dlc_pars.credit_flow_ctrl to FALSE in theRFC_PARNEG_RES primitive. The value of the dlc_pars.initial_credits is now of noconsequence and is shown as 0. As previously, the PN command is used to communicatebetween the peer RFCOMM entities. Finally, the unsuccessful outcome is indicated to the Port


RFCOMM

© 2001 77

Entity by the parameter dlc_pars.credit_flow_ctrl being set to FALSE in the primitiveRFC_PARNEG_CFM.

Credits are updated using the credit field in the RFC_DATA_REQ and RFC_DATA_IND primitives.RFC_DATA_REQ sent by a Port Entity is used to define the number of credits for reception by thatPort Entity (i.e. either the local or remote side) and RFC_DATA_IND received by a Port Entity isused to define the number of credits for transmission by that Port Entity.

Although the updating of credits is a local matter between RFCOMM and the Port Entity, theoverall flow control mechanism operates across the air interface between peer RFCOMMentities. This mechanism uses the same UIH frames as the RFCOMM user data is transferredin. Thus, in the BlueStack implementation, we maintain this association between RFC_DATAprimitives and UIH frames, and the mechanism for the updating of credits uses these primitives.This can lead to situations where, for example, data is asymmetric and RFCOMM wishes toupdate the credits of the Port Entity but has no data to send it. In this case RFCOMM sends thePort Entity a RFC_DATA_IND primitive with no user data, as shown in Figure 4-5. The parametercredits conveys update to the credit value. For example, if a Port Entity was given an initialcredit of 5, and has subsequently sent 3 packets, then its credit remaining is 2. If it receives aRFC_DATA_IND with credits = 2, then it can increment its local record of the credits by 2, thus inthis example, it now has 4 remaining credits.

No user datacredits used to update local credit value

Port Entity RFCOMM

1: RFC_DATA_REQ

2: RFC_DATA_IND

Figure 4-5: Updating flow control with no user data

In the case where data is symmetric, the RFC_DATA_REQ and RFC_DATA_IND primitives are usedto both pass user data, and contain the credits parameter to update the credit value. Evenwhen the data is symmetric, it is still possible to send or receive an RFC_DATA primitive withno user data. Again, this is used purely for the updating of the credit values.

The following represents a simple algorithm for the transmit flow control in the Port Entity. Thelocal variable tx_credits is used to keep the current value as to the number of credits that thePort Entity has. The variable is updated as a result of three actions.

switch (action)

{

case RFC_PARNEG_CFM

if (dlc_pars.credit_flow_control)

tx_credits = dlc_pars.initial_credits

break

case RFC_DATA_IND

tx_credits += credits


RFCOMM

© 2001 78

break

case Data to Transmit

if (tx_credits > 0)

send data to RFCOMM in a RFC_DATA_REQ

tx_credits—

break

}

RFCOMM intelligently manages flow control mechanisms based on the pool ofmemory (pmalloc allocated) resources available. It is therefore possible thatRFCOMM will retain some credits, for example when an application issues credits to aremote entity, due to a forecast lack of local memory resource.The remaining creditswill be issued by RFCOMM when local conditions allow..


The rfcomm_config.h file contains the following configurable items.

The following parameters are associated with the flow control behaviour of RFCOMM. Thedefaults are defined in the rfcomm_config.h file however they may be overriden whenRFCOMM is initialised by the RFC_INIT_REQ primitive.

fcon_threshold fcon threshold in RFCOMM flow controlfcoff_threshold fcoff threshold in RFCOMM flow control

max_tx_credits Maximum value for transmission credits per DLC in CFCmax_rx_credits Maximum value for receiver credits per DLC in CFCnon_credit_free_pmalloc_blocks Memory blocks that may not be used for credits

If you wish to modify the behaviour of RFCOMM flow control for your particular applicationplease contact Mezoe support by e-mail: [email protected] .

The (maximum) frame size is configured per server channel connection. This is set via the APIusing the RFC_Start primitive as a multiplexer parameter, and the RFC_Parneg primitive as aDLC parameter. The recommended default value is 127 (the RFCOMM default). Larger valuescan be used, but should always be less than or equal to the RFCOMM maximum frame size of32167.



RFCOMM

© 2001 79

4.4 RFCOMM API Primitives

4.4.1 RFC_INIT

typ

e

ph

and

le

psm

_lo

cal

ove

rrid

e_fc

_def

ault

s

RFC INIT REQ ✔ ✔ ✔ ✔

RFC INIT CFM ✔ ✔ ✔

Table 4-1: RFC_INIT Primitives

Description

RFC_INIT is called to initialize RFCOMM at start up from a system point of view (rather than atstack start-up). RFC_INIT registers the psm and protocol handle to which remote requests tostart an RFCOMM session will be sent via RFC_Start_Ind events. This call will causeRFCOMM to register itself with L2CAP using the RFCOMM psm value. RFC_INIT may alsooptionally be used to set flow control parameters.

Parameters

type RFC_INIT_REQRFC_INIT_CFM

phandle Protocol handle of the initializing entity, for example Application Manager. Thisis the phandle to which RFC_START_IND will be sent by RFCOMM.

psm_local Defines the PSM used by this instance of RFCOMM. This is the value thatRFCOMM supplies to L2CAP. The default value as defined by Bluetooth SIG is0x0003. Alternatively, values in the range 0x1001 to 0xFFFF can be(dynamically) assigned.

override_fc_defaults

Boolean flag to signify that the default settings for RFCOMM flow control are tobe overriden. If set TRUE in RFC_INIT_REQ then the following additionalparameters are valid for both RFC_INIT_REQ and RFC_INIT_CFM, otherwise thedefault values will be used.

fcon_threshold fcon threshold in RFCOMM flow controlfcoff_threshold fcoff threshold in RFCOMM flow controlmax_tx_credits Maximum value for transmission credits per DLC in CFCmax_rx_credits Maximum value for receiver credits per DLC in CFCnon_credit_free_pmalloc_blocks

Memory blocks that may not be used for credits


RFCOMM

© 2001 80

4.4.2 RFC_REGISTER

typ

e

acce

pt

serv

er_c

han

ph

and

le

RFC REGISTER REQ ✔ ✔

RFC REGISTER CFM ✔ ✔ ✔ ✔

Table 4-2: RFC_REGISTER Primitives

Description

RFC_REGISTER_REQ allows a higher (port) entity to register a protocol handle (phandle) withRFCOMM. The registered phandle is used for notifying a higher entity of the arrival of aRFC_ESTABLISH_IND message on the given server channel. RFCOMM should respond with aRFC_REGISTER_CFM event, and provides the registering entity with details of the server channelthat has been allocated to that service.

Parameters

type RFC_REGISTER_REQRFC_REGISTER_CFM

accept Accept flag (TRUE | FALSE)

server_chan Server channel id for the specific higher entity (application).

phandle Protocol handle of higher entity (application).


RFCOMM

© 2001 81

4.4.3 RFC_START

typ

e

acce

pt

bd

_ad

dr

mu

x_id

resp

on

d_p

han

dle

ph

and

le

resu

lt_c

od

e

psm

_rem

ote

sys_

par

s

RFC START REQ ✔ ✔ ✔ ✔ ✔

RFC START RES ✔ ✔ ✔ ✔ ✔

RFC START IND ✔ ✔ ✔ ✔ ✔

RFC START CFM ✔ ✔ ✔ ✔ ✔ ✔

Table 4-3: RFC_START Primitives

Description

RFC_START_REQ requests the initiation of a logical connection between the local device and aremote device specified by its Bluetooth device address with the suggested system parameters.These system parameters are the maximum frame size and the data rate.

The request includes the creation of a multiplexer channel. If the connection is successfullyestablished, the local RFCOMM responds with a RFC_START_CFM event even if the parametersare not agreed. In this case the RFC_START_CFM contains the mux_id. The phandle has alreadybeen supplied in the RFC_INIT_REQ.

RFC_START_IND is received when a remote RFCOMM wishes to set-up a mux. This primitivewill be received twice when a remote device is initiating mux set-up. The first occurrenceprovides the local device the opportunity of refusing the connection. In this case the local deviceresponds with the RFC_START_RES primitive setting the system parameters to 0 and the acceptflag is set to FALSE.

The second instance of an RFC_START_IND event during a connection start-up sequence is forconfiguration purposes. In this case, the accept flag set to FALSE is equivalent to suggesting adifferent set of parameters, otherwise the accept flag is set TRUE and the system parametersare returned as received to indicate agreement. (Note that the max_frame_size returned maybe less than that suggested but not greater).

Parameters

type RFC_START_REQRFC_START_RESRFC_START_INDRFC_START_CFM

accept accept flag (TRUE | FALSE)

bd_addr Bluetooth Device Address.

mux_id Multiplexer identifier.

respond_phandle


RFCOMM

© 2001 82

Protocol handle of higher entity (application). Reply overrides default if set.


result_code The result code can take the values:SUCCESS

RFC_CONNECTION_PENDING L2CAP reflected code.RFC_CONNECTION_REJ_PSM L2CAP reflected code.RFC_CONNECTION_REJ_SECURITY L2CAP reflected code.RFC_CONNECTION_REJ_RESOURCES L2CAP reflected code.RFC_CONNECTION_REJ_NOT_READY L2CAP reflected code.RFC_CONNECTION_FAILED L2CAP reflected code.RFC_CONNECTION_TIMEOUT L2CAP reflected code.NORMAL_DISCONNECT Remote device initiated.ABNORMAL_DISCONNECT Link loss.RFC_CONFIG_UNACCEPTABLE L2CAP reflected code.RFC_CONFIG_REJECTED L2CAP reflected code.RFC_CONFIG_INVALID_CID L2CAP reflected code.RFC_CONFIG_UNKNOWN L2CAP reflected code.RFC_CONFIG_REJECTED_LOCALLY L2CAP reflected code.RFC_CONFIG_TIMEOUT L2CAP reflected code.REMOTE_REFUSAL Remote device refusal.RACE_CONDITION_DETECTED Remote device also initiating.INSUFFICIENT_RESOURCES Insufficient pool memory.CANNOT_CHANGE_FLOW_CONTROL_MECHANISM Cannot change in a session.DLC_ALREADY_EXISTS Only one DLC per remote service allowed.GENERIC_REFUSAL Unknown L2CAP error.

psm_remote PSM of the remote RFCOMM entity.

sys_pars The system parameters consist of two values which are defined in a structure:

typedef struct{ port_speed_t port_speed; /* port speed indicator */ uint16_t max_frame_size; /* Maximum frame size (bytes) */} SYS_PAR_T;

The port_speed takes the form PORT_SPEED_xxxx, where xxxx is the port speed in bits persecond. The following values are defined: 2400, 4800, 7200, 9600, 19200, 38400, 57600,115200, and 230400.

The max_frame_size is implementation dependent, but a value of 250 bytes or less isrecommended for efficient operation across BCSP. The RFCOMM default is 127 bytes.

Notes

The PSM of the remote RFCOMM entity can be found using service discovery.

If respond_phandle is set to INVALID_PHANDLE then the RFC_START_IND / RFC_START_CFMprimitives will be returned to the phandle specified in RFC_INIT_REQ. Otherwise theRFC_START_IND / RFC_START_CFM primitives will be returned to respond_ phandle.


RFCOMM

© 2001 83

4.4.4 RFC_STARTCMP

typ

e

mu

x_id

ph

and

le

resu

lt_c

od

e

sys_

par

s

RFC STARTCMP IND ✔ ✔ ✔ ✔ ✔

Table 4-4: RFC_STARTCMP Primitive

Description

RFC_STARTCMP_IND is an indication to the local port entity that the multiplexer sessionconfiguration has now been completed and that server channel establishment may commenceon the multiplexer.

Parameters

type RFC_STARTCMP_IND

mux_id The multiplexer identifier.

phandle Protocol handle of the higher entity (application).


RFC_CONNECTION_PENDING L2CAP reflected code.RFC_CONNECTION_REJ_PSM L2CAP reflected code.RFC_CONNECTION_REJ_SECURITY L2CAP reflected code.RFC_CONNECTION_REJ_RESOURCES L2CAP reflected code.RFC_CONNECTION_REJ_NOT_READY L2CAP reflected code.RFC_CONNECTION_FAILED L2CAP reflected code.RFC_CONNECTION_TIMEOUT L2CAP reflected code.NORMAL_DISCONNECT Remote device initiated.ABNORMAL_DISCONNECT Link loss.RFC_CONFIG_UNACCEPTABLE L2CAP reflected code.RFC_CONFIG_REJECTED L2CAP reflected code.RFC_CONFIG_INVALID_CID L2CAP reflected code.RFC_CONFIG_UNKNOWN L2CAP reflected code.RFC_CONFIG_REJECTED_LOCALLY L2CAP reflected code.RFC_CONFIG_TIMEOUT L2CAP reflected code.REMOTE_REFUSAL Remote device refusal.RACE_CONDITION_DETECTED Remote device also initiating.INSUFFICIENT_RESOURCES Insufficient pool memory.CANNOT_CHANGE_FLOW_CONTROL_MECHANISM Cannot change in a session.DLC_ALREADY_EXISTS Only one DLC per remote service allowed.GENERIC_REFUSAL Unknown L2CAP error.


RFCOMM

© 2001 84

sys_pars The system parameters consist of two values which are defined in a structure:

typedef struct{ port_speed_t port_speed; /* port speed indicator */ uint16_t max_frame_size; /* Maximum frame size (bytes) */} SYS_PAR_T;

The port_speed takes the form PORT_SPEED_xxxx, where xxxx is the port speed in bits persecond. The following values are defined: 2400, 4800, 7200, 9600, 19200, 38400, 57600,115200, and 230400.

The max_frame_size is implementation dependent, but a value of 250 bytes or less isrecommended for efficient operation across BCSP. The RFCOMM default is 127 bytes.


RFCOMM

© 2001 85

4.4.5 RFC_CLOSE

typ

e

mu

x_id

ph

and

le

reas

on

_co

de

RFC CLOSE REQ ✔ ✔

RFC CLOSE IND ✔ ✔ ✔ ✔

Table 4-5: RFC_CLOSE Primitives

Description

RFC_CLOSE_REQ closes the RFCOMM link for the specified multiplexer to its remote Bluetoothdevice. This command represents a termination of the multiplexer session, and as aconsequence all associated server channels. This request is not confirmed.

The user of the port entity(ies) does not need to ensure that all server channels have beenreleased before issuing the RFC_CLOSE_REQ. If there are still server channels open, RFCOMMreturns an RFC_RELEASE_IND with reason code set toLOCAL_ENTITY_TERMINATED_CONNECTION (see page 90).

RFC_Close_Ind is a non-negotiable indication that the RFCOMM link has closed.

Parameters

type RFC_CLOSE_REQRFC_CLOSE_IND

phandle Protocol handle.

mux_id The identifier of the specific multiplexer session being used.

reason_code The reason for the close indication:

NORMAL_DISCONNECTABNORMAL_DISCONNECT

Notes

A normal disconnect is one initiated either by the local or remote RFCOMM, an abnormaldisconnect indicates a loss of the ACL baseband link.


RFCOMM

© 2001 86

4.4.6 RFC_PARNEG

typ

e

dlc

_par

s

loc_

serv

er_c

han

rem

_ser

ver_

chan

serv

er_c

han

mu

x_id

ph

and

le

RFC PARNEG REQ ✔ ✔ ✔ ✔ ✔

RFC PARNEG RES ✔ ✔ ✔ ✔

RFC PARNEG IND ✔ ✔ ✔ ✔ ✔

RFC PARNEG CFM ✔ ✔ ✔ ✔ ✔

Table 4-6: RFC_PARNEG Primitives

Description

RFC_PARNEG is used to indicate to the remote port entity that the local port entity wants tonegotiate and set parameters for the server channel, as given in dlc_pars. If a response isreceived from the remote port entity, a RFC_PARNEG_CFM event is sent even if the parametersare not agreed.

Parameters

type RFC_PARNEG_REQRFC_PARNEG_RESRFC_PARNEG_INDRFC_PARNEG_CFM

dlc_pars See the structure defined below.

loc_server_chan

Local server channel of the higher entity (application).

rem_server_chan

Server channel for the remote application.

server_chan Relevant server channel.

mux_id Identifier of the multiplexer session.



RFC_CONNECTION_PENDING L2CAP reflected code.RFC_CONNECTION_REJ_PSM L2CAP reflected code.RFC_CONNECTION_REJ_SECURITY L2CAP reflected code.RFC_CONNECTION_REJ_RESOURCES L2CAP reflected code.RFC_CONNECTION_REJ_NOT_READY L2CAP reflected code.RFC_CONNECTION_FAILED L2CAP reflected code.RFC_CONNECTION_TIMEOUT L2CAP reflected code.NORMAL_DISCONNECT Remote device initiated.ABNORMAL_DISCONNECT Link loss.


RFCOMM

© 2001 87

RFC_CONFIG_UNACCEPTABLE L2CAP reflected code.RFC_CONFIG_REJECTED L2CAP reflected code.RFC_CONFIG_INVALID_CID L2CAP reflected code.RFC_CONFIG_UNKNOWN L2CAP reflected code.RFC_CONFIG_REJECTED_LOCALLY L2CAP reflected code.RFC_CONFIG_TIMEOUT L2CAP reflected code.REMOTE_REFUSAL Remote device refusal.RACE_CONDITION_DETECTED Remote device also initiating.INSUFFICIENT_RESOURCES Insufficient pool memory.CANNOT_CHANGE_FLOW_CONTROL_MECHANISM Cannot change in a session.DLC_ALREADY_EXISTS Only one DLC per remote service allowed.GENERIC_REFUSAL Unknown L2CAP error.

The dlc_pars are defined in the structure DLC_PAR_T as follows:

typedef struct{ uint16_t max_frame_size; /* Maximum frame size for DLC */ uint8_t credit_flow_ctrl; /* true if requesting credit_based */ uint16_t initial_credits; /* initial credits */

} DLC_PAR_T;

max_frame_size The maximum frame size in bytes that the DLC can support. The use of theRFCOMM default value of 127 is recommended wherever possible.

credit_flow_control TRUE if requesting credit based operation, FALSE otherwise.

initial_credits For RFC_PARNEG_REQ or RFC_PARNEG_RES initial_credits normally set inthe range 4 to 7 to request the initial Port Entity receiver credit value for thesession. For RFC_PARNEG_IND or RFC_PARNEG_CFM initial_creditscontains the initial Port Entity transmitter credit value for the session.

Notes

RFC_PARNEG_REQ must be sent prior to RFC_ESTABLISH_REQ when setting up a server channel.

The rem_server_chan parameter is not required if this primitive is being used once a DLC hasbeen established - RFCOMM can identify the remote DLC from the local server channel.

The remote server channel can be found using SDP.

In a response, the application must fill in the dlc_pars with those from the _ind, replacing anyunacceptable parameters with acceptable values. The possible changes are; reduced framesize, and rejection of credit-based flow control.


RFCOMM

© 2001 88

4.4.7 RFC_ESTABLISH

typ

e

acce

pt

loc_

serv

er_c

han

serv

er_c

han

mu

x_id

ph

and

le

resu

lt_c

od

e

rem

_ser

ver_

chan

RFC ESTABLISH REQ ✔ ✔ ✔ ✔

RFC ESTABLISH RES ✔ ✔ ✔ ✔

RFC ESTABLISH IND ✔ ✔ ✔ ✔

RFC ESTABLISH CFM ✔ ✔ ✔ ✔ ✔

Table 4-7: RFC_ESTABLISH Primitives

Description

RFC_ESTABLISH_REQ requests the establishment of a new server on the multiplexer. If theserver channel is established, the response is an RFC_ESTABLISH_CFM event.

Parameters

type RFC_ESTABLISH_REQRFC_ESTABLISH_RESRFC_ESTABLISH_INDRFC_ESTABLISH_CFM


loc_server_chan

The local server channel for the service.

server_chan The server channel for the service.




RFC_CONNECTION_PENDING L2CAP reflected code.RFC_CONNECTION_REJ_PSM L2CAP reflected code.RFC_CONNECTION_REJ_SECURITY L2CAP reflected code.RFC_CONNECTION_REJ_RESOURCES L2CAP reflected code.RFC_CONNECTION_REJ_NOT_READY L2CAP reflected code.RFC_CONNECTION_FAILED L2CAP reflected code.RFC_CONNECTION_TIMEOUT L2CAP reflected code.NORMAL_DISCONNECT Remote device initiated.ABNORMAL_DISCONNECT Link loss.RFC_CONFIG_UNACCEPTABLE L2CAP reflected code.RFC_CONFIG_REJECTED L2CAP reflected code.RFC_CONFIG_INVALID_CID L2CAP reflected code.


RFCOMM

© 2001 89

RFC_CONFIG_UNKNOWN L2CAP reflected code.RFC_CONFIG_REJECTED_LOCALLY L2CAP reflected code.RFC_CONFIG_TIMEOUT L2CAP reflected code.REMOTE_REFUSAL Remote device refusal.RACE_CONDITION_DETECTED Remote device also initiating.INSUFFICIENT_RESOURCES Insufficient pool memory.CANNOT_CHANGE_FLOW_CONTROL_MECHANISM Cannot change in a session.DLC_ALREADY_EXISTS Only one DLC per remote service allowed.GENERIC_REFUSAL Unknown L2CAP error.

rem_server_chanServer channel for the remote application.

Notes

The remote server channel may be obtained via SDP.


RFCOMM

© 2001 90

4.4.8 RFC_RELEASE

typ

e

reas

on

_co

de

serv

er_c

han

mu

x_id

ph

and

le

RFC RELEASE REQ ✔ ✔ ✔

RFC RELEASE IND ✔ ✔ ✔ ✔ ✔

Table 4-8: RFC_RELEASE Primitive

Description

RFC_RELEASE_REQ allows a higher entity (application) to close down the data link connectionreferenced by the server channel within the RFCOMM multiplexer to the remote Bluetoothdevice indexed by its mux_id. This affects only the RFCOMM link referenced by the serverchannel, not the multiplexer session.

Parameters

type RFC_RELEASE_REQRFC_RELEASE_IND

server_chan Local server channel of the higher entity (application).



reason_code The reason for the release indication:NORMAL_DISCONNECTABNORMAL_DISCONNECTLOCAL_ENTITY_TERMINATED_CONNECTION


RFCOMM

© 2001 91

4.4.9 RFC_CONTROL

typ

e

con

tro

l_p

ars se

rver

_ch

an

mu

x_id

ph

and

le

RFC CONTROL REQ ✔ ✔ ✔ ✔

RFC CONTROL IND ✔ ✔ ✔ ✔ ✔

Table 4-9: RFC_CONTROL Primitives

Description

RFC_CONTROL_REQ is used by the higher port entity to convey control information to the remoteport. The control information is set in control_pars.

The RFC_CONTROL_IND event indicates to the port entity that the remote port emulation entitywishes to use the control parameters set in control_pars.

Parameters

type RFC_CONTROL_REQRFC_CONTROL_IND

control_pars These are a number of parameters defined in a structure (see below).

server_chanThe local server channel of the higher entity (application).



The structure for control_pars has the form:

typedef struct{ uint8_t modem_signal; /* modem signal */ uint8_t break_signal; /* break signal time (4 bits) */} CONTROL_PAR_T;

The encoding of modem_signal is as follows:

Bit 8 7 6 5 4 3 2 1

DV IC 0 0 RTR RTC 0 0


RFCOMM

© 2001 92

The values of DV, IC, RTR and RTC are encoding as shown in Table 4-10 and Table 4-11 onpage 92 (from the 0710 specification):

Control Signal Byte DTE receiving DCE receiving

bit number, name signal V.24 circuit signal V.24 circuit

3, RTC DSR 107 DTR 108/2

4, RTR CTS 106 RFR 1 133

7, IC RI 125 ignored -

8, DV DCD 109 ignored -

Table 4-10: Mapping From the Control Signal Octet by a Receiving Entity

Control Signal Byte DTE sending DCE sending

bit number, name signal V.24 circuit signal V.24 circuit

3, RTC DTR 108/2 DSR 107

4, RTR RFR 133 CTS 133

7, IC always 0- - RI 125

8, DV always 1- - DCD 109

Table 4-11: Mapping To the Control Signal Octet by a Sending Entity

The break_signal is encoded as follows:

Bit 8 7 6 5 4 3 2 1

L4 L3 L2 L1 B3 B2 B1 EA

Where:

B1 1 Break signal encoded.

B1 0 No break signal encoded.

L1 - L4 Duration of break signal in 200mS increments.

EA , B2 – B3 Not used.

1 Circuit 133, RFR (Ready for Receiving) is commonly assigned to the connector pin that is alternatively used for circuit105, RTS (Ready to Send). It is sometime referred to by that name.


RFCOMM

© 2001 93

4.4.10 RFC_PORTNEG

typ

e

loc_

serv

er_c

han

rem

_ser

ver_

chan

serv

er_c

han

mu

x_id

ph

and

le

po

rt_p

ars

req

ues

t

RFC PORTNEG REQ ✔ ✔ ✔ ✔ ✔ ✔

RFC PORTNEG RES ✔ ✔ ✔ ✔

RFC PORTNEG IND ✔ ✔ ✔ ✔ ✔ ✔

RFC PORTNEG CFM ✔ ✔ ✔ ✔ ✔

Table 4-12: RFC_PORTNEG Primitives

Description

RFC_PORTNEG_REQ is used to indicate to the remote port entity that the local port entity hasrequested it to set port parameters for the server channel as given in port_pars. port_parsconsist of the port data rate, number of data bits, number of stop bits, parity and parity type. If aresponse is received from the remote port entity then a RFC_PORTNEG_CFM event is sent even ifthe parameters are not agreed.

Parameters

type RFC_PORTNEG_REQRFC_PORTNEG_RESRFC_PORTNEG_INDRFC_PORTNEG_CFM

loc_server_chan

Local server channel of the higher entity (application).

rem_server_chan

Server channel for the remote application.

server_chan Relevant server channel.



request Boolean defined as:TRUE - Request that the remote device sends its current port parametersettings for mux_id.FALSE - Negotiates the port parameters. The remote device must confirm thesettings or propose new ones.

port_pars Port parameters as defined in the PORT_PAR_T structure:

typedef struct{ port_speed_t port_speed; /* port speed indicator */ uint8_t data_bits; /* 5, 6, 7 or 8 */


RFCOMM

© 2001 94

uint8_t stop_bits; /* 0 or 1 (1 or 1.5 stop bits) */ uint8_t parity; /* off or on */ uint8_t parity_type; /* odd, even, mark or space */ uint8_t flow_ctrl_mask; /* 6 bits – use FLC_ #defines */ uint8_t xon; /* xon character (default DC1) */ uint8_t xoff; /* xoff character (default DC3) */ uint16_t parameter_mask; /* PM1 – PM18 as per 07.10 */} PORT_PAR_T;

The port parameters are encoded as follows:

port_speed Takes the form PORT_SPEED_xxxx, where xxxx is the port speed in bits persecond. The following values are defined: 2400, 4800, 7200, 9600, 19200,38400, 57600, 115200, and 230400.

data_bits Number of data bits encoded as an unsigned integer. Valid values are 5, 6, 7and 8.

stop_bits Encoded as: 0 = 1 stop bit, 1 = 1.5 stop bits.

parity PARITY_OFF or PARITY_ON

parity_type Encoded as:

0 odd parity1 even parity2 mark parity3 space parity

flow_ctrl_mask

Encoded as:

Bit 1 XON / XOFF, input

Bit 2 XON / XOFF, output

Bit 3 RTR input

Bit 4 RTR output

Bit 5 RTC input

Bit 6 RTC output

xon XON character, default DC1

xoff XOFF character, default DC3

parameter_mask

The parameter mask encoding is defined in the ETSI GSM specification asfollows:

PM1-PM18: Parameter mask

parameter_mask is used to indicate which parameters in the Remote PortNegotiation command are negotiated. For a command, parameter_mask isinterpreted as follows:

0 no change

1 change

For a response the following values apply:

0 not accepted proposal

2 accepted proposal - the new values are used

The bit mask is shown as:


RFCOMM

© 2001 95

Bit1 bit rate

Bit2 data bits

Bit3 stop bits

Bit4 Parity

Bit5 parity type

Bit6 XON character

Bit7 XOFF character

Bit8 Reserved

Bit 9 XON / XOFF, input

Bit 10 XON / XOFF, output

Bit 11 RTR input

Bit 12 RTR output

Bit 13 RTC input

Bit 14 RTC output

Bit 15 Reserved, set 0 by sender

Bit 16 Reserved, set 0 by sender

Notes

The rem_server_chan parameter is not required if this primitive is being used once a DLC hasbeen established - RFCOMM can identify the remote DLC from the local server channel.

The remote server channel can be found using SDP.


RFCOMM

© 2001 96

4.4.11 RFC_FCON

typ

e

mu

x_id

ph

and

le

RFC FCON REQ ✔ ✔

RFC FCON IND ✔ ✔ ✔

RFC FCON CFM ✔ ✔ ✔

Table 4-13: RFC_FCON Primitives

Description

RFC_FCON_REQ is used to control upstream aggregate flow. The port entity may use this toindicate to a remote entity that it is able to receive data.

RFC_FCON_CFM is returned in response to RFC_FCON_REQ.

RFC_FCON_IND is an indication to the local port entity that the remote entity does not wish toreceive data on this multiplexer. The port entity must not send further downstream data on themultiplexer after receiving this primitive.

Parameters

type RFC_FCON_REQRFC_FCON_INDRFC_FCON_CFM



Notes

A new multiplexer will start in the FCON state – i.e. it will be able to receive and send data.


RFCOMM

© 2001 97

4.4.12 RFC_FCOFF

typ

e

mu

x_id

ph

and

le

RFC FCOFF REQ ✔ ✔

RFC FCOFF IND ✔ ✔ ✔

RFC FCOFF CFM ✔ ✔ ✔

Table 4-14: RFC_FCOFF Primitives

Description

RFC_FCOFF_REQ is used to control upstream aggregate flow. It indicates to a remote entity thatthe local port entity is not able to receive new data on the mux. The opposite entity is then notallowed to transmit frames except on the control channel.

RFC_FCOFF_CFM is returned in response to RFC_FCOFF_REQ.

RFC_FCON_IND is an indication to the local port entity that the remote entity is now able toreceive data on this multiplexer. The port entity may now send further downstream data on themultiplexer after receiving this primitive.

Parameters

type RFC_FCOFF_REQRFC_FCOFF_INDRFC_FCOFF_CFM



Notes

A new multiplexer will start in the FCON state – i.e. it will be able to receive and send data.


RFCOMM

© 2001 98

4.4.13 RFC_DATA

typ

e

*pay

load

pay

load

_len

gth

serv

er_c

han

cred

its

mu

x_id

ph

and

le

*pre

leas

e

RFC DATA REQ ✔ ✔ ✔ ✔ ✔ ✔

RFC DATA IND ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 4-15: RFC_DATA Primitives

Description

RFC_DATA_REQ is used to request RFCOMM to transmit the data given in the payload to theremote address along the chosen server channel. The payload is transmitted in the form of UIHframes. This primitive may be used in conjunction with the RFC_DATAWRITE primitives – seepage 99.

RFC_DATA_IND indicates receipt of data on a server channel.

Parameters

type RFC_DATA_REQRFC_DATA_IND

*payload Pointer to the data buffer containing the payload.

payload_length Length (in bytes) of the data in the data buffer (payload length).


credits The credit value for credit based flow control.



*prelease The prelease field points to the first byte of the L2CAP packet itself.

Notes

With RFC DATA IND, to minimise copy operations within RFCOMM, *payload points to the firstbyte of payload data within the L2CAP packet supplied. The *prelease field points to the firstbyte of the L2CAP packet itself.

When the payload has been processed, the recipient must release the data pointed to by the*prelease pointer. (This is not strictly necessary when used with the supplied pmallocsubsystem, as pfree can handle pointers within an allocated block).


RFCOMM

© 2001 99

4.4.14 RFC_DATAWRITE

typ

e

*pay

load

pay

load

_len

gth

serv

er_c

han

cred

its

mu

x_id

ph

and

le

RFC DATAWRITE REQ ✔ ✔ ✔ ✔ ✔ ✔

RFC DATAWRITE CFM ✔ ✔ ✔ ✔

Table 4-16: RFC_DATAWRITE Primitives

Description

RFC_DATAWRITE_REQ may be used in conjunction with RFC_DATA_REQ (see page 98) to transmitdata.

If this transmission method is used, the port entity must wait for RFC_DATAWRITE_CFM beforesending the next frame. This might be used, for example, when transmitting a block of datawhere acknowledgement is required that the last frame of the block has been sent.

RFC_DATA_REQ is used for 1..N-1 frames of the block and RFC_DATAWRITE_REQ is used on thefinal Nth frame.

Parameters

type RFC_DATAWRITE_REQRFC_DATAWRITE_CFM

*payload Pointer to the data buffer containing the payload.

payload_length

Length (in bytes) of the data in the data buffer (payload length).


credits The credit value for credit based flow control.




RFCOMM

© 2001 100

4.4.15 RFC_LINESTATUS

typ

e

line_

stat

us

serv

er_c

han

mu

x_id

ph

and

le

erro

r_fl

ag

RFC LINESTATUS REQ ✔ ✔ ✔ ✔ ✔

RFC LINESTATUS IND ✔ ✔ ✔ ✔ ✔ ✔

Table 4-17: RFC_LINESTATUS Primitives

Description

RFC_LINESTATUS_REQ is used by the higher port entity to send the line status to the remote portentity.

Parameters

type RFC_LINESTATUS_REQRFC_LINESTATUS_IND

line_status Refer to the encoding table below.

server_chanLocal server channel of the higher entity (application).



error_flag Error is used to aid diagnosis of line problems and can be:RLS_ERROR_FLAG_OFFRLS_ERROR_FLAG_ON

The line status parameter is encoded as follows:

Bit 8 7 6 5 4 3 2 1

0 0 0 0 L4 L3 L2 L1

Where:

L1 0 indicates no error

L1 1 indicates an error defined by bits L2 to L4.

L4-L2 specific errors:

001 Overrun ErrorReceived character overwrote an unread character

010 Parity ErrorReceived character’s parity was incorrect

100 Framing Error character did not terminate with a stop bit

Notes

This primitive requests the sending of a local status to the remote end. Therefore, it differsslightly from many other Bluetooth primitives in that it is not a ‘read’ request. In other words,there is no local response expected.

It is recommended that this command be sent only on change of line status.


RFCOMM

© 2001 101

4.4.16 RFC_TEST

typ

e

mu

x_id

ph

and

le

*tes

t_d

ata

test

_dat

a_le

ng

th

RFC TEST REQ ✔ ✔ ✔ ✔

RFC TEST CFM ✔ ✔ ✔ ✔ ✔

Table 4-18: RFC_TEST Primitives

Description

RFC_TEST_REQ requests a test of the communication link. The test data is sent to the remoteRFCOMM which automatically loops it back. If the data arrives back, a RFC_TEST_CFM event issent to the originating port entity.

Parameters

type RFC_TEST_REQRFC_TEST_CFM



*test_data Pointer to the memory containing the test data.

test_data_length

Length of the test data in the memory pointed at by *test data.


RFCOMM

© 2001 102

4.4.17 RFC_NSC

typ

e

mu

x_id

ph

and

le

com

man

d_c

od

e

cmd

_res

RFC NSC IND ✔ ✔ ✔ ✔ ✔

Table 4-19: RFC_NSC Primitive

Description

This primitive provides an indication to the higher layer entity that the previous RFCOMMcommand sent to the remote device was not understood.

Parameters

type RFC_NSC_IND



command_codeThe command code is the RFCOMM protocol code:PN 0x80 /* Parameter Negotiation */

TEST 0x20 /* Test */

FCON 0xA0 /* FCon */

FCOFF 0x60 /* FCoff */

MSC 0xE0 /* Modem Status Command */

RPN 0x90 /* Port Negotiation */

RLS 0x50 /* Line Status */

Any other value is not supported by RFCOMM.

cmd_res Command or Response. The value of the command response bit in theRFCOMM frame. This is encoded as follows:

command / response Direction cmd_res valuecommand Initiator � Responder 1

Responser � Initiator 0response Initiator � Responder 0

Responder � Initiator 1


RFCOMM

© 2001 103


This section provides a number of usage scenarios and shows the expected typical primitiveexchanges that will be seen at the RFCOMM API.

In all of the downstream examples two methods are shown:

1. using the native primitives, and

2. using the interface library functions

4.5.1 Starting and Configuring a Multiplexer Session – As an InitiatorThis section describes how to start a multiplexer session with a remote device as identified byits bd_addr. The bd_addr is known from a previous encounter or from inquiry.

Port Entity RFCOMM

RFC_Start_Req

RFC_Start_Cfm

Figure 4-6: Starting a Multiplexer Session – As an Initiator

Start the session:

Method 1: Using the native primitives

msg_ptr = (RFC_START_REQ_T *)pmalloc(sizeof(RFC_START_REQ_T))

The members of the structure are then set up:

msg_ptr->type = RFC_START_REQmsg_ptr->bd_addr.lap = value_of_lapmsg_ptr->bd_addr.nap = value_of_napmsg_ptr->bd_addr.uap = value_of_uapmsg_ptr-> psm_remote = RFCOMM_PSM /* assume default */msg_ptr-> respond_phandle = APPL1_QUEUE;msg_ptr->sys_pars.port_speed = PORT_SPEED_UNUSEDmsg_ptr->sys_pars.max_frame_size = RFCOMM_MAX_FRAME_SIZE

The port entity now sends the primitive as an internal message to RFCOMM via the scheduler.

put_message(rfcomm_ifacequeue, RFCOMM_PRIM, msg_ptr);

Method 2: Using the library functions

rfc_start_req(p_bd_addr, RFCOMM_PSM, p_sys_pars, APPL1_QUEUE);


RFCOMM

© 2001 104

Where p_bd_addr is a pointer to the memory containing the bluetooth addressstructure, and p_sys_pars is a pointer to the memory containing the system parametersstructure.

Once the primitive has been sent, the port entity returns control to the scheduler and waits forthe next event.

start_cfm_handler(RFC_START_CFM_T* msg_ptr){

deal with msg_ptr-> accept, if requiredextract msg_ptr-> mux_id, and store for future reference as this_mux_iddeal with msg_ptr-> refusal_code; if requireddeal with msg_ptr-> sys_pars, if required

Finally free the memory block occupied by the RFC_START_CFM primitive.

pfree(msg_ptr) return}


RFCOMM

© 2001 105

4.5.2 Starting and Configuring a Multiplexer Session – As a RecipientThis example differs from the previous example because it shows the primitive exchange for therecipient.

Port Entity RFCOMM

RFC_Start_Ind

RFC_Start_Res

RFC_StartCmp_Ind

RFC_Start_Ind

Figure 4-7: Starting a Multiplexer Session – As a Recipient

Receive an indication that a remote device wishes to setup an RFCOMM mux:

First_start_ind_handler(RFC_START_IND_T* msg_ptr){

extract msg_ptr-> bd_addr and storeextract msg_ptr-> mux_id and store as this_mux_idmsg_ptr-> sys_pars can be ignored.

Assuming that we wish to accept the connection we respond with a RFC_START_RES with theaccept parameter set to TRUE.


omsg_ptr = (RFC_START_RES_T *)pmalloc(sizeof(RFC_START_RES_T))


omsg_ptr->type = RFC_START_RESomsg_ptr->mux_id = this_mux_idomsg_ptr->accept = TRUEomsg_ptr-> respond_phandle = APPL1_QUEUE

The port entity now sends the message to RFCOMM via the scheduler.

put_message(rfcomm_ifacequeue, RFCOMM_PRIM, omsg_ptr);


rfc_start_res(this_mux_id, TRUE, p_sys_pars, APPL1_QUEUE);


RFCOMM

© 2001 106

Where p_sys_pars is a pointer to the memory containing the system parameters thathave just been received in the RFC_START_IND primitive.

For both methods we must now free the memory block occupied by theRFC_START_REQ_IND primitive.


Once the message has been sent and the memory associated with the received primitive hasbeen freed, the port entity returns control to the scheduler and waits for the next event.

Second_start_ind_handler(RFC_START_IND_T* msg_ptr){

extract msg_ptr-> bd_addr and storeextract msg_ptr-> mux_id and store as this_mux_iddeal with msg_ptr-> sys_pars, let us assume that this is stored locally as this_sys_pars

Assuming that the sys_pars are acceptable (or we can modify the relevant parameters) then werespond with a RFC_START_RES.


omsg_ptr = (RFC_START_RES_T *)pmalloc(sizeof(RFC_START_RES_T))


omsg_ptr->type = RFC_START_RESomsg_ptr->mux_id = this_mux_idomsg_ptr->accept = TRUEomsg_ptr-> respond_phandle = APPL1_QUEUEomsg_ptr->sys_pars = this_sys_pars




rfc_start_res(this_mux_id, TRUE, p_this_sys_pars, APPL1_QUEUE);

Where p_this_sys_pars is a pointer to the memory containing the system parametersthat have just been received in the RFC_START_IND primitive.

For both methods we must now free the memory block occupied by theRFC_START_REQ_IND primitive.



RFCOMM

© 2001 107

Once the message has been sent and the memory associated with the received primitive hasbeen freed, the port entity returns control to the scheduler and waits for the next event.

The next event expected is the primitive RFC_STARTCMP_IND, which indicates that themultiplexer session configuration has now been completed.

startcmp_ind_handler(RFC_STARTCMP_IND_T* msg_ptr){

deal with msg_ptr-> mux_id, if required

Finally free the memory block occupied by the RFC_STARTCMP_IND primitive.


4.5.3 Opening a Server Channel and Negotiating ParametersThis section describes how to set up a server channel and negotiate parameters.

Port Entity RFCOMM

RFC_ParNeg_Req

RFC_ParNeg_Cfm

RFC_Establish_Req

RFC_Establish_Cfm

Figure 4-8: Opening a Server Channel and Negotiating Parameters

Negotiate parameters and set up a server channel with a remote server channel that has beenfound using SDP on local server channel local_server_chan on the multiplexer this_mux_id,which has been previously obtained from the RFC_START_CFM (or _IND):


msg_ptr = (RFC_PARNEG_REQ_T *)pmalloc(sizeof(RFC_PARNEG_REQ_T))

The members of the structure are then set up.

msg_ptr->type = RFC_PARNEG_REQmsg_ptr->mux_id = this_mux_idmsg_ptr-> loc_server_chan = local_server_chan /* assigned at registration */msg_ptr->rem_server_chan = remote_server_chan; /* found via SDP */msg_ptr->dlc_pars.max_frame_size = 127 /* RFCOMM default */msg_ptr->dlc_pars.credit_flow_control = TRUE; /* credit flow control requested */msg_ptr->dlc_pars.initial_credits = initial_credit_value;



RFCOMM

© 2001 108



rfc_parneg_req(this_mux_id, local_server_chan, remote_server_chan, p_dlc_pars);

Where p_dlc_pars is a pointer to the memory containing the dlc parameters structure,and local_server_chan is the local server channel assigned when the port entityregisters with RFCOMM.

Once sent, the port entity returns control to the scheduler and waits for the next event.

parneg_cfm_handler(RFC_PARNEG_CFM_T* msg_ptr){

Inspect parameters to see if the final values are acceptable.Assuming that they are acceptable, then send establish request.


omsg_ptr = (RFC_ESTABLISH_REQ_T *)pmalloc(sizeof(RFC_ESTABLISH_REQ_T))


omsg_ptr->type = RFC_ESTABLISH_REQomsg_ptr->mux_id = this_mux_idomsg_ptr-> loc_server_chan = local_server_chan /* assigned at registration */omsg_ptr->rem_server_chan = remote_server_chan; /* found via SDP */



rfc_establish_req(this_mux_id, local_server_chan, remote_server_chan);

Where local_server_chan is the local server channel assigned when the port entityregisters with RFCOMM.

Both methods now continue as follows:

Free the memory block occupied by the RFC_PARNEG_CFM primitive.


Once the RFC_ESTABLISH_REQ message has been sent and the memory associated with thereceived primitive has been freed, the port entity returns control to the scheduler and waits forthe next event.


RFCOMM

© 2001 109

establish_cfm_handler(RFC_ESTABLISH_CFM_T* msg_ptr){deal with msg_ptr-> result_code

Finally free the memory block occupied by the RFC_ESTABLISH_CFM primitive. pfree(msg_ptr) return}


Service Discovery Protocol

© 2001 111

5 Service Discovery ProtocolThis chapter provides an overview of SDP (Service Discovery Protocol) and an introduction tothe SDP API.

� Overview of SDP and its API on page 111

� Key Concepts within SDP on page 112


� SDP API Primitives – SDC on page 116

� SDP API Primitives – SDS on page 123


5.1 Overview of SDP and its API

The Service Discovery SubSystem (SDSS) provides for the discovery of the services availablethrough a Bluetooth device. It is responsible for managing service discovery requests, using theService Discovery Protocol (SDP) and maintaining service records.

The Service Discovery Protocol allows Bluetooth devices to discover what services areavailable, or to find a Bluetooth device that supports a specific service. This is an importantfeature of Bluetooth, given the dynamic nature of ad-hoc networking. It allows a Bluetoothdevice to find a specific service without previous knowledge of the Bluetooth address of thatservice. For example, a laptop could search for a printer service when being used at a locationthat was new to the laptop.

The Service Discovery Protocol is a client server architecture that uses the Service DiscoveryDatabase at the server. The Service Discovery Database (or SDP Server) contains a numberof Service Records, and each Service Record contains attributes of the service. One of theattributes is the Service Record Handle, which uniquely identifies each service record within theSDP Server.

The SDP supports both searching for services and browsing. Searching allows a client tosearch for a specific service, which is subsequently identified by the service handle attribute.Browsing allows a client to discover what services are supported, which are identified by theservice attributes, including the service handle.

The Service Discovery Protocol is run over L2CAP (L2CAP on page 194).

The Service Discovery Protocol sub-system provides both the Service Discovery Server (SDS)and Service Discovery Client (SDC) interfaces via a common API. The differentiation betweenthe interfaces is made using the primitive type.

Within this User Guide the SDS and SDC interfaces are dealt with as if they areseparate interfaces.

5.1.1 Service Discovery Client (SDC) InterfaceThis interface provides service-searching functions1 for the host application, as described in theBluetooth Specification (refer to www.Bluetooth.com). The interface is event-based, followingthe service primitive model.

The parameters for these primitives are listed in the sdc_prim.h file. The parameters includepointers to data describing the search patterns and attribute lists for services being searchedfor. Both search patterns and attribute lists are formatted as the data element sequences, asdescribed in the Bluetooth specification. This is a compact and flexible data format, but it is not

1 Browsing for services is accomplished using the service search functions.




© 2001 112

the easiest format to include in the interface between the SDA and SDSS because the data typeand size information is embedded as bit sections within individual bytes. However, this formatis used to maintain consistency with the SDP.

There are seven basic primitives associated with this interface:

� SDC_Service_Search� SDC_Service_Attribute� SDC_Service_Search_Attribute� SDC_Terminate_Primitive� SDC_Open_Search� SDC_Close_Search� SDC_Config

5.1.2 Service Discovery Server (SDS) InterfaceThis interface allows an application to register and maintain, the database of services providedby the local device. The interface is event-based with downstream and upstream primitives.

The parameters for these primitives are listed in the sds_prim.h file.

There are three primitives associated with this interface:

� SDS_Register� SDS_Unregister� SDS_ConfigIt is the responsibility of the application to provide the service record in the formrequired by the Bluetooth specified Service Discovery Protocol.

5.2 Key Concepts within SDP

5.2.1 Service Record FormatsService records are key to the operation of SDP. As the attribute lists are transmitted acrossthe air using the Service Discovery Protocol, the format of the attributes is standardized. TheBlueStack implementation uses this standardized format internally, and service recordspresented at the SDS API for registration with the database must also be in this format.

The format of the service records is specified in the Bluetooth specification.

The service attributes are defined for each of the profiles in the Bluetooth profiles document. Itis recommended that they be used as the template for the basic requirements for whichattributes are to be defined for each service.

The service record attributes contain:

� details of the service

� details of how the service can be found

Service Record Handle Attribute 1

Service Record

Attribute 2

Attribute n

Attribute IDValue

Figure 5-1: Service Record Attribute List

Each service record is a list of attributes. The service record handle is an index to the particularservice record. Each attribute is made up of an Attribute ID and a value. Service Discovery has



© 2001 113

adopted the following notation for describing the format of the data (whether it be an Attribute IDor an associated value).

Bit 7 6 5 4 3 2 1 0 Byte

Type Size Index

Attribute ID (MSB)

Attribute ID (LSB)

The transfer byte order as described in the Bluetooth Service Discovery Protocol specificationPart E is also noted at this time:

Byte Transfer Order“ The service discovery protocol transfers multiple-byte fields in standard network byte order(Big Endian), with more significant (high-order) bytes being transferred before less-significant(low-order) bytes. ”

The data representation adopted is intended to reflect this transfer mechanism.

In the data representation the ‘Type’ field is the data element type and is represented as a 5-bitdescriptor. The type descriptor is contained in the most significant (high-order) 5 bits of the firstbyte of the data element header. The following types listed in Figure 5-1 on page 112 havebeen defined in the Bluetooth specification.

TypeDescriptor

Values

Valid SizeDescriptor

Values

Type Description

0 0 nil, the null type

1 0,1,2,3,4 unsigned integer

2 0,1,2,3,4 signed twos-complement integer

3 1,2,4 UUID, a universally unique identifier

4 5,6,7 text String

5 0 boolean

6 5,6,7 data element sequence, a data element whose data fieldis a sequence of data elements

7 5,6,7 data element alternative, data element whose data field isa sequence of data elements from which one dataelement is to be selected

8 5,6,7 URL, a uniform resource locator

9-31 Reserved

Table 5-1: Data Types from Bluetooth Specification

The data element size descriptor is represented as a 3-bit size index followed by 0, 8, 16 or 32bits. The size index is contained in the least significant (low order) 3 bits of the first byte of thedata element header. The following size index values have been defined in the Bluetoothspecification.

Size Index Additional Bits Data Size

0 0 1 byte, exception–if the data element type is nil, the datasize is 0 bytes

1 0 2 bytes



© 2001 114

2 0 4 bytes

3 0 8 bytes

4 0 16 bytes

5 8 the data size is contained in the additional 8 bits, whichare interpreted as an unsigned integer



Table 5-2: Size Indexes from Bluetooth Specification

The following data formats are examples of data elements:

Nil is represented as:

Bit 7 6 5 4 3 2 1 0 Byte

Type = 0b00000, Nil Size = 0b000, 0 Bytes

A 16-bit signed integer is represented as:

Bit 7 6 5 4 3 2 1 0 Byte

Type = 0b00010, signed int Size = 0b001, 2 bytes

Data value (MSB)

Data value (LSB)

The five character ASCII string “Mezoe” is represented as:

Bit 7 6 5 4 3 2 1 0 Byte

Type = 0b00100, text string Size = 0b101, see firstbyte below

Length = 0x05

0x4d “M”

0x65 “e”

0x7a “z”

0x6f “o”

0x65 “e”

The actual service records require some additional structure. This is the additional use of thesize and type descriptions to allow lists of data elements to be stored with a single attribute ID.The basic structure is shown in Figure 5-2.



© 2001 115

Level 0 - Attribute ID Level 1 - Length of TotalData Element Sequence

Level 2 - Length of IndividualData Element Sequence

Level 3 - Data

Attribute ID

Type Size Length

Type Size

Type Size Length

Type Size data

Figure 5-2: Service Record Structure

There are exceptions to the above:

� Level 1 can be omitted if there is only one data element in the sequence.

� Levels 1 and 2 can be omitted if the data is not a data element sequence that is associatedwith the Service Attribute.


There are no configurable parameters that can be specified at compile time.

The size of the Service Discovery Database is determined by the number and size of theservice records that are registered with SDP.

The service record memory used is either allocated dynamically from the memory pool, or therecords may be held in non-volatile memory through the optional SDPdbase subsystem (anexample implementation of this subsystem is provided with the BlueStack source code). Bydefault the records are dynamically allocated so the memory pool requirements must be takeninto consideration when using this method.



© 2001 116

5.4 SDP API Primitives– SDC

5.4.1 SDC_SERVICE_SEARCH

typ

e

bd

_ad

dr

err_

cod

e

*err

_in

fo

*rec

_lis

t

max

_n

um

_rec

s

nu

m_r

ecs_

ret

ph

and

le

resp

on

se

*src

h_p

ttrn

size

_err

_in

fo

size

_rec

_lis

t

size

_src

h_p

ttrn

SDC SERVICE SEARCH REQ ✔ ✔ ✔ ✔ ✔ ✔

SDC SERVICE SEARCH CFM ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 5-3: SDC_SERVICE_SEARCH Primitives

Description

SDC_SERVICE_SEARCH initiates a search for services on a remote device and corresponds to theSDP_Service_Search_Request PDU in the Bluetooth specification. The device specified bybd_addr is searched using the search pattern specified by *srch_pttrn.

SDC_SERVICE_SEARCH_CFM returns the results of a search request. The number of servicerecords is returned in num_recs_ret, the size (in bytes) of the list of service record handles isreturned in size_rec_list and the service record handles are returned via the *rec_listpointer.

SDC_SERVICE_SEARCH_CFM also indicates whether or not a search is successful, usingresponse, and if an error has occurred it indicates the error code in err_code. The *err_infois reserved for use for error-specific information that may be used in future versions of theBluetooth specification.

Parameters

type SDC_SERVICE_SEARCH_REQSDC_SERVICE_SEARCH_CFM

bd_addr Bluetooth device address of the remote device.

err_code Error code from SDP_ErrorResponse PDU, as defined in the BluetoothSpecification.

*err_info Reserved for future use.

*rec_list Simple list of 32-bit handles - not formatted as a data element sequence withheaders. Each handle identifies a record on the remote server that matches thesearch criteria. These handles may be used in SDC_SERVICE_ATTRIBUTE_REQprimitives in order to retrieve attributes from the remote server.

max_num_recs The maximum number of record handles to be returned. Range 0x0001 to0xFFFF.

num_recs_ret Number of service record handles returned. This will be no more than themaximum specified in the search request.



© 2001 117

phandle Protocol handle of the higher layer entity using SDP.

response Response indicating success (0x0000) or failure (any other value):

SDC_RESPONSE_SUCCESS Search succeeded

SDC_ERROR_RESPONSE_PDU SDP_Error Response PDU received

SDC_NO_RESPONSE_DATA Empty response - no results

SDC_CON_DISCONNECTED Remote device disconnected

SDC_CONNECTION_ERROR Remote device refused connection

SDC_CONFIGURE_ERROR L2CAP config failed

SDC_SEARCH_DATA_ERROR Search data is invalid

SDC_DATA_CFM_ERROR Failed to transmit PDU

SDC_SEARCH_BUSY Search is busy

SDC_RESPONSE_PDU_HEADER_ERROR The response had a header error

SDC_RESPONSE_PDU_SIZE_ERROR The response had a size error

SDC_RESPONSE_PDU_TIMEOUT_ERROR The response has timed out

SDC_SEARCH_SIZE_TO_BIG The size of the search will not fit into the L2CAP packet

*srch_pttrn Data element sequence of UUIDs that define the search pattern. Therecan be a maximum of 12 UUIDs in the search pattern.

size_err_info The number of bytes in the error information.

size_rec_list The number of bytes in the list.

size_srch_pttrn The number of bytes in the search pattern.



© 2001 118

5.4.2 SDC_SERVICE_ATTRIBUTE

typ

e

*att

r_lis

t

bd

_ad

dr

err_

cod

e

*err

_in

fo

max

_nu

m_a

ttr

ph

and

le

resp

on

se

svc_

rec_

hn

dl

size

_att

r_lis

t

size

_err

_in

fo

SDC SERVICE ATTRIBUTE REQ ✔ ✔ ✔ ✔ ✔ ✔ ✔

SDC SERVICE ATTRIBUTE CFM ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 5-4: SDC_SERVICE_ATTRIBUTE Primitives

Description

SDC_SERVICE_ATTRIBUTE initiates a request for attribute values from a service record on aremote device and corresponds to the SDP_Service_Attribute_Request PDU in the Bluetoothspecification.

Parameters

type SDC_SERVICE_ATTRIBUTE_REQSDC_SERVICE_ATTRIBUTE_CFM

*attr_list Data element sequence of attribute IDs.


err_code Error code from SDP_ErrorResponse PDU, as defined in the BluetoothSpecification.


max_num_attr The maximum number of attribute bytes to be returned in one response packet.Range 0x0007 to 0xFFFF.

















© 2001 119


srv_rec_hndl The service record handle of the service record being queried (asreturned in a SDC_SERVICE_SEARCH_CFM).

size_attr_list The size of the attribute list in bytes pointed to by *attr_list.


5.4.3 SDC_SERVICE_SEARCH_ATTRIBUTE

typ

e

Ph

and

le

tota

l_re

spo

nse

_

size

_att

r_lis

t

*att

r_lis

t

bd

_ad

dr

max

_nu

m_a

ttr

mo

re_t

o_c

om

e

resp

on

se

err_

cod

e

size

_src

h_p

ttrn

*src

h_p

ttrn

size

_err

_in

fo

*err

_in

fo

SDC SERVICE SEARCHATTRIBUTE REQ

✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

SDC SERVICE SEARCHATTRIBUTE CFM

✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 5-5: SDC_SERVICE_SEARCH_ATTRIBUTE Primitives

Description

This primitive initiates a search for attribute values for services available on a remote device. Itaccomplishes the same thing as a SDC_SERVICE_SEARCH_REQ primitive followed by aSDC_SERVICE_ATTRIBUTE_REQ primitive and corresponds to theSDP_Service_Search_Attribute_Request PDU in the Bluetooth specification.

Parameters

type SDC_SERVICE_SEARCH_ATTRIBUTE_REQSDC_SERVICE_SEARCH_ATTRIBUTE_CFM



Total_response_size Total size of entire response in bytes.

size_attr_list The number of bytes in the attribute list.

*attr_list The attribute list and size for a single service, described as a data elementsequence. For multiple services in responses, this primitive will be issuedmultiple times, each one containing the attribute data for one service.

more_to_come TRUE if there are further responses to come (_CFM’s), FALSE for the finalresponse.

err_code Error code from SDP_ErrorResponse PDU, as defined in the Bluetoothspecification.

max_num_attr The maximum number of attribute bytes to be returned in one response packet.Range 0x0007 to 0xFFFF.




© 2001 120














size_srch_pttrn The number of bytes in the search pattern.

*srch_pttrn Data element sequence of UUIDs that define the search pattern. Therecan be a maximum of 12 UUIDs in the search pattern.



5.4.4 SDC_TERMINATE_PRIMITIVE

typ

e

*att

r_lis

t

ph

anle

size

_att

r_lis

t

SDC TERMINATE PRIMITIVE REQ ✔ ✔

Table 5-6: SDC_TERMINATE_PRIMITIVE Primitives

Description

This primitive requests the termination of an active service search. No parameters arenecessary since only one outstanding search request is handled at any time so the search to beterminated can be uniquely identified.

Parameters

type SDC_TERMINATE_PRIMITIVE_REQ

*attr_list Data Element Sequence of Attribute IDs and values.


size_attr_list

The number of bytes, if any, in the attribute list.

Notes



© 2001 121

As there can be only one outstanding request at any one time, this terminates the last SDCrequest, independent of the type of request.

Terminates the currently active search primtive. If a search is in progress then thecorresponding search cfm primitive will be issued with its response set toSDC_RESPONSE_TERMINATED.

5.4.5 SDC_OPEN_SEARCH

typ

e

bd

_ad

dr

ph

and

le

resu

lt

SDC OPEN SEARCH REQ ✔ ✔ ✔

SDC OPEN SEARCH CFM ✔ ✔ ✔

Table 5-7: SDC_OPEN_SEARCH Primitives

Description

This requests the opening of a permanent (L2CAP) connection request for multiple searchinteractions.

Parameters

type SDC_OPEN_SEARCH_REQSDC_OPEN_SEARCH_CFM



result Result of the request:SDC_OPEN_SEARCH_OKSDC_OPEN_SEARCH_BUSYSDC_OPEN_SEARCH_FAILEDSDC_OPEN_SEARCH_OPENSDC_OPEN_SEARCH_DISCONNECTED

Notes

Calling SDC_OPEN_SEARCH a second time will result in the SDC_OPEN_SEARCH_OPEN result. Toclose the connection SDC_CLOSE_SEARCH_REQ must be sent twice.



© 2001 122

5.4.6 SDC_CLOSE_SEARCH

typ

e

resu

lt

ph

and

le

SDC CLOSE SEARCH REQ ✔ ✔

SDC CLOSE SEARCH IND ✔ ✔ ✔

Table 5-8: SDC_CLOSE_SEARCH Primitive

Description

The SDC_CLOSE_SEARCH_REQ primitive requests the closing of a permanent (L2CAP) connectionrequest that has been previously opened with an SDC_OPEN_SEARCH_REQ.

SDC_CLOSE_SEARCH_IND indicates a search close by either the SDS server or the SDC client.

Parameters

type SDC_CLOSE_SEARCH_REQSDC_CLOSE_SEARCH_IND


result Result for SDC_CLOSE_SEARCH_IND:SDC_SDS_DISCONNECTED Connection disconnected by SDS serverSDC_SDC_DISCONNECTED Connection disconnected by SDC client

Notes

If SDC_OPEN_SEARCH has been used twice, SDC_CLOSE_SEARCH_REQ must be sent twice to clsoethe connection.

5.4.7 SDC_CONFIG

typ

e

mtu

SDC CONFIG REQ ✔ ✔

Table 5-9: SDC_CONFIG Primitive

Description

This primitive allows the L2CAP MTU size to be specified for all SDC sessions.

Parameters

type SDC_CONFIG_REQ

mtu L2CAP MTU size. The default value is used if the value supplied is invalid.



© 2001 123

5.5 SDP API Primitives– SDS

5.5.1 SDS_REGISTER

typ

e

ph

and

le

nu

m_r

ec_b

ytes

resu

lt

*ser

vice

_rec

svc_

rec_

hn

dl

SDS REGISTER REQ ✔ ✔ ✔ ✔

SDS REGISTER CFM ✔ ✔ ✔ ✔

Table 5-10: SDS_REGISTER Primitives

Description

This primitive requests that the SDS registers a service that can be provided to other Bluetoothenabled devices.

Parameters

type SDS_REGISTER_REQSDS_REGISTER_CFM


num_rec_bytesThe number of bytes in the service record, in the range 0x000A to 0xFFFF.

result Response indicating success (0x0000) or failure (any other value).REQ_PASSREQ_ERROR

*service_rec A list of attribute IDs and values.

svc_rec_hndl The service record handle that uniquely identifies each service record on aparticular server. It is a 32-bit value in the range 0x00010000– 0xFFFFFFFF.

Notes

See page 112 for a description of the format of service_rec .



© 2001 124

5.5.2 SDS_UNREGISTER

typ

e

ph

and

le

resu

lt

svc_

rec_

hn

dl

SDS UNREGISTER REQ ✔ ✔ ✔

SDS UNREGISTER CFM ✔ ✔ ✔ ✔

Table 5-11: SDS_UNREGISTER Primitives

Description

This primitive requests that a service be unregistered. The service to be unregistered inspecified by its service record handle, which is a 32-bit unsigned integer that uniquely identifieseach service record.

Parameters

type SDS_UNREGISTER_REQSDS_UNREGISTER_CFM


result Response indicating success (0x0000) or failure (any other value).REQ_PASSREQ_ERROR

svc_rec_hndl Uniquely identifies each service record on a particular server. It is a 32-bitvalue in the range 0x00010000–0xFFFFFFFF. Handle of the service to beunregistered.

5.5.3 SDS_CONFIG

typ

e

mtu

SDS CONFIG REQ ✔ ✔

Table 5-12: SDS_CONFIG Primitive

Description

This primitive allows the L2CAP MTU size to be specified for all SDS sessions.

Parameters

type SDS_CONFIG_REQ

mtu L2CAP MTU size. The default value is used if the value supplied is invalid.



© 2001 125


In this section, we provide by way of example a number of usage scenarios and show theexpected typical primitive exchanges that will be seen at the SDP API.




5.6.1 Service Registration

Application SDP

SDS_Register_Req

SDS_Register_Cfm

Figure 5-3: Service Registration

Register a service record corresponding to the serial port profile with SDP.

data_ptr = pmalloc(sizeof(service_record))


msg_ptr = (SDS_REGISTER_REQ_T *)pmalloc(sizeof(SDS_REGISTER_REQ_T))


msg_ptr->type = SDS_REGISTER_REQmsg_ptr->phandle = APP1_QUEUEmsg_ptr->service_rec = data_ptrmsg_ptr->num_rec_bytes = sizeof(service_record)

The application now sends the message to SDP (SDS) via the scheduler.

put_message(sdp_ifacequeue, SDP_PRIM, msg_ptr);

Method 2: Using the library functions (from sdslib.h)

sds_register_req(APP1_QUEUE, data_ptr, sizeof(service_record));

Where data_ptr is the pointer to the memory containing the service record, pamlloc()’dabove.



© 2001 126

Example Service Record

Table 5-13 on page 126 defines the service database entries for the Serial Port Profile.

Item Definition Type/Size Value AttributeID

ServiceClassIDList 0x0001

ServiceClassID Serial Port UUID/32-bit

ProtocolSescriptorList 0x0004

Protocol0 L2CAP UUID/32-bit L2CAP

Protocol1 RFCOMM UUID/32-bit RFCOMM

ProtocolSpecificParameter0 ServerChannel

Uint8 N = serverchannel #

ServiceName Displayabletext name

DataElement/String

“COM1”

Table 5-13: Serial Port Profile Service Database Entries

This is translated into a service record as described in the following section:

Service Class ID List

There is only one service class in the list, Serial Port.

The Service Class ID List is a service attribute with value 0x0001. The data associated with thisis the service class, and this is comprised of a Data Element Sequence.

The Service Class ID List is encoded as follows:

Bit 7 6 5 4 3 2 1 0 Byte

Type = 0b00001, unsigned int Size = 0b001, 2 bytes 0

Attribute ID (MSB) = 0x00 1

Attribute ID (LSB) = 0x01 2

The data element for the service class is encoded as:

Bit 7 6 5 4 3 2 1 0 Byte

Type = 0b00110, Data Element Sequence Size = 0b101, see below 3

Length = 0x05, (length of data element sequence in bytes) 4

Bit 7 6 5 4 3 2 1 0 Byte

Type = 0b00011, UUID Size = 0b010, 4 bytes 5

UUID 16 converted to UUID 32 = 0x00 6


UUID 16 (MSB) = 0x11 8

UUID 16 (LSB) = 0x01 9



© 2001 127

Note that type and size information fields are repeated. The first element in the list indicates thelength of the total number of data elements and the second describes the UUID. Its use is moreobvious in the next set of attributes.

The Protocol Descriptor List Attribute ID is encoded as follows:

Bit 7 6 5 4 3 2 1 0 Byte




With this list of Data Elements, the length of the total sequence is first described, providing aguide to the next Attribute ID.

Bit 7 6 5 4 3 2 1 0 Byte



Although the first data element sequence is simply the UUID for L2CAP, the length must first beprovided, then the UUID. Again, this may not appear totally logical, but provides a consistentstructure and is needed for the case where there is additional information associated with theprotocol (see RFCOMM in the following example).

Bit 7 6 5 4 3 2 1 0 Byte



Bit 7 6 5 4 3 2 1 0 Byte




UUID 16 (MSB) = 0x01 20

UUID 16 (LSB) = 0x00 21

There is then a set of data elements for RFCOMM. These consist of the RFCOMM UUID as theprotocol description and the server channel number. In this example, the PSM used forRFCOMM has to be 0x0003, by default. If any other PSM were used, it would need to beincluded in the description.

The first part of the encoding provides the length of the data element for RFCOMM. Note that inthis case the length is equal to 7 bytes, which is the sum of the RFCOMM UUID description andthe associated parameter.

Bit 7 6 5 4 3 2 1 0 Byte





© 2001 128

First the RFCOMM UUID:

Bit 7 6 5 4 3 2 1 0 Byte




UUID 16 (MSB) = 0x00 27

UUID 16 (LSB) = 0x03 28

Then the parameter:

Bit 7 6 5 4 3 2 1 0 Byte

Type = 0b00001, unsigned int Size = 0b000, 1 byte 29

Value = 0x01 (server channel 1) 30

Finally, the service name:

Bit 7 6 5 4 3 2 1 0 Byte




The Attribute ID is derived from the Service Name offset added to the base offset for theprimary language (which equates to 0x0000 added to 0x0100).

COM1 is given as an example:

Bit 7 6 5 4 3 2 1 0 Byte

Type = 0b00100, text string Size = 0b101, see below 34


0x43 “C” 36

0x4f “O” 37

0x4d “M” 38

0x31 “1” 39



© 2001 129

Using our indentation level format we show the above in Figure 5-4 on page 129:

Level 0 - Attribute ID Level 1 - Length of TotalData Element Sequence

Level 2 - Length of IndividualData Element Sequence

Level 3 - Data

Omitted as only 1 item in list

Type Size Service Name ID + offset

Omitted as data associated with Service Name isa text string and not a data element sequence

Length = 0x04Type Size "COM1"

Type Size RCOMM UUID

Type Size RCOMM chan no

Type Size L2CAP UUID

Type Size Service UUID

Type Size Length = 0x05




Type Size Protocol Descriptor List ID

Type Size Service Class ID

Figure 5-4: COM1 Service Record Example

Note that the SDP is also required to support the service record handle. The Service RecordHandle is allocated by SDP, it is passed to the registering application in the SDS_REGISTER_CFMprimitive.

The application now sends the message to SDP via the scheduler.

Once sent, the application returns control to the scheduler and awaits the next event, in thiscase the confirmation from SDP.

register_cfm_handler(SDS_REGISTER_CFM_T* msg_ptr){

extract msg_ptr->resultif result == success thenextract msg_ptr->svc_rec_hndl and store if required for future reference

Finally, free the memory block occupied by the SDS_REGISTER_CFM primitive.


5.6.2 Service Search Request

Application SDP

SDC_Service_Search_Req

SDC_Service_Search_Cfm



© 2001 130

Figure 5-5: Service Search Request

data_ptr = pmalloc(sizeof(search_pattern))

The search pattern conforms to a Bluetooth specified pattern.

In this example, we assume that the service required is that of the serial port profile. In thiscase the data element for the service class is encoded as:

Bit 7 6 5 4 3 2 1 0 Byte



Bit 7 6 5 4 3 2 1 0 Byte




UUID 16 (MSB) = 0x11 5

UUID 16 (LSB) = 0x01 6


msg_ptr = (SDC_SERVICE_SEARCH_REQ_T *)pmalloc(sizeof(SDC_SERVICE_SEARCH_REQ_T))

The members of the structure are then set up. The Bluetooth device address has beenpreviously obtained, probably by the use of Inquiry.

msg_ptr->type = SDC_SERVICE_SEARCH_REQmsg_ptr->phandle = APP1_QUEUEmsg_ptr->bd_addr.lap = value_of_lapmsg_ptr->bd_addr.nap = value_of_napmsg_ptr->bd_addr.uap = value_of_uapmsg_ptr->max_num_recs = maximum number of records that you can store and

deal withmsg_ptr->srch_pttrn = data_ptrmsg_ptr->size_srch_pttrn = sizeof(search_pattern)



Method 2: Using the library functions (from sdclib.h)

sdc_service_search_req(APP1_QUEUE, p_bd_addr, sizeof(search_pattern)data_ptr, max_num_recs);

Where p_bd_addr is a pointer to the memory containing the bluetooth addressstructure, max_num_recs is maximum number of records that you can store and dealwith and data_ptr is a pointer to the memory containing the search pattern.



© 2001 131

Once sent, the application returns control to the scheduler and awaits the next event, in thiscase the result of the search (confirmation) from SDP.

service_search_cfm_handler(SDC_SERVICE_SEARCH_CFM_T* msg_ptr){

extract msg_ptr->responseif result == success thenextract msg_ptr->num_recs_ret /* let us assume 1 */extract msg_ptr->rec_list and store if required for future reference

Finally, free the memory block occupied by the SDC_SERVICE_SEARCH_CFMprimitive.


The data memory pointed to by rec_list contains the list of service record handles (in thisexample, 1). This is then extracted and stored and used in our next example. The servicerecord handle is a 32-bit number.



© 2001 132

5.6.3 Service Attribute Request

Application SDP

SDC_Service_Attribute_Req

SDC_Service_Attribute_Cfm

Figure 5-6: Service Attribute Request

Request the service attributes on a particular service record handle. The service record handlewill be previously obtained using a Service Search Request.

data_ptr = pmalloc(sizeof(attribute_list))

The attribute list consists of details of the attributes required and conforms to the Bluetoothspecified format. In this example, only the protocol descriptor list is requested - this allows thesearching Bluetooth device to locate the required service within the remote device. The formatis of a data element sequence as follows:

Bit 7 6 5 4 3 2 1 0 Byte



The Protocol Descriptor List attribute ID is encoded as follows:

Bit 7 6 5 4 3 2 1 0 Byte





msg_ptr = (SDC_SERVICE_ATTRIBUTE_REQ_T *)pmalloc(sizeof(SDC_SERVICE_ATTRIBUTE_REQ_T))

The members of the structure are then set up. The Bluetooth device address has beenpreviously obtained, probably by the use of Inquiry.

msg_ptr->type = SDC_SERVICE_ATTRIBUTE_REQmsg_ptr->phandle = APP1_QUEUEmsg_ptr->bd_addr.lap = value_of_lapmsg_ptr->bd_addr.nap = value_of_napmsg_ptr->bd_addr.uap = value_of_uapmsg_ptr->svc_rec_hndl = service record handle value previously obtainedmsg_ptr->max_num_attr = maximum number of attributes that you can store and

deal withmsg_ptr->attr_list = data_ptrmsg_ptr->size_attr_list = sizeof(attribute_list)



© 2001 133



Method 2: Using the library functions (from sdclib.h)

void sdc_service_attribute_req(APP1_QUEUE, p_bd_addr, svc_rec_hndl,sizeof(attribute_list), data_ptr, max_num_attr);

Where p_bd_addr is a pointer to the memory containing the bluetooth addressstructure, svc_rec_hndl is the service record handle value previously obtained,max_num_attr is maximum number of attributes that you can store and deal with anddata_ptr is a pointer to the memory containing the attribute list.

Once sent, the application returns control to the scheduler and awaits the next event, in thiscase the result of the attribute request (confirmation) from SDP.

service_attribute_cfm_handler(SDC_SERVICE_ATTRIBUTE_CFM_T* msg_ptr){

extract msg_ptr->responseif result == success thenextract msg_ptr->num_attr_retextract msg_ptr->attr_list and store if required for future reference

Finally, free the memory block occupied by theSDC_SERVICE_ATTRIBUTE_CFM primitive.


In this case, we assume (as a minimum) that the attribute list is a data element sequencecorresponding to the protocol descriptor list. The example is actually that which we have seenas the protocol descriptor list that has been registered, but with the server channel numberchanged.

Initially there is a data element that defines the length of the data element sequence:

Bit 7 6 5 4 3 2 1 0 Byte



The Protocol Descriptor List attribute ID is encoded as follows:

Bit 7 6 5 4 3 2 1 0 Byte




With a list of Data Elements, the length of the total sequence is described, providing a guide tothe next Attribute ID.



© 2001 134

Bit 7 6 5 4 3 2 1 0 Byte



Although the first data element sequence is simply the UUID for L2CAP, we have to initiallyprovide the length of it, then the UUID. Again, this may not appear totally logical, but provides aconsistent structure and is needed for the case where there is additional information associatedwith the protocol (see RFCOMM, below).

Bit 7 6 5 4 3 2 1 0 Byte



Bit 7 6 5 4 3 2 1 0 Byte




UUID 16 (MSB) = 0x01 12

UUID 16 (LSB) = 0x00 13

There is then a set of data elements for RFCOMM. These comprise the RFCOMM UUID as theprotocol description and the server channel number. In this example, the PSM used forRFCOMM must be 0x0003, by default. If any other PSM was used, it would need to beincluded in the description.

The first part of the encoding provides the length of the data element for RFCOMM. Note that inthis case the length is equal to 7 bytes, which is the sum of the RFCOMM UUID description andthe associated parameter.

Bit 7 6 5 4 3 2 1 0 Byte



First the RFCOMM UUID:

Bit 7 6 5 4 3 2 1 0 Byte




UUID 16 (MSB) = 0x00 19

UUID 16 (LSB) = 0x03 20



© 2001 135

Then the parameter indicating the server channel:

Bit 7 6 5 4 3 2 1 0 Byte

Type = 0b00001, unsigned int Size = 0b000, 1 byte 21

Value = 0x03 (server channel 3) 22


TCS

© 2001 136

6 TCSThis section provides an overview of TCS and an introduction to the API. This chapter containsthe following sections:



� Configurability and Tuners on page 143.

� TCS API Primitives on page 144.

6.1 Overview

TCS Binary is a protocol that provides support for cordless telephony functionality over theBluetooth air interface.

It defines call control functionality for the establishment and clearing of calls, procedures for themanagement of Bluetooth TCS devices, and a limited number of supplementary services.

TCS Binary is based on the ITU-T Recommendation Q.931 ‘ISDN User-Network Interface Layer3 Specification’ [ref Q.931].

The signalling data of TCS Binary is transmitted across the Bluetooth air interface using L2CAPas the transport protocol. Voice transport utilises SCO links, which are controlled from TCSBinary via the Device Manager (DM).

The supplementary services included within the TCS Binary specification are explicit support forCalling Line Identity Presentation (CLIP). TCS Binary also provides a mechanism for sendingDual-Tone Multi-Frequency (DTMF) and Register Recall signals across the air interface. Thisallows a means whereby additional supplementary services within the (fixedtelecommunications) network may be accessed.

L2CAP DM

SDP TCS Binary

Cordless Telephony Application

Figure 6-1: TCS Binary Relationship to Other Entities

The Bluetooth specification includes two profiles that utilise the TCS Binary as defined by theBluetooth specification Part F:3:

The Cordless Telephony profile defines the interoperability requirements of Bluetooth devicesacting as either a Gateway (GW) or as Terminals (TL), where a gateway is a ‘base station’ thatconnects to the ISDN or fixed telecommunications network1, and provides cordlesscommunications services to the Terminals. The Terminals are typically, but not exclusively,cordless handsets.

1 or provides a gateway to a fixed radio access network, CATV based communications network, satellite link or acellular communications network.


TCS

© 2001 137

The Intercom Profile defines the interoperability requirements for direct Terminal to Terminalcommunication. A Cordless Telephony Application may support either or both profiles. Whilst itis unlikely that a Gateway will directly support the Intercom Profile, it can include (group)management functionality that allows direct Terminal to Terminal communication to be achievedwith reduced call set up times.

Within the Bluetooth specification, the profiles are discriminated between by using differentProtocol Service Multiplexer (PSM) values at L2CAP: 0x0005 is defined for the Intercom Profile,and 0x0007 is defined for the Cordless Telephony Profile. Whilst TCS Binary supports bothprofiles, this does place a requirement on the application developer to register which of theprofiles the Cordless Telephony Application provides functionality for. This is achieved usingTCS Registration. In this registration transaction, the application provides the relevant PSMvalues to TCS Binary, and in doing so, declares that capability. The application can registermultiple profile capabilities. The application is also required to supply that PSM value to ServiceDiscovery, as part of the Service Discovery Record that is registered on the local database.

Figure 6-2 illustrates a Cordless Telephony Application that supports multiple profiles; itcontains functionality for both the Cordless Telephony profile and functionality for the Intercomprofile.

L2CAP DM

SDP TCS Binary

PSM = 0x0007 PSM = 0x0005

Cordless Telephony profile functionality

Intercom profilefunctionality

Cordless Telephony Application

Figure 6-2: Cordless Telephony Application supporting multiple profiles

Applications may use PSM numbers from the dynamically assigned range (0x1001 - 0xffff).TCS does not perform any validation of PSM numbers. The PSM is again also registered withSDP, along with the associated service. This allows remote devices to access the service,utilising first SDP to determine service availability and obtain the attributes (including the PSM)and thus connect to the relevant service entity within the application.

It should be noted that the PSM values for the Intercom and Cordless Telephony profiles aredefined, and that Bluetooth qualification for cordless telecommunication will usually be to one orboth of the these profiles. However, the use of the dynamically assigned PSM numbers may beapplicable where additional services over and above those defined in the Cordless Telephonyand Intercom profiles are provided. In this case qualification against the Cordless Telephonyand Intercom profiles would still be possible for the application services with PSM valuescorresponding to those profiles.


TCS

© 2001 138

TL

TL

TL + GW

TelecommunicationsNetwork

Figure 6-3: Cordless Telephony Scenario

The operation of the cordless telephony system (meeting the Cordless Telephony Profile)requires that each Terminal connects to a Gateway (GW) as soon as it is within range of asuitable GW. The initial connection is for signalling data only, and this (virtual) connection ismaintained for as long as the TL is within range of the GW. This is required to reduce TCS callset up times, once there is either an outgoing or an incoming call. The Cordless TelephonyApplication at the TL uses the TCS Attach Procedure to establish this connection. Within theCordless Telephony Profile Specification, this virtual connection is referred to as a ‘link’ and thisterminology is applied here. For the link establishment to be accepted, the applications on bothdevices must have registered the PSM with TCS. Once established, TCS Binary uses ParkMode for power efficiency. Park Mode is used whenever the TL is not in a call, but still attachedto the GW.

The application is returned a unique TCS handle, h_tcs, if the attachment procedure has beensuccessful. This is subsequently used for all further procedures on the link. As TCS supportsthe coexistence of multiple TCS links between a pair of devices, the TCS handle is also used toidentify which link. The multiple links may correspond to attachments made using differentapplication services (as identified by the relevant PSM) or the same application service.

The multiple links may each be initiated by the same device or by different devices. This allowsthe applications to use multiple links if required, and also allows applications to manage TCSlink setup collisions in an appropriate manner.

Once a link has been established, an application may use the link to perform Call Controlprocedures and Group Management procedures.

When the link is no longer required, the Detach procedure is used to close the link (see "TCSlink release" below).

Scenarios illustrating use of the primitives to perform basic initialisation and link managementare provided in the file tcs_prim.h.

Within this user manual, reference is made to timers of the form Txxx, where xxx is the numberof the timer. The timer numbers used are as defined in part F:3 of the Bluetooth Specification,TCS Binary.


TCS

© 2001 139

This section describes the raw TCS primitive interface. It is strongly recommendedthat users of TCS use the functions supplied in the TCS access library,"src\TCSLib\tcs_lib.h". The access library provides one function for each TCSdownstream primitive (ie the _req and _res primitives). Each function accepts thecorrect arguments for its primitive, allocates and populates the primitive, and issues itto the TCS task. Using the access library allows the compiler to verify that all requiredfields are specified for each primitive, eliminating the risk of new fields being addedbut not filled in by user code.

6.2 Key Concepts

This section discusses the concepts introduced by the Bluetooth Specification(www.Bluetooth.com) that are key to TCS that a user of TCS requires knowledge of in order tounderstand and use the API.

The terms Gateway (GW) and Terminal (TL) have already been introduced in the Overview.TCS Binary also introduces the concepts of Incoming Side and Outgoing Side.

There are four key concepts of TCS that the user needs to be aware of when designing theirapplication: Attach, SCO Bearer Call Management, Connectionless Call Management, andGroup Management.

Three further key concepts of Memory Management, TCS Constraints and Race Conditions /Multiple Resources are described at the end of this section.

Incoming Side and Outgoing Side.

These are terms introduced in part F:3 of the Bluetooth Specification, TCS Binary. Theycorrespond to whether the Bluetooth TCS device is the recipient of a SETUP message(Incoming Side), or the initiator of a SETUP message (Outgoing Side). Thus, a TL initiating anoutgoing external call via a GW will be the Outgoing Side. However, the GW receiving thatSETUP message for the outgoing external call will be the Incoming Side for that call setup.

6.2.1 AttachFundamental to the operation of a cordless telecommunications system that meets therequirements of the Cordless Telephony Profile is that each Terminal (TL) is required to Attachto a Gateway. The attachment procedure establishes a TCS Link, which is a virtual connectionestablished using L2CAP. The TCS Link is used for signalling purposes, and is present for aslong as a TL is within range of a GW. It is established as soon as a TL comes within range of asuitable GW, and not just for each call. This is to avoid the paging delay normally associatedwith Bluetooth connection establishment. Although the link exists almost permanently, theunderlying L2CAP connection is likely to be idle (i.e. not used to transfer data) for considerableperiods of time.

6.2.2 SCO Bearer Call Management

SCO links are used as the bearer channel for voice transport. The SCO bearer channel isalways created by the Incoming Side of a call. TCS supports the creation and release of SCOlinks. It is the responsibility of the application to inform TCS when it requires TCS to create theSCO link - TCS will not create it automatically. This gives the application full control over the



TCS

© 2001 140

moment of link creation. This allows in-band tones and announcements to be applied duringcall setup. A common example is to connect dial and other progress tones generated by a localexchange via the audio path to a TL, during outgoing external call setup. TCS will ensure thatthe SCO link is always released during call clearing – there is no requirement placed on theapplication for SCO link release.

The application at the Incoming Side must invoke TCS to create the SCO link, and then wait forthe confirmation, before sending any message to the Outgoing Side indicating that the bearerchannel is ready. The SCO link may be created at any stage during call setup, betweenreceiving the SETUP message and sending the CONNECT message. Whatever happens, theSCO link must be ready at the latest by the time the CONNECT message is sent.

Once the SCO link is ready, the Incoming Side may inform the Outgoing Side of this fact bysending one of:

SETUP-ACKNOWLEDGE,CALL-PROCEEDING,ALERTING, orPROGRESS

messages containing a Progress Indicator element with value chosen to indicate ‘In-bandinformation or appropriate pattern is now available’, or by sending a CONNECT message. TheProgress Indicator element indicating ‘In-band information or appropriate pattern is nowavailable’ takes the numerical value 8, though we recommend setting the progind parameter inthe relevant primitive to TCS_PROGIND_INBAND_INFO. Alternatively, if call clearing with in-bandtones is required, a DISCONNECT message may be sent containing the same ProgressIndicator.

Call Setup Procedure

The application at the Incoming Side invokes SCO link creation by sending aTCS_OPEN_SCO_REQ primitive. TCS will attempt to create the SCO link, and then confirm theresult to the application in a TCS_OPEN_SCO_CFM primitive. The application may then send thenext message to the Outgoing Side to inform it that the SCO link is ready.

When TCS at the Outgoing Side receives the message, it will search for the correct SCO linkand inform the Outgoing Side application in a TCS_OPEN_SCO_IND primitive, and then it will passthe received message up to the application. With this mechanism, the application will alwaysbe informed of the SCO link before it is told to connect to it.

If there is a problem with the SCO link setup (e.g. the Incoming Side does not create it, or itdoes not follow the above procedure correctly), the Outgoing Side application may be told toconnect to the SCO link before it knows about it. The application must decide how to handlethis situation; typically it would start call clearing to release the call.

See the example scenarios in tcs_prim.h for message flows relating to SCO setup.

6.2.3 Connectionless Call ManagementConnectionless Call Management allows a Gateway (GW) to simultaneously inform allattached Terminals (TL) of the arrival of an incoming external call.

An application initiates a connectionless call setup by sending a TCS_CL_SETUP_REQ primitivewith the h_tcs set to TCS_HANDLE_MULTIPOINT. The primitive contains the PSM of theapplication service at the remote device to be used for the call. The local application servicemust have been previously registered with TCS as one that supports connectionlesstransmissions.

TCS then broadcasts the SETUP message to all terminals. When any terminals respond, theapplication will receive the relevant TCS primitive containing the actual h_tcs of the terminal.


TCS

© 2001 141

The only response that an application at the GW should expect is TCS_CONNECT_IND sent by theterminals. This differs from the point to point case in that the SETUP-ACKNOWLEDGE, CALL-PROCEEDING or ALERTING messages are not required.

When a terminal accepts the call and sends the CONNECT message to the gateway, TCS willissue a TCS_CONNECT_IND to the application and will reset the connectionless call control entity,thus stopping any further SETUP broadcasts. Once this has happened, TCS will also releaseany other terminals that have responded or that respond subsequently (this is non-selecteduser clearing), and the application will not receive notification of any more responses.

The TL issuing the CONNECT message is still required to establish the SCO link, as describedin the section on SCO Bearer Call Management.

The call is now identical to one set up by the normal connection-oriented mechanism.

A connectionless call setup may be cancelled at any time before receipt of theTCS_CONNECT_IND by sending a TCS_CL_RELEASE_REQ primitive with theTCS_HANDLE_MULTIPOINT handle. This will respond with a TCS_CL_RELEASED_IND alsocontaining the multipoint handle.

6.2.4 Group ManagementTCS Binary defines a Wireless User Group. This is a group of devices that support TCS Binary,one of which is a master. Normally the master is the Gateway. The Group Managementprocedures are provided to support the management of such a group. The procedures include:

Access rights request,

Configuration distribution, and

Fast inter-member access.

It is intended that the access rights procedure works in association with pairing. TCS Binaryexpects group members to be trusted devices, at least to the GW. TCS does not providespecific pairing primitives, however the Cordless Telephony Application will need to include thecontrol pairing as part of its functionality. This is achieved via the Device Manager API. Accessrights are requested where a WUG member wishes to access the telephony services providedby another member of the group. Typically a TL will make an access rights request to a GW.

Configuration distribution is used to provide information to WUG members about theconfiguration of the group, e.g. when a new member is added, a member leaves the group(using the Detach procedure), and key information. The key information is used to facilitateunconscious pairing. This allows a TL to communicate directly with a TL without specificallypairing; provided that they have both paired with the GW, and the GW has distributed thenecessary key.

Fast inter-member access is a collection of procedures that allows direct TL to TLcommunication to be established quickly by providing signalling to co-ordinate the TLs, andclock information to allow fast synchronisation of the two TL’s frequency hopping. Direct TL toTL communication is useful within a Bluetooth cordless telephony system as it increases theaggregate capacity; a GW can only support a maximum of three SCO links. The three SCOlinks can easily be used by one internal call (switched by the GW) and one external call.

The application declares its capability to deal with group management as part of the registrationprocedure, using the gm_allowed flag. Normally the application will register a service capabilityfor the Cordless Telephony profile using PSM value 0x0007 and will set the gm_allowed flag.

There are also some constraints as to the type of primitives that can be used at the GW and theTL, depending on which is the master. Table 6-1 summarises the primitives that are allowed forthe permitted values of the wug_master_flag.


TCS

© 2001 142

wug_master Flag PrimitiveFALSE TCS_ACCESS_RIGHTS_REQFALSE TCS_ACCESS_RIGHTS_CFMFALSE TCS_WUG_INFO_INDFALSE TCS_WUG_INFO_RESFALSE TCS_LISTEN_REQUEST_REQFALSE TCS_LISTEN_REQUEST_CFMFALSE TCS_LISTEN_SUGGEST_INDFALSE TCS_LISTEN_SUGGEST_RES

TRUE TCS_ACCESS_RIGHTS_INDTRUE TCS_ACCESS_RIGHTS_RESTRUE TCS_WUG_INFO_REQTRUE TCS_WUG_INFO_CFMTRUE TCS_LISTEN_QUERY_INDTRUE TCS_LISTEN_QUERY_RES

Table 6-1: TCS Primitives and wug_master Flag Relationship

6.2.5 Memory Management

All application-to-TCS primitives must be allocated from the memory pool. TCS will pfree() thememory for a primitive when it has processed the primitive.

Similarly, all TCS-to-application primitives are allocated from the memory pool by TCS. Theapplication must pfree() the primitive memory when it has processed the primitive.

Some primitives contain pointers to optional elements. The same memory rules apply to these,and to any pointers within the elements. TCS supplies a function,tcslib_free_tcs_primitive_contents(), which can be called by users of TCS. This functioncorrectly releases any memory referenced within any TCS primitive, leaving the primitive itselfto be freed. Hence the recommended way to tidy up any TCS primitive after processing is:

tcslib_free_tcs_primitive_contents(p_tcs_prim);

pfree(p_tcs_prim);

6.2.6 TCS ConstraintsA constraint is imposed that an application may not have simultaneous connection-oriented andconnectionless call setups in progress on the same application service as defined by the localPSM value. In practice this means that:

If a point to point connection-oriented call setup has been started, a connectionlessone must not be started until after the call has been successfully connected orreleased.

If a connectionless call setup has been started, a point to point connection-orientedone must not be started until after the connectionless one has been successfullyconnected or released.

Note that once a call is active, the constraint is lifted.

This constraint is not enforced by TCS - it is the application’s responsibility to ensure it is notviolated. Violation of this constraint results in undefined behaviour.

The primary reason for this constraint is that there is no way to distinguish between the twocalls when a response is received at the GW.


TCS

© 2001 143

Suppose, for example, that the GW has sent some connectionless broadcast SETUPs and apoint-to-point connection-oriented SETUP via a TCS instance, both using the same PSM value.If a TL responds with an ALERTING message, there is no way to determine whether the TL isresponding to the broadcast connectionless SETUP or to the CO point-to-point connection-oriented SETUP.

6.2.7 Race Conditions / Multiple ResourcesOnce the application has requested connectionless call setup, it is still possible for a terminal-initiated point-to-point connection-oriented call setup to succeed. This will be notified to theapplication via the usual TCS_SETUP_IND, and it is then up to the application to decide: whetherto allow it to proceed, whether to release it, or even cancel the connectionless call setup.

Multiple terminals can respond to the connectionless call setup by sending one or more ofSETUP-ACK, CALL-PROCEEDING or ALERTING. These will all be notified to the application.However, the first terminal to send a CONNECT message is the one which TCS expects to begranted the call by the application. Therefore any further CONNECT messages or otherresponses will be automatically rejected by TCS without informing the application.

If the application requests cancellation of the connectionless call setup (by sendingTCS_CL_RELEASE_REQ with the multipoint handle), TCS may already have issued aTCS_CONNECT_IND and so the connectionless call setup is no longer running. In this case TCSwill not respond to the cancel request.


The following configurable parameters can be specified at compile time:

T301_TIMEOUT - the time to wait at the Outgoing Side for the call to be connected after anALERTING message has been received. The specified time is "minimum 3 minutes". Defaultvalue 3 minutes.

T310_TIMEOUT - the time to wait at the Outgoing Side, after receipt of a CALL PROCEEDINGmessage, for one of ALERTING, CONNECT, DISCONNECT, PROGRESS (ie a timeout on theexternal network locating the called party and alerting it of the call). The specified time is "30 -120 seconds". Default value 30 seconds.

These timeouts can be set in your build configuration file if you wish. The defaults are defined intcs_cc.c.

TCS_MAX_DIGITS - the maximum number of digits allowed in calling/called party numbers.Default value 24 digits. The default is defined in tcs_prim.h.


TCS

© 2001 144

6.4 TCS API Primitives

6.4.1 TCS_REGISTER

typ

e

ph

and

le

psm

mtu

gm

_allo

wed

cl_t

x

acce

pt

TCS REGISTER REQ ✔ ✔ ✔ ✔ ✔ ✔

TCS REGISTER CFM ✔ ✔ ✔ ✔

Table 6-2: TCS_REGISTER Primitives

Description

Registers an application service with TCS. The application service supplies the phandle, whichis used to identify the application service, so that TCS events relating to it can be routedaccordingly. The application service supplies both the phandle and the PSM. TCS associatesthe phandle with the PSM value. Each registered PSM value corresponds to an applicationservice and events received via L2CAP with that PSM value can be routed to the relevantapplication service using the phandle. The application services are typically those that meet therequirements of either the Cordless Telephony profile or the Intercom profile. The PSM valuesfor the profiles being as defined in the Bluetooth Specification. An application is free to use anyPSM numbers from the dynamically assigned range (0x1001 - 0xffff). Application servicedependent characteristics are included in the request, namely the MTU.

TCS_REGISTER_CFM indicates to the higher layer the result of its registration attempt. This canbe accepted (accept flag set to TRUE) or rejected (accept flag set to FALSE).

Parameters

type TCS_REGISTER_REQTCS_REGISTER_CFM


psm PSM of the TCS entity.

mtu MTU for L2CAP channels.

gm_allowed Group Management (GM) flag (TRUE | FALSE). Specifies whether GMoperations are allowed over this application service. If not, then TCS will ignoreany GM messages received from a peer device. If they are allowed, TCS willhandle the GM messages as normal and will expect suitable responses fromthe application.

cl_tx Connectionless transmission flag (TRUE | FALSE). Specifies whether aconnectionless transmission channel should be registered with L2CAP for thisapplication service. A higher entity can then initiate connectionless call setups.



TCS

© 2001 145

6.4.2 TCS_UNREGISTER

typ

e

ph

and

le

psm

TCS UNREGISTER REQ ✔ ✔ ✔

TCS UNREGISTER CFM ✔ ✔ ✔

Table 6-3: TCS_UNREGISTER Primitives

Description

Unregisters the protocol ’psm’, which was previously registered via TCS_REGISTER_REQ. It isthe responsibility of the application to ensure that any active calls on this protocol are cleareddown, and any TCS connections using this protocol are detached.

TCS_UNREGISTER_CFM indicates to the higher layer that the unregistration transaction has beencompleted.

Parameters

type TCS_UNREGISTER_REQTCS_UNREGISTER_CFM


psm PSM of the TCS entity.


TCS

© 2001 146

6.4.3 TCS_ATTACH

typ

e

ph

and

le

psm

wu

g_m

aste

r

cl_r

x

h_t

cs

bd

_ad

dr

acce

pt

TCS ATTACH REQ ✔ ✔ ✔ ✔ ✔

TCS ATTACH CFM ✔ ✔ ✔ ✔ ✔ ✔

TCS ATTACH IND ✔ ✔ ✔ ✔ ✔

Table 6-4: TCS_ATTACH Primitives

Description

A request from the registered application entity to create a TCS connection with the deviceidentified by bd_addr. Specifies which of the previously registered application services to use.

The wug_master flag is used to filter out unexpected GM messages, so for example TCS willnot issue a TCS_ACCESS_RIGHTS_IND primitive to a WUG member application if a TCS ACCESSRIGHTS message is received from a remote device that is not the WUG master. This reducesthe requirements on an application to handle unexpected GM messages. The flag is also usedto ignore invalid GM primitives received from an application - no response will be generated forGM primitives that are ignored.

Note that the value of wug_master flag set in this primitive will determine which device is to bethe master of the group. Subsequent Group Management (GM) primitives are only valid forspecific settings of the wug_master flag, as defined in Table 6-1.

TCS_ATTACH_IND indicates to the higher layer entity that a remote device with address bd_addrhas successfully attached to the local device and expects to use the application service asspecified in psm. The new h_tcs handle is included for use in all subsequent primitives.

If the higher layer entity does not wish to accept this connection, it can terminate it using theTCS_DETACH_REQ primitive.

Parameters

type TCS_ATTACH_REQTCS_ATTACH_CFMTCS_ATTACH_IND

phandle Routing protocol handle of higher entity (application).

psm PSM of the remote TCS entity.

wug_master Specifies whether the local device is to be the WUG master for this TCS link. Used onlyif Group Management procedures are allowed on the registered application service.

cl_rx Connectionless reception flag (TRUE | FALSE). Specifies whetherconnectionless messages received on this connection should be accepted. Ifnot, they will not be passed to this connection for handling and TCS will try tofind another active connection that will handle connectionless messages.


TCS

© 2001 147

h_tcs TCS connection handle. If the ATTACH attempt is accepted the new h_tcs isincluded for use in all subsequent primitive transactions.



Notes

The PSM of the remote application service can be found using Service Discovery.


TCS

© 2001 148

6.4.4 TCS_PREATTACH

typ

e

ph

and

le

psm

wu

g_m

aste

r

cl_r

x

h_t

cs

bd

_ad

dr

acce

pt

TCS PRE ATTACH IND ✔ ✔ ✔ ✔ ✔

TCS PRE ATTACH RES ✔ ✔ ✔ ✔ ✔

Table 6-5: TCS_ PRE_ATTACH Primitives

Description

TCS_PRE_ATTACH_IND provides an indication to the application service that a remote device isattempting to create a TCS link with the local device. The application service must accept orreject the attempt by sending a TCS_PRE_ATTACH_RES primitive. The TCS_PRE_ATTACH_RESprimitive is also used for the setting up of some configuration options for the link.

This primitive does not indicate that the link is set up and ready for use, so an applicationshould not change state on receiving this primitive. A TCS_ATTACH_IND primitive will be issuedwhen the link is ready.

No TCS_ATTACH_IND primitive will be issued if the link setup fails.

The application must send the TCS_PRE_ATTACH_RES primitive in response to aTCS_PRE_ATTACH_IND. The accept flag is used to indicate acceptance of the attach attempt ifTRUE, or rejection if FALSE. If accepted, then TCS will proceed with the link setup, and ifsuccessful will issue a TCS_ATTACH_IND primitive. If the link setup fails, no primitive is issued.

Therefore an application must not change state when sending a TCS_PRE_ATTACH_RES primitiveindicating acceptance, as there is no guarantee that TCS will issue a TCS_ATTACH_IND.

Parameters

type TCS_PRE_ATTACH_INDTCS_PRE_ATTACH_RES



wug_master TRUE if device is WUG master for GM operations, otherwise FALSE.

cl_rx Connectionless reception flag (TRUE | FALSE). Specifies whetherconnectionless messages received on this connection should be accepted. Ifnot, they will not be passed to this connection for handling and TCS will try tofind another active connection that will handle connectionless messages.

h_tcs TCS connection handle.




TCS

© 2001 149

6.4.5 TCS_DETACH

typ

e

ph

and

le

h_t

cs

TCS DETACH REQ ✔ ✔

TCS DETACH IND ✔ ✔ ✔

Table 6-6: TCS_DETACH Primitives

Description

A request from the registered application service to terminate the TCS connection between thelocal device and the remote device. This can only be sent after sending TCS_ATTACH_REQ orreceiving TCS_ATTACH_IND. It cannot be used during the pre-attach phase on the terminatingside of a connection setup.

TCS_DETACH_IND provides an indication to the application service that the TCS connection hasbeen lost or has been detached.

The h_tcs handle is no longer valid after a DETACH.

Parameters

type TCS_DETACH_REQTCS_DETACH_IND

phandle Routing protocol handle of application service.

h_tcs TCS connection handle. The h_tcs handle is no longer valid after a DETACH.


TCS

© 2001 150

6.4.6 TCS_SETUP

typ

e

h_t

cs

call_

clas

s

sen

din

g_c

om

ple

te

bea

rer

sig

nal

*p_c

allin

g_p

arty

*p_c

alle

d_p

arty

*p_c

om

pan

y_sp

ecif

ic

ph

and

le

pro

gin

d

con

nec

tio

nle

ss

TCS SETUP REQ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

TCS SETUP CFM ✔ ✔ ✔ ✔ ✔ ✔

TCS SETUP IND ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

TCS SETUP RES ✔ ✔ ✔ ✔ ✔

Table 6-7: TCS_SETUP Primitives

Description

TCS_SETUP_REQ is used by the Outgoing Side to request the initiation of call establishment.This results in a SETUP message being sent. The application must specify the type of SCOuser information encoding in the bearer element.

TCS_SETUP_CFM indicates that the Incoming Side has responded to the SETUP message with aSETUP ACKNOWLEDGE message. The call is now in the Overlap Sending state, in whichadditional called party digits are expected, guarded by timer T304. This primitive may containthe supported SCO bearer capability if the Incoming Side cannot satisfy the capabilityrequested in SETUP. If the supported capability reported in the TCS_SETUP_CFM primitive is ofno use1 to the application, then the application should release the call.

TCS_SETUP_IND indicates to the application on the Incoming Side that a call setup attempt hasbeen initiated. The application can accept the call by initiating Overlap Sending(TCS_SETUP_RES), Call Proceeding (TCS_CALL_PROCEEDING_REQ), Call Confirmation(TCS_ALERTING_REQ), or Call Connection (TCS_CONNECT_REQ). Alternatively it can reject the call(TCS_DISCONNECT_REQ).

The bearer capability field is always filled in by TCS in a TCS_SETUP_IND - if no capability wasspecified in the SETUP message then TCS fills in the default settings. This means that theapplication does not need to be aware of the TCS defaults.

TCS_SETUP_RES initiates Overlap Sending during call establishment. The Outgoing Side isexpected to send further called party digits in INFORMATION messages. The application maydecide at a suitable time to move on to Call Proceeding (TCS_CALL_PROCEEDING_REQ), CallConfirmation (TCS_ALERTING_REQ), or Call Connection (TCS_CONNECT_REQ).

1 e.g. where the local device cannot support the capability, e.g. a speech encoding method.


TCS

© 2001 151

Parameters

type TCS_SETUP_REQTCS_SETUP_CFMTCS_SETUP_INDTCS_SETUP_RES



call_class TCS call class as defined in section 7.4.4 of Bluetooth specification Part F:3.This mandatory parameter can be one of:

TCS_CALL_CLASS_EXTERNALTCS_CALL_CLASS_INTERCOMTCS_CALL_CLASS_SERVICETCS_CALL_CLASS_EMERGENCY

sending_complete

Flag to indicate that the information (element) being sent is complete. (TRUE |FALSE). The flag is set TRUE to indicate that the information being sent iscomplete. Typically, if the application is sending called party information digitby digit, as the user enters these via a keypad on the TL, then the flag is setFALSE; the application does not know when the information is complete. If theapplication does know that the information is complete, then the flag is setTRUE.

bearer This optional structure, of type TCS_BEARER_CAPABILITY_T as describedbelow, defines a requested or available bearer service. If the bearer capabilityis not specified, the default is SCO HV3 with CVSD coding.

TCS_BEARER_CAPABILITY_T

ParameterParameter Value Notes

valid TRUE If filled inFALSE If not filled in

link_type TCS_LINK_TYPE_SCO

TCS_LINK_TYPE_ACL

TCS_LINK_TYPE_NONE

Link type - section 7.4.3 ofBluetooth specification Part F:3

packet_type TCS_PACKET_TYPE_HV1

TCS_PACKET_TYPE_HV2

TCS_PACKET_TYPE_HV3

TCS_PACKET_TYPE_DV

Packet type - section 7.4.3 ofBluetooth specification Part F:3

user_info TCS_USER_INFO_CVSD

TCS_USER_INFO_PCM_ALAW

TCS_USER_INFO_PCM_ULAW

User information layer 1 - section7.4.3 of Bluetooth specificationPart F:3

TCS only directly supports bearer types SCO or NONE.


TCS

© 2001 152

signal Optional signal element type as defined in section 7.4.16 of Bluetoothspecification Part F:3. TCS_SIGNAL_NONE signifies a null signal, no signalelement will be sent in the message. Can be one of:

TCS_SIGNAL_EXTERNALTCS_SIGNAL_INTERNALTCS_SIGNAL_CALL_BACKTCS_SIGNAL_NONE

*p_calling_party

This optional pointer to a structure, of type TCS_CALLING_PARTY_NUMBER_T asdescribed below, defines the calling parties number details. Specifies the calledparty number for use in SETUP and INFORMATION messages. This is passedas a pointer to pmalloc()ed memory, so the value of the pointer indicates thevalidity of the element.

TCS_CALLING_PART_NUMBER_TParameter

Parameter Value Notes

number_type TCS_NUMBER_TYPE_UNKNOWNTCS_NUMBER_TYPE_INTERNATIONALTCS_NUMBER_TYPE_NATIONALTCS_NUMBER_TYPE_NETWORK_SPECIFICTCS_NUMBER_TYPE_SUBSCRIBERTCS_NUMBER_TYPE_ABBREVIATED

Calling party type ofnumber (Bluetoothspecification Part F:3section 7.4.5)

numbering_plan TCS_PLAN_UNKNOWNTCS_PLAN_ISDN_E164TCS_PLAN_DATA_X121TCS_PLAN_NATIONALTCS_PLAN_PRIVATE

Calling party numberingplan (Bluetoothspecification Part F:3section 7.4.5)

presentation TCS_PRESENTATION_ALLOWEDTCS_PRESENTATION_RESTRICTEDTCS_PRESENTATION_NOT_AVAILABLE

Called party numberpresentation indicator(Bluetooth specificationPart F:3 section 7.4.6)

screening TCS_SCREENING_USER_NONETCS_SCREENING_USER_PASSEDTCS_SCREENING_USER_FAILEDTCS_SCREENING_NETWORK

Called party numberscreening indicator(Bluetooth specificationPart F:3 section 7.4.6)

digits[TCS_MAX_DIGITS] Digits as IA5 characters TCS_MAX_DIGITSdefault value is 24digits.

num_digits Number of digits in digits[]


TCS

© 2001 153

*p_called_partyThis optional pointer to a structure, of type TCS_CALLED_PARTY_NUMBER_T asshown below, defines the calling parties number details. Specifies the called partynumber for use in SETUP messages. This is passed as a pointer to pmalloc()edmemory, so the value of the pointer indicates the validity of the element.

TCS_CALLED_PART_NUMBER_TParameter






digits[TCS_MAX_DIGITS] Digits as IA5 characters TCS_MAX_DIGITS

default value is 24digits.


*p_company_specific

This optional pointer to a structure, of type TCS_COMPANY_SPECIFIC_NUMBER_Tas shown below, defines the company specific details. Transfers company-specific information, for use in most messages. The memory for the contentssupplied in p_contents must be allocated from the memory pool. Whencompany specific information is passed into TCS, TCS will free the memory.When company specific information is passed to the application, the applicationmust free the memory using pfree().

typedef struct

{

tcs_company_id_t company_id; /* 16 bit company ID.0 to 4 pre-allocated.*/

uint8_t *p_contents; /* Pointer to contents, must be pfree()d */

uint8_t length_contents; /* Size of contents */

} TCS_COMPANY_SPECIFIC_T;

progind This optional parameter identifies the progress indication type as defined insection 7.4.13 of Bluetooth specification Part F:3. TCS_PROGIND_NONE signifiesa null progress indicator, no element will be sent in the message. Can be oneof:TCS_PROGIND_INBAND_INFOTCS_PROGIND_NONE

connectionless

This boolean parameter, valid only for the TL, is TRUE for connectionless callsetup.


TCS

© 2001 154

6.4.7 TCS_CL_SETUP

typ

e

h_t

cs

psm

call_

clas

s

sen

din

g_c

om

ple

te

bea

rer

sig

nal

*p_c

allin

g_p

arty

*p_c

alle

d_p

arty

*p_c

om

pan

y_sp

ecif

ic

TCS SETUP REQ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 6-8: TCS_CL_SETUP Primitives

Description

TCS_SETUP_REQ initiates a connectionless call establishment at the Outgoing Side for theapplication service corresponding to the service at the remote device that is specified in theparameter psm. The application service must be one that has been previously registered withTCS, and which supports connectionless transmissions.

It is not permitted for the application to have concurrent single-point and multi-point call setups in progress on the same PSM. If the application attempts to dothis, the results are undefined. However, once a call is in the Active state (i.e. it isconnected), this restriction is lifted.

Parameters

type TCS_CL_SETUP_REQ

psm PSM of the remote TCS application service.


call_class TCS call class as defined in section 7.4.4 of Bluetooth specification Part F:3.This mandatory parameter can be one of:

TCS_CALL_CLASS_EXTERNALTCS_CALL_CLASS_INTERCOMTCS_CALL_CLASS_SERVICETCS_CALL_CLASS_EMERGENCY

sending_complete



TCS

© 2001 155

bearer This optional structure, of type TCS_BEARER_CAPABILITY_T as shown below,defines a requested or available bearer service. If the bearer capability is notspecified, the default is SCO HV3 with CVSD coding.





TCS_LINK_TYPE_ACL

TCS_LINK_TYPE_NONE



TCS_PACKET_TYPE_HV2

TCS_PACKET_TYPE_HV3

TCS_PACKET_TYPE_DV






TCS only directly supports bearer types SCO or NONE.

signal Optional signal element type as defined in section 7.4.16 of Bluetoothspecification Part F:3. TCS_SIGNAL_NONE signifies a null signal, no signalelement will be sent in the message. Can be one of:

TCS_SIGNAL_EXTERNALTCS_SIGNAL_INTERNALTCS_SIGNAL_CALL_BACKTCS_SIGNAL_NONE


TCS

© 2001 156

*p_calling_party

This optional pointer to a structure, of type TCS_CALLING_PARTY_NUMBER_T asdescribed below, defines the calling parties number details. Specifies thecalled party number for use in SETUP and INFORMATION messages. This ispassed as a pointer to pmalloc()ed memory, so the value of the pointerindicates the validity of the element.

TCS_CALLING_PART_NUMBER_TParameter







Called party numberpresentation indicator(Bluetooth specificationPart F:3 section 7.4.6)


Called party numberscreening indicator(Bluetooth specificationPart F:3 section 7.4.6)





TCS

© 2001 157

*p_called_party

This optional pointer to a structure, of type TCS_CALLED_PARTY_NUMBER_T asshown below, defines the calling parties number details. Specifies the calledparty number for use in SETUP messages. This is passed as a pointer topmalloc()ed memory, so the value of the pointer indicates the validity of theelement.

TCS_CALLED_PART_NUMBER_TParameter









*p_company_specific


typedef struct

{






TCS

© 2001 158

6.4.8 TCS_INFO

typ

e

ph

and

le

h_t

cs

sen

din

g_c

om

ple

te

keyp

ad

*p_c

allin

g_p

arty

*p_c

alle

d_p

arty

aud

io_c

on

tro

l

*p_c

om

pan

y_sp

ecif

ic

TCS INFO REQ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

TCS INFO CFM ✔ ✔ ✔

TCS INFO IND ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 6-9: TCS_INFO Primitives

Description

TCS_INFO_REQ requests the sending of an INFORMATION message to provide additionalinformation during overlap sending or when the call is active.

When the INFORMATION message has been sent, TCS will confirm this to the application byissuing a TCS_INFO_CFM primitive. This can be used by the application to implement simpleflow control, for example, where there is a significant amount of data that needs to be sent to aremote device.

TCS_INFO_CFM indicates to the application that the preceding INFORMATION message on thischannel has now been sent. This can be used by the application to implement simple flowcontrol, avoiding the danger of flooding TCS with too many INFORMATION messages.

TCS will queue consecutive INFORMATION messages, so an application does not have to waitfor the confirm between messages. However, it is recommended that applications should waitfor the TCS_INFO_CFM.

Parameters

type TCS_INFO_REQTCS_INFO_CFMTCS_INFO_IND



sending_complete



TCS

© 2001 159

keypad Optional IA5 keypad character.

*p_calling_party

This optional pointer to a structure, of type TCS_CALLING_PARTY_NUMBER_T asshown below, defines the calling parties number details. Specifies the callingparty number for use in SETUP messages. This is passed as a pointer topmalloc()ed memory, so the value of the pointer indicates the validity of theelement.

TCS_CALLING_PARTY_NUMBER_TParameter





Calling partynumbering plan(Bluetoothspecification Part F:3section 7.4.5)


Called party numberpresentation indicator(TCS Binary 7.4.6)


Called party numberscreening indicator(TCS Binary 7.4.6)




*p_called_party

This optional pointer to a structure, of type TCS_CALLED_PARTY_NUMBER_T asshown below, defines the called parties number details. Specifies the calledparty number for use in SETUP messages. This is passed as a pointer topmalloc()ed memory, so the value of the pointer indicates the validity of theelement.

TCS_CALLED_PARTY_NUMBER_TParameter





TCS

© 2001 160


Calling partynumbering plan(Bluetoothspecification Part F:3section 7.4.5)

digits[TCS_MAX_DIGITS] Digits as IA5 characters TCS_MAX_DIGITSdefault value is 24digits.


audio_control

This optional parameter indicates an audio control command. It is a structureas shown below. The ’valid’ flag indicates whether the value in ’audio_control’is valid. If ’valid’ is TRUE, then the audio control information element will beincluded in outgoing messages, or has been received in an incoming message.The audio_control parameter in the structure can take one of the followingvaluesTCS_AC_VOLUME_INCTCS_AC_VOLUME_DECTCS_AC_MIC_GAIN_INCTCS_AC_MIC_GAIN_DEC

typedef struct{ bool_t valid; /* TRUE if filled in */ tcs_audio_control_t audio_control; /* Audio control command */} TCS_AUDIO_CONTROL_T;

*p_company_specific


typedef struct

{






TCS

© 2001 161

6.4.9 TCS_CALL_PROCEEDING

typ

e

h_t

cs

bea

rer

*p_c

om

pan

y_sp

ecif

ic

ph

and

le

pro

gin

d

TCS CALL PROCEEDING REQ ✔ ✔ ✔ ✔ ✔

TCS CALL PROCEEDING IND ✔ ✔ ✔ ✔ ✔ ✔

Table 6-10: TCS_CALL_PROCEEDING Primitives

Description

Requests the sending of a CALL PROCEEDING message to the Outgoing Side to indicate thatthe call is now being established by the network. This moves the call into the Call Proceedingphase.

The application at the Incoming Side may now initiate Call Confirmation (TCS_ALERTING_REQ) orCall Connection (TCS_CONNECT_REQ). Such actions are permitted by the call control statemachine shown in Appendix 1 – TCS Call States of part F:3 of the Bluetooth Specification.

This primitive may contain the supported SCO bearer capability if the Incoming Side Cannotsatisfy the capability requested in SETUP. If the supported capability is of no use to theapplication then it should release the call.

TCS_CALL_PROCEEDING_IND indicates that a CALL PROCEEDING message has been receivedfrom the Incoming Side. The call is now in the Call Proceeding phase.

Parameters

type TCS_CALL_PROCEEDING_REQTCS_CALL_PROCEEDING_IND




TCS

© 2001 162






TCS_LINK_TYPE_ACL

TCS_LINK_TYPE_NONE



TCS_PACKET_TYPE_HV2

TCS_PACKET_TYPE_HV3

TCS_PACKET_TYPE_DV






*p_company_specific


typedef struct

{





progind This optional parameter identifies the progress indication type as defined insection 7.4.13 of Bluetooth specification Part F:3. TCS_PROGIND_NONE signifiesa null progress indicator, no element will be sent in the message. Can be oneof:

TCS_PROGIND_INBAND_INFOTCS_PROGIND_NONE


TCS

© 2001 163

6.4.10 TCS_ALERTING

typ

e

h_t

cs

bea

rer

*p_c

om

pan

y_sp

ecif

ic

ph

and

le

pro

gin

d

TCS ALERTING REQ ✔ ✔ ✔ ✔ ✔

TCS ALERTING IND ✔ ✔ ✔ ✔ ✔ ✔

Table 6-11: TCS_ALERTING Primitives

Description

TCS_ALERTING_REQ sends an ALERTING message to the Outgoing Side to indicate that thecalled user is being alerted. This moves the call into the Call Confirmation phase. Theapplication at the Incoming Side may initiate Call Connection at the appropriate time(TCS_CONNECT_REQ). This action is permitted by the call control state machine shown inAppendix 1 – TCS Call States of part F:3 of the Bluetooth Specification.

The TCS_ALERTING_REQ primitive may contain the supported SCO bearer capability if theIncoming Side cannot satisfy the capability requested in SETUP. Alternatively, if the IncomingSide cannot satisfy the capability requested in SETUP and is unable to suggest an alternativesupported SCO bearer capability in the TCS_ALERTING_REQ primitive, then the Incoming Sideapplication should release the call.

If the supported capability reported back to the Outgoing Side is not adequate, the OutgoingSide application should release the call.

TCS_ALERTING_IND indicates that an ALERTING message has been received from theIncoming Side. The call is now in the Call Confirmation phase.

Parameters

type TCS_ALERTING_REQTCS_ALERTING_IND




TCS

© 2001 164






TCS_LINK_TYPE_ACL

TCS_LINK_TYPE_NONE



TCS_PACKET_TYPE_HV2

TCS_PACKET_TYPE_HV3

TCS_PACKET_TYPE_DV






*p_company_specific


typedef struct

{








TCS

© 2001 165

6.4.11 TCS_OPEN_SCO

typ

e

h_t

cs

ph

and

le

h_s

co

succ

ess

TCS OPEN SCO REQ ✔ ✔

TCS OPEN SCO CFM ✔ ✔ ✔ ✔ ✔

TCS OPEN SCO IND ✔ ✔ ✔ ✔

Table 6-12: TCS_OPEN_SCO Primitives

Description

Requests TCS at the Incoming Side of a voice call to create the SCO bearer channel for thecall. TCS will respond with TCS_OPEN_SCO_CFM indicating the success or failure of the operation.

The TCS_OPEN_SCO_REQ primitive may be sent to TCS at any time during voice call setup inorder to support in-band tones and announcements. However it must have been sent (andanswered) at the latest by the time the application sends TCS_CONNECT_REQ.

TCS will respond with a TCS_OPEN_SCO_CFM primitive indicating whether the bearer wassuccessfully opened. If the call does not have a SCO bearer type associated with it, TCS willignore TCS_OPEN_SCO_REQ.

The TCS_OPEN_SCO_CFM primitive is issued whenever TCS has opened, or failed to open, theSCO bearer channel for a voice call. The success parameter is used to indicate whether theSCO bearer channel has been successfully opened.

The TCS_OPEN_SCO_IND primitive is issued when TCS at the Outgoing Side of a voice call hassuccessfully received the SCO bearer channel for the call from the Incoming Side.

Provided that the Incoming Side creates the SCO bearer channel at the correct time, thisprimitive will always be issued to the application before any other primitive indicating that thebearer channel is ready (e.g. TCS_CONNECT_IND or another primitive containing a progressindicator).

If the application does not receive TCS_OPEN_SCO_IND, it should assume that the bearerchannel has not been created correctly, and should probably choose to release the call.

The application must not connect to the bearer channel until it receives a primitive explicitlystating that the bearer channel is ready (e.g. TCS_CONNECT_IND or a progress indicator).

The application at the Incoming Side MUST always request TCS to create theSCO bearer channel and wait for the response before sending any messageindicating to the Outgoing Side that the bearer channel is ready. Failure to doso will result in undefined behaviour.


TCS

© 2001 166

Parameters

type TCS_OPEN_SCO_REQTCS_OPEN_SCO_CFMTCS_OPEN_SCO_IND



h_sco Contains the HCI connection handle of the SCO connection. This can then beused by the application to route SCO data over HCI.

success TRUE if bearer opened successfully, FALSE if not.


TCS

© 2001 167

6.4.12 TCS_CONNECT

typ

e

h_t

cs

bea

rer

*p_c

om

pan

y_sp

ecif

ic

ph

and

le

TCS CONNECT REQ ✔ ✔ ✔ ✔

TCS CONNECT CFM ✔ ✔ ✔ ✔

TCS CONNECT IND ✔ ✔ ✔ ✔ ✔

TCS CONNECT RES ✔ ✔ ✔

Table 6-13: TCS_CONNECT Primitives

Description

Requests the sending of a CONNECT message to the Outgoing Side to indicate callacceptance by the user. This moves the call into the Call Connection phase in which aCONNECT ACKNOWLEDGE message is expected by the Incoming Side.

The TCS_CONNECT_REQ primitive may contain the supported SCO bearer capability if theIncoming Side cannot satisfy the capability requested in SETUP. Alternatively, if the IncomingSide cannot satisfy the capability requested in SETUP and is unable to suggest an alternativesupported SCO bearer capability in the TCS_CONNECT_REQ primitive, then the Incoming Sideapplication should release the call.

If the supported capability reported back to the Outgoing Side is not adequate, the OutgoingSide application should release the call.

TCS_CONNECT_CFM indicates that a CONNECT ACKNOWLEDGE message has been receivedfrom the Outgoing Side. The call is now Active. The application should now connect the audiopath if not already connected.

TCS_CONNECT_IND indicates that a CONNECT message has been received from the IncomingSide. The call is now in the Call Connection phase. When the Outgoing Side is ready, it shouldcomplete the call setup by sending a CONNECT ACKNOWLEDGE message(TCS_CONNECT_RES). The application should now connect the audio path if not alreadyconnected.

TCS_CONNECT_RES sends a CONNECT ACKNOWLEDGE message to the Incoming Side tocomplete the call setup. The call then moves into the Active state.


TCS

© 2001 168

Parameters

type TCS_CONNECT_REQTCS_CONNECT_CFMTCS_CONNECT_INDTCS_CONNECT_RES








TCS_LINK_TYPE_ACL

TCS_LINK_TYPE_NONE



TCS_PACKET_TYPE_HV2

TCS_PACKET_TYPE_HV3

TCS_PACKET_TYPE_DV






*p_company_specific


typedef struct

{






TCS

© 2001 169

6.4.13 TCS_PROGRESS

typ

e

h_t

cs

*p_c

om

pan

y_sp

ecif

ic

ph

and

le

pro

gin

d

TCS PROGRESS REQ ✔ ✔ ✔ ✔

TCS PROGRESS IND ✔ ✔ ✔ ✔ ✔

Table 6-14: TCS_PROGRESS Primitives

Description

TCS_PROGRESS_REQ is sent by a Gateway to indicate the presence of in-band tones andannouncements.

TCS_PROGRESS_IND indicates that a PROGRESS message has been received. If the progressindicator is TCS_PROGIND_INBAND_INFO then the application should connect the audio path ifnot already connected.

Parameterstype TCS_PROGRESS_REQ

TCS_PROGRESS_IND


h_tcs TCS connection handle.*p_company_specific


typedef struct

{








TCS

© 2001 170

6.4.14 TCS_DISCONNECT

typ

e

h_t

cs

*p_c

om

pan

y_sp

ecif

ic

ph

and

le

cau

se

pro

gin

d

TCS DISCONNECT REQ ✔ ✔ ✔ ✔ ✔

TCS DISCONNECT IND ✔ ✔ ✔ ✔ ✔ ✔

TCS DISCONNECT RES ✔ ✔ ✔

Table 6-15: TCS_DISCONNECT Primitives

Description

Requests release of the call. When used in response to a TCS_SETUP_IND, a RELEASECOMPLETE message is sent and the call will terminate immediately. When used at any othertime, a DISCONNECT message is sent to initiate the graceful termination of the SCO link andthen the call.

If the release procedure proceeds as normal, the application will receive a TCS_RELEASING_INDprimitive when the other side sends the RELEASE message. The application must respondwith TCS_RELEASING_RES - this will cause the RELEASE-COMPLETE message to be sent.During abnormal releases, the TCS_RELEASING_IND/TCS_RELEASING_RES sequence may nothappen.

If the release procedure completes in either a normal or an abnormal manner, theapplication will always receive a TCS_RELEASED_IND primitive to confirm completion.

If a progress indicator of value 8 is specified for sending in the DISCONNECT message, thisinitiates "call clearing with in-band tones", to allow the initiating side to apply tones/announcements during the release of a voice call. This is indicated to the application as theprogind parameter being set to TCS_PROGIND_INBAND_INFO. In this case the timer T305 isnot used - it is expected that the user at the other side will decide when to release. However,the application at the initiating side may force the release to continue by sending aTCS_DISCONNECT_RES primitive.

TCS_DISCONNECT_IND indicates that the other side has disconnected the voice path. This sideshould also disconnect and then send TCS_DISCONNECT_RES into TCS.

TCS_DISCONNECT_RES confirms to TCS that the voice path has now been disconnected inresponse to a TCS_DISCONNECT_IND. TCS can now send a RELEASE message to the otherside.

TCS_DISCONNECT_RES is also used during call clearing with in-band tones by the side thatinitiated call clearing to send a RELEASE message if it does not want to wait any longer for theother side to send RELEASE (note that the T305 timer is not used in the in-band tones case).


TCS

© 2001 171

Parameters

type TCS_DISCONNECT_REQTCS_DISCONNECT_INDTCS_DISCONNECT_RES



*p_company_specific


typedef struct

{







cause Cause of the release (mandatory). Can be one of:

TCS_CAUSE_UNASSIGNED

TCS_CAUSE_NO_ROUTE_TO_DESTINATION

TCS_CAUSE_NORMAL_CALL_CLEARING

TCS_CAUSE_USER_BUSY

TCS_CAUSE_NO_USER_RESPONDING

TCS_CAUSE_NO_ANSWER_FROM_USER

TCS_CAUSE_SUBSCRIBER_ABSENT

TCS_CAUSE_CALL_REJECTED_BY_USER

TCS_CAUSE_NUMBER_CHANGED

TCS_CAUSE_NON_SELECTED_USER_CLEARING

TCS_CAUSE_INVALID_NUMBER_FORMAT

TCS_CAUSE_FACILITIES_REJECTED

TCS_CAUSE_NO_CIRCUIT_AVAILABLE

TCS_CAUSE_TEMPORARY_FAILURE

TCS_CAUSE_REQUESTED_CIRCUIT_NOT_AVAILABLE

TCS_CAUSE_BEARER_CAPABILITY_UNAVILABLE

TCS_CAUSE_BEARER_CAPABILITY_UNSUPPORTED

TCS_CAUSE_REQUESTED_FACILITY_UNSUPPORTED

TCS_CAUSE_RECOVERY_ON_TIMER_EXPIRY

TCS_CAUSE_NONE null cause, no Cause element will be sent in themessage.


TCS

© 2001 172

6.4.15 TCS_RELEASING

typ

e

h_t

cs

*p_c

om

pan

y_sp

ecif

ic

ph

and

le

cau

se

pro

gin

d

TCS RELEASING IND ✔ ✔ ✔ ✔ ✔

TCS RELEASING RES ✔ ✔ ✔ ✔ ✔

Table 6-16: TCS_RELEASING Primitives

Description

TCS_RELEASING_IND indicates that a RELEASE message has been received as part of normalcall clearing. The application must respond with TCS_RELEASING_RES, which will cause theRELEASE-COMPLETE message to be sent.

TCS_RELEASING_RES is the mandatory application response to a TCS_RELEASING_IND primitive.This only happens during normal call clearing, and causes the RELEASE-COMPLETEmessage to be sent.

Note that TCS_RELEASING_RES primitive is identical in content to the TCS_DISCONNECT_REQprimitive.

Parameters

type TCS_RELEASING_INDTCS_RELEASING_RES



*p_company_specific


typedef struct

{






TCS

© 2001 173



cause Cause of the release. Can be one of:




TCS_CAUSE_USER_BUSY


















TCS

© 2001 174

6.4.16 TCS_RELEASED

typ

e

h_t

cs

*p_c

om

pan

y_sp

ecif

ic

ph

and

le

cau

se

TCS RELEASED IND ✔ ✔ ✔ ✔ ✔

Table 6-17: TCS_RELEASED Primitives

Description

Indicates that the call has been released. This can be for a variety of reasons, for example:

- setup rejection by Incoming Side

- normal call release

- abnormal call release

- link loss

On receiving this indication, the application should disconnect the voice path if it has not alreadydone so (e.g. in response to an earlier TCS_DISCONNECT_IND).

The TCS_RELEASED_IND primitive is always sent at the end of a call. It is the only primitive thatan application may rely upon receiving during call release procedures.

Note that it is identical in content to the TCS_RELEASING_IND primitive.

Parameters

type TCS_RELEASED_IND



*p_company_specific


typedef struct

{






TCS

© 2001 175





TCS_CAUSE_USER_BUSY


















TCS

© 2001 176

6.4.17 TCS_CL_RELEASE

typ

e

h_t

cs

*p_c

om

pan

y_sp

ecif

ic

psm

cau

se

TCS CL RELEASE REQ ✔ ✔ ✔ ✔ ✔

Table 6-18: TCS_CL_RELEASE Primitive

Description

Requests cancellation of the connectionless call setup attempt. A common example of whenthis is used is when the call has been removed on the network side. TCS will stop broadcastingthe setup message, initiate the release procedure with any responding devices, and then willissue a TCS_CL_RELEASED_IND primitive as confirmation to the application.

A connectionless call setup may only be cancelled before a CONNECT message is receivedfrom a responding device.

Parameters

type TCS_CL_RELEASE_REQ

h_tcs TCS connection handle. Always TCS_HANDLE_MULTIPOINT.

*p_company_specific


typedef struct

{





psm PSM of the remote TCS entity as defined by the relevant TCS_CL_SETUPconnectionless call establishment.






TCS

© 2001 177

TCS_CAUSE_USER_BUSY


















TCS

© 2001 178

6.4.18 TCS_CL_RELEASED

typ

e

h_t

cs

psm

ph

and

le

cau

se

TCS CL RELEASED IND ✔ ✔ ✔ ✔ ✔

Table 6-19: TCS_CL_RELEASED Primitive

Description

Confirms that the connectionless call setup was stopped upon request of the application.

Parameters

type TCS_CL_RELEASED_IND


h_tcs TCS connection handle. Always TCS_HANDLE_MULTIPOINT.


cause Cause of the release always:



TCS

© 2001 179

6.4.19 TCS_START_DTMF

typ

e

h_t

cs

keyp

ad

ph

and

le

acce

pt

cau

se

TCS START DTMF REQ ✔ ✔ ✔

TCS START DTMF CFM ✔ ✔ ✔ ✔ ✔

TCS START DTMF IND ✔ ✔ ✔ ✔

TCS START DTMF RES ✔ ✔ ✔ ✔

Table 6-20: TCS_START_DTMF Primitives

Description

TCS_START_DTMF_REQ sends a START-DTMF to request the remote side to generate a DTMFtone.

TCS_START_DTMF_CFM indicates that a START-DTMF-ACKNOWLEDGE or START-DTMF-REJECT message has been received.

TCS_START_DTMF_IND indicates that a START-DTMF message has been received.

TCS_START_DTMF_RES acknowledges a START-DTMF message, either accepting it or rejectingit depending on the value of "accept". If "accept" is TRUE then a START-DTMF-ACKNOWLEDGE message is sent, otherwise a START-DTMF-REJECT message is sent.

Parameters

type TCS_START_DTMF_REQTCS_START_DTMF_CFMTCS_START_DTMF_INDTCS_START_DTMF_RES



keypad Mandatory IA5 keypad character.

accept TRUE if DTMF tone was started.

cause Cause (reason) for rejection (when accept==FALSE) Can be one of:




TCS_CAUSE_USER_BUSY










TCS

© 2001 180










TCS

© 2001 181

6.4.20 TCS_STOP_DTMF

typ

e

h_t

cs

ph

and

le

TCS STOP DTMF REQ ✔ ✔

TCS STOP DTMF CFM ✔ ✔ ✔

TCS STOP DTMF IND ✔ ✔ ✔

TCS STOP DTMF RES ✔ ✔

Table 6-21: TCS_STOP_DTMF Primitives

Description

TCS_STOP_DTMF_REQ sends a STOP-DTMF to request the remote side to stop generating aDTMF tone.

TCS_STOP_DTMF_CFM indicates that a STOP-DTMF-ACKNOWLEDGE message has beenreceived.

TCS_STOP_DTMF_IND indicates that a STOP-DTMF message has been received.

TCS_STOP_DTMF_RES acknowledges a STOP-DTMF message, sending a STOP-DTMF-ACKNOWLEDGE message in response.

Parameters

type TCS_STOP_DTMF_REQTCS_STOP_DTMF_CFMTCS_STOP_DTMF_INDTCS_STOP_DTMF_RES




TCS

© 2001 182

6.4.21 TCS_ACCESS_RIGHTS

typ

e

h_t

cs

acce

pt

bd

_ad

dr

*p_c

om

pan

y_sp

ecif

ic

ph

and

le

TCS ACCESS RIGHTS REQ ✔ ✔ ✔

TCS ACCESS RIGHTS CFM ✔ ✔ ✔ ✔ ✔

TCS ACCESS RIGHTS IND ✔ ✔ ✔ ✔ ✔

TCS ACCESS RIGHTS RES ✔ ✔ ✔ ✔

Table 6-22: TCS_ACCESS_RIGHTS Primitives

Description

TCS_ACCESS_RIGHTS_REQ initiates the Obtain Access Rights procedure, sending an ACCESS-RIGHTS-REQUEST message to the remote side in order to become a member of the WirelessUser Group (WUG).Valid if wug_master==FALSE, (see Table 6-1).

TCS_ACCESS_RIGHTS_CFM indicates that the remote side has responded to the Access RightsRequest. The accept flag indicates the success or failure of the request. Valid ifwug_master==FALSE.

TCS_ACCESS_RIGHTS_IND indicates that the remote side is requesting access rights on thesystem, in order to become a member of the WUG. This must be accepted or rejected bysending a TCS_ACCESS_RIGHTS_RES primitive containing an accept flag. Valid ifwug_master==TRUE.

TCS_ACCESS_RIGHTS_RES completes the Obtain Access Rights procedure. If the request hasbeen accepted, accept is TRUE and an ACCESS-RIGHTS-ACCEPT message will be sent tothe remote side. If accept if FALSE, an ACCESS-RIGHTS-REJECT message is sent instead.Valid if wug_master==TRUE.

Parameters

type TCS_ACCESS_RIGHTS_REQTCS_ACCESS_RIGHTS_CFMTCS_ACCESS_RIGHTS_INDTCS_ACCESS_RIGHTS_RES





TCS

© 2001 183

*p_company_specific


typedef struct

{





accept TRUE to accept or to indicate success, FALSE to reject or indicate failure.


TCS

© 2001 184

6.4.22 TCS_WUG_INFO

typ

e

h_t

cs

acce

pt

*p_c

om

pan

y_sp

ecif

ic

n_w

ug

_mem

eber

s

*p_w

ug

_mem

ber

s

ph

and

le

TCS WUG INFO REQ ✔ ✔ ✔ ✔ ✔

TCS WUG INFO CFM ✔ ✔ ✔ ✔ ✔

TCS WUG INFO IND ✔ ✔ ✔ ✔ ✔ ✔

TCS WUG INFO RES ✔ ✔ ✔ ✔

Table 6-23: TCS_WUG_INFO Primitives

Description

TCS_WUG_INFO_REQ initiates the Configuration Distribution procedure towards the remotedevice. This is used by the WUG master to communicate changes in the WUG to all WUGmembers. Valid if wug_master==TRUE, (see Table 6-1).

TCS_WUG_INFO_CFM indicates that the Configuration Distribution procedure with the remotedevice has completed. If the remote device accepted the updated WUG configuration then the’accept’ flag is TRUE. The ’accept’ flag can be FALSE to indicate a failure of the procedure.Valid if wug_master==TRUE.

TCS_WUG_INFO_IND indicates to the application that an updated WUG configuration has beenreceived from the WUG master. The application should accept or reject the updatedconfiguration by sending a TCS_WUG_INFO_RES primitive, setting the ’accept’ flagaccordingly. The application must respond within T403 (4 seconds), otherwise the WUGmaster will deem the procedure to have failed. Valid if wug_master==FALSE.

TCS_WUG_INFO_RES is the response from the application, accepting or rejecting the updatedWUG configuration received from the WUG master. There is no mechanism defined in the TCSspecification to support rejection, therefore if rejection is indicated TCS will simply send nomessage to the WUG master, thus causing the procedure to time out. Valid ifwug_master==FALSE.

Parameters

type TCS_WUG_INFO_REQTCS_WUG_INFO_CFMTCS_WUG_INFO_INDTCS_WUG_INFO_RES



n_wug_membersNumber of WUG members in array *p_wug_members.


TCS

© 2001 185

*p_wug_members

Pointer to an array of WUG members each entry of which has the followingparameters:

bd_addr Bluetooth device address of theremote device for the WUG member.

int_digit_1 First extension digit expressed asan IA5 encoded digit.

int_digit_2 Second digit or ’\0’ if only onedigit used. IA5 encoded.

link_key[SIZE_LINK_KEY] The link key to be used for thisWUG member

The internal extension number of the WUG member can be expressed as one or twoIA5-encoded digits. If just one digit is used, the second one should be set to ’\0’.

*p_company_specific


typedef struct

{





accept TRUE to accept, FALSE to reject.


TCS

© 2001 186

6.4.23 TCS_LISTEN_REQUEST

typ

e

h_t

cs

int_

dig

it_1

int_

dig

it_2

des

t_cl

ock

_off

set

ph

and

le

*p_c

om

pan

y_sp

ecif

ic

acce

pt

cau

se

TCS LISTEN REQUEST REQ ✔ ✔ ✔ ✔ ✔

TCS LISTEN REQUEST CFM ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 6-24: TCS_LISTEN_REQUEST Primitives

Description

TCS_LISTEN_REQUEST_REQ initiates the Fast Inter-Member Access procedure from one WUGmember (the originator) to another WUG member (the terminator) via the WUG master. ALISTEN-REQUEST message is sent to the WUG master. Valid if wug_master==FALSE, (seeTable 6-1).

The parameter int_digit_1 and int_digit2 define the internal extension number of the WUGmember to access. This is the number supplied in the TCS_WUG_MEMBER_T structure in the lastConfiguration Distribution procedure. The number is expressed as one or two IA5-encodeddigits. If just one digit is used, the second one should be set to ’\0’.

TCS_LISTEN_REQUEST_CFM indicates completion of the Inter-Member Access procedure. Ifsuccessful, accept == TRUE, then the originator may assume that the terminating WUGmember is now in page scan mode, and will remain so for T406 (20 seconds). If the procedurefailed, then accept is FALSE and a reason code may be indicated in cause.

For a successful procedure, the primitive may contain the clock offset of the destination devicerelative to the WUG master. If no clock offset has been supplied, dest_clock_offset isTCS_CLOCK_OFFSET_NONE.

The clock offset may be used to reduce the connection setup time when the destination deviceis paged. To do this, the Clock_Offset field of the HCI_Create_Connection command shouldbe set to:

Clock_Offset = dest_clock_offset - local_clock_offset

where local_clock_offset is the clock offset of the originating device relative to the WUGmaster. TCS_LISTEN_REQUEST_CFM is valid if wug_master==FALSE.

Parameters

type TCS_LISTEN_REQUEST_REQTCS_LISTEN_REQUEST_CFM



accept TRUE if successful.

cause Reason for failure (when accept==FALSE) Can be one of:


TCS

© 2001 187




TCS_CAUSE_USER_BUSY

















int_digit_1 First extension digit expressed as an IA5 encoded digit.

int_digit_2 Second extension digit or ’\0’ if only one digit used. IA5 encoded.

dest_clock_offset

Optional 15 bit clock offset (bits 16-2 of clock) for the destination device relativeto the WUG master. If not supplied returns TCS_CLOCK_OFFSET_NONE.

*p_company_specific


typedef struct

{






TCS

© 2001 188

6.4.24 TCS_LISTEN_SUGGEST

typ

e

h_t

cs

des

t_cl

ock

_off

set

pag

e_sc

an_t

ime

ph

and

le

*p_c

om

pan

y_sp

ecif

ic

acce

pt

cau

se

TCS LISTEN SUGGEST IND ✔ ✔ ✔ ✔ ✔

TCS LISTEN SUGGEST RES ✔ ✔ ✔ ✔ ✔ ✔

Table 6-25: TCS_LISTEN_SUGGEST Primitives

Description

TCS_LISTEN_SUGGEST_IND indicates to the terminating WUG member that a LISTEN-SUGGEST message has been received from the WUG master, meaning that another WUGmember wishes this device to enter the page scan mode. The time for which the device shouldremain in page scan mode is indicated in page_scan_time. If this is acceptable, the applicationshould invoke page scan mode and respond with a TCS_LISTEN_SUGGEST_RES primitive withaccept set to TRUE. Otherwise the application must reject the procedure by setting accept toFALSE. Valid if wug_master==FALSE, (see Table 6-1).

TCS_LISTEN_SUGGEST_RES completes the Fast Inter-Member Access procedure. Theterminating WUG member sends this primitive to TCS with the ’accept’ flag set to indicateacceptance or rejection of the procedure. If accepting the procedure, the application shouldensure that the local device is placed into page scan mode before sending theTCS_LISTEN_SUGGEST_RES primitive. The device should remain in page scan mode for theperiod specified in the TCS_LISTEN_SUGGEST_IND primitive.

For a successful procedure, the TCS_LISTEN_SUGGEST_RES primitive may contain the clockoffset of the terminating device relative to the WUG master. If no clock offset has beensupplied, dest_clock_offset is TCS_CLOCK_OFFSET_NONE. TCS_LISTEN_SUGGEST_RES is validif wug_master==FALSE.

Parameters

type TCS_LISTEN_SUGGEST_INDTCS_LISTEN_SUGGEST_RES



*p_company_specific

This optional pointer to a structure, of type TCS_COMPANY_SPECIFIC_NUMBER_Tas shown below, defines the company specific details. Transfers company-specific information, for use in most messages. The memory for the contentssupplied in p_contents must be allocated from the memory pool. Whencompany specific information is passed into TCS, TCS will free the memory.


TCS

© 2001 189

When company specific information is passed to the application, the applicationmust free the memory using pfree().

typedef struct

{





accept TRUE if successful.

cause Reason for failure (when accept==FALSE) Can be one of:




TCS_CAUSE_USER_BUSY

















dest_clock_offset

Optional 15 bit clock offset (bits 16-2 of clock) for the destination device relativeto the WUG master. If not supplied returns TCS_CLOCK_OFFSET_NONE.

page_scan_time Time expressed in units of milliseconds to page scan for.


TCS

© 2001 190

6.4.25 TCS_LISTEN_QUERY

typ

e

h_t

cs

int_

dig

it_1

int_

dig

it_2

ph

and

le

h_t

cs_d

est

cau

se

TCS LISTEN QUERY IND ✔ ✔ ✔ ✔ ✔

TCS LISTEN QUERY RES ✔ ✔ ✔ ✔

Table 6-26: TCS_LISTEN_QUERY Primitives

Description

When the WUG master receives a LISTEN-REQUEST message from the originator of a FastInter-Member Access procedure, the application needs to check that the indicated destinationdevice is a valid WUG member. If the application allows the procedure to continue, it alsoneeds to specify which TCS instance should be used to perform the LISTEN-SUGGEST part ofthe procedure (this is because there could be multiple TCS instances with the destinationdevice and TCS would not otherwise be able to choose between them).

Therefore, on receipt of a LISTEN-REQUEST message, TCS issues a TCS_LISTEN_QUERY_INDprimitive to the application, containing the extension number of the destination device. Theapplication must respond with a TCS_LISTEN_QUERY_RES primitive. TCS_LISTEN_QUERY_IND isvalid if wug_master==TRUE, (see Table 6-1).

The parameters int_digit_1 and int_digit2 define the internal extension number of theWUG member to access. This is the number supplied in the TCS_WUG_MEMBER_T structure in thelast Configuration Distribution procedure. The number is expressed as one or two IA5-encodeddigits. If just one digit is used, the second one should be set to ’\0’.

TCS_LISTEN_QUERY_RES provides a response from the application to a TCS_LISTEN_QUERY_INDprimitive. h_tcs_dest contains the handle of the TCS instance that should be used for theLISTEN-SUGGEST part of the procedure. This may be TCS_HANDLE_NULL to reject theprocedure (e.g. if the device is not a WUG member, or if it is not currently attached to themaster). The cause may contain a failure reason if the procedure is rejected.TCS_LISTEN_QUERY_RES is valid if wug_master==TRUE.

Parameters

type TCS_LISTEN_QUERY_INDTCS_LISTEN_QUERY_RES



h_tcs_dest TCS connection handle (h_tcs) of the destination device. TCS_HANDLE_NULL ifthe procedure has been rejected.

cause Reason for rejection (when h_tcs_dest==tcs_handle_null) Can be one of:




TCS_CAUSE_USER_BUSY


TCS

© 2001 191

















int_digit_1 First extension digit expressed as an IA5 encoded digit.

int_digit_2 Second extension digit or ’\0’ if only one digit used. IA5 encoded.


TCS

© 2001 192

6.4.26 TCS_CL_INFO

typ

e

h_t

cs

ph

and

le

*p_c

om

pan

y_sp

ecif

ic

psm

con

nec

tio

nle

ss

TCS CL INFO REQ ✔ ✔ ✔ ✔

TCS CL INFO CFM ✔ ✔ ✔ ✔

TCS CL INFO IND ✔ ✔ ✔ ✔ ✔

Table 6-27: TCS_CL_INFO Primitives

Description

TCS_CL_INFO_REQ invokes the connectionless TCS (CL) procedure by sending a CL INFOmessage to the remote side(s).

Note that "connectionless" in this sense strictly refers to the fact that this procedure can bedone without establishing a TCS call. The connectionless TCS (CL) procedure may beperformed over connection-oriented channels or over a connectionless channel.

The h_tcs value in the primitive can be a valid TCS instance handle, in which case the CLINFO message is sent over the connection-oriented channel to the single remote device at theother end of the channel. Alternatively, setting h_tcs to TCS_HANDLE_MULTIPOINT and psm to aregistered PSM value transmits the CL INFO message using the L2CAP connectionlesschannel. Note that the application service must have been registered using TCS_REGISTER_REQwith the cl_tx flag set.

Note that use of the connectionless channel is only valid in the direction piconet master topiconet slaves. If a connection-oriented channel is used, CL INFO may be sent in eitherdirection.

When a CL INFO message has been sent, TCS will confirm this to the application by issuing aTCS_CL_INFO_CFM primitive. This can be used by the application to implement simple flowcontrol.

TCS Binary can not guarantee delivery of the CL INFO message if sent over aconnectionless channel. It is the responsibility of the application to perform anyretries that may be necessary.

TCS_CL_INFO_CFM indicates to the application that the preceding CL INFO message on thischannel has now been sent. This can be used by the application to implement simple flowcontrol, avoiding the danger of flooding TCS with too many CL INFO messages.

For a CL INFO message sent over the broadcast channel, the application must wait for thecorresponding TCS_CL_INFO_CFM primitive before sending another broadcast CL INFOmessage.


TCS

© 2001 193

For a CL INFO message sent over a connection-oriented channel, TCS will queue consecutivemessages. However, it is recommended that the application should wait for theTCS_CL_INFO_CFM.

The TCS_CL_INFO_CFM primitive indicates that a CL INFO message has beensent. It will therefore not be issued if the CL INFO message could not be sent.Example cases are:

a) If the application sends a second broadcast CL INFO without waiting forconfirmation of the first, TCS will ignore it.

b) If the application attempts to send a broadcast CL INFO over a PSM that doesnot support broadcast transmission, TCS will ignore it.

TCS_CL_INFO_IND indicates reception of a CL INFO message from the remote device at theother end of the link identified by h_tcs. The CL INFO message may have been received overa connection-oriented channel or a connectionless channel (as long as cl_rx was set inTCS_ATTACH_REQ when the channel was created). The connectionless flag indicates whichchannel type was used.

Parameters

type TCS_CL_INFO_REQTCS_CL_INFO_CFMTCS_CL_INFO_IND


h_tcs TCS instance handle or TCS_HANDLE_MULTIPOINT for broadcast supplied inTCS_CL_INFO_REQ. Copied in the TCS_CL_INFO_CFM response.

*p_company_specific


typedef struct

{





psm PSM value to use for TCS_CL_INFO_REQ if h_tcs == TCS_HANDLE_MULTIPOINT.Copied in the TCS_CL_INFO_CFM response.

connectionless Boolean flag set as TRUE to indicate if the CL INFO was received over aconnectionless channel or FALSE for reception over a connection-orientedchannel.


L2CAP

© 2001 194

7 L2CAPThis chapter provides an overview of L2CAP and an introduction to the API. It contains thefollowing sections:

� Overview of L2CAP and its API on page 194

� Key Concepts on page 195


� L2CAP API Primitives on page 197


7.1 Overview of L2CAP and its API

The L2CAP sub-system is responsible for the implementation of the Logical Link Control andAdaptation Protocol (L2CAP).

The purpose of L2CAP is to provide connection oriented and connectionless data services tohigher layer protocols. In order to achieve this L2CAP provides the following functionality:

� multiplexing of higher layer protocols using the Protocol/Service Multiplexer (PSM)

� the establishment, maintenance and clearing of logical connections for connection orientedservices

� segmentation and re-assembly services to allow up to 64 kilobyte packets to be transportedbetween L2CAP entities

Additional features include support for groups and QoS negotiation for connections.

BlueStack L2CAP provides data services to upper layer protocols with protocol multiplexingcapability, and segmentation and re-assembly operation. L2CAP permits higher layer protocolsand applications to transmit and receive L2CAP data packets up to 64 kilobytes long, providingthat these buffers sizes are physically possible on the target platform. L2CAP is configured ona per connection basis via the API.

The higher layer protocols instruct L2CAP when they need to create a logical connection toanother device in order to transfer data. L2CAP uses the Device Manager to set up andmaintain an ACL link between the two devices. Once the link is active, L2CAP uses the HCIdirectly to send data packets to the Host.

L2CAP executes as a single process in its target environment and primitives are passed toL2CAP via three separate event queues:

� a queue for use by multiple higher layer protocols

� a queue for use by the Device Manager

� an ACL data queue used by the HCI top interface

In addition, a functional interface is supplied that allows the Device Manager to notify L2CAP ofdata related HCI events.


L2CAP

© 2001 195

7.2 Key Concepts

This section discusses the concepts introduced by the Bluetooth specification that are key toL2CAP, and which a user of L2CAP requires knowledge of in order to understand and use theAPI.

The following concepts, reproduced from the Bluetooth Specification, are key to the operation ofL2CAP.

L2CAP uses the convention _RSP as the extension for the response primitive.

7.2.1 PSMThe PSM field is two octets (minimum) in length. The structure of the PSM field is based on theISO 3309 extension mechanism for address fields.

All PSM values are ‘odd’, that is, the least significant bit of the least significant octet must be ‘1’.Also, all PSM values must be assigned such that the least significant bit of the most significantoctet equals ‘0’. This allows the PSM field to be extended beyond 16 bits. PSM values areseparated into two ranges. The values in the first range are assigned by the Bluetooth SIG, andindicate protocols. The second range of values are dynamically allocated and used inconjunction with the Service Discovery Protocol (SDP).

The dynamically assigned values can be used to support multiple implementations of aparticular protocol, for example, RFCOMM, residing on top of L2CAP or for prototyping anexperimental protocol.

7.2.2 CIDChannel identifiers (CIDs) are local names representing a logical channel end-point on thedevice. Identifiers from 0x0001 to 0x003F are reserved for specific L2CAP functions. The nullidentifier (0x0000) is defined as an illegal identifier and must never be used as a destinationend-point.

CID assignment is relative to a particular device and a device can assign CIDs independentlyfrom other devices (unless it needs to use any of the reserved CIDs described in the Bluetoothspecifications). Therefore, even if the same CID value has been assigned to (remote) channelendpoints by several remote devices connected to a single local device, the local device canstill uniquely associate each remote CID with a different device.

7.2.3 MTUThe MTU field represents the largest L2CAP packet payload, in bytes, that the originator of theRequest can accept for that channel.

The MTU is asymmetric and the sender of the request specifies the MTU it can receive on thischannel if it differs from the default value.

The minimum MTU size is 48 bytes. The default value is 672 bytes. The default is definedwithin the header file for the primitives as DEFAULT_MTU.

7.2.4 RTXThe Response Timeout eXpired (RTX) timer is used to terminate the channel when the remoteendpoint is unresponsive to signalling requests.

Implementations are responsible for deciding on the maximum number of Requestretransmissions performed at the L2CAP level before disconnecting the channel. The decision


L2CAP

© 2001 196

should be based on the flush timeout of the signalling link, which is set as a configurationparameter. The longer the flush timeout, the more retransmissions can be performed at thephysical layer and the reliability of the channel improves, requiring fewer retransmissions at theL2CAP level. For example, if the flush timeout is infinite, no retransmissions should beperformed at the L2CAP level.

In BlueStack, the number of RTX retries is set to 3.

The value of this timer is implementation-dependent, but the minimum initial value is 1 secondand the maximum initial value is 60 seconds.

In BlueStack, the timer value for RTX is set to 10 seconds.

7.2.5 ERTXThe Extended Response Timeout eXpired (ERTX) timer is used in place of the RTX timer whenit is suspected the remote endpoint is performing additional processing of a request signal.

In BlueStack the number of ERTX retries is set to 1.

The value of this timer is implementation-dependent but the minimum initial value is 60 secondsand the maximum initial value is 300 seconds.

In BlueStack, the timer value for ERTX is set to 60 seconds.


There are no compile time configuration options or tuners.

The maximum MTU size is configured per connection. This is set via the API using theL2CA_Config_Req primitive. Care must be taken not to set the maximum MTU size too largewhen L2CAP is implemented in a restricted memory environment. If the MTU size is set toolarge, memory starvation can result, and the use of the default MTU as a maximum isrecommended in this case.

L2CAP users must ensure, using pmalloc(), that there are enough memory poolblocks available of the desired MTU size.


L2CAP

© 2001 197

7.4 L2CAP API Primitives

7.4.1 L2CA_REGISTER

typ

e

ph

and

le

psm

L2CA REGISTER REQ ✔ ✔ ✔

L2CA REGISTER CFM ✔ ✔ ✔

Table 7-1: L2CA_REGISTER Primitives

Description

Registers a PSM from a higher layer so that L2CAP can multiplex between the higher layerprotocols.

Parameters

type L2CA_REGISTER_REQL2CA_REGISTER_CFM

phandle Protocol handle of the higher layer entity registering with L2CAP, for example,RFCOMM.

psm Defines the PSM used by the entity registering with L2CAP. The Bluetoothspecification defines a number of default values, for example, the default forRFCOMM is 0x0003. Alternatively, values in the range 0x1001 to 0xFFFF canbe (dynamically) assigned.

Notes

The PSM values are defined locally within the registering module, for example SDP orRFCOMM.


L2CAP

© 2001 198

7.4.2 L2CA_CONNECT

typ

e

bd

_ad

dr

cid

iden

tifi

er

ph

and

le

psm

psm

_lo

cal

pac

ket_

typ

e

resp

on

se

L2CA CONNECT REQ ✔ ✔ ✔ ✔ ✔

L2CA CONNECT RSP ✔ ✔ ✔ ✔

L2CA CONNECT IND ✔ ✔ ✔ ✔ ✔ ✔

L2CA CONNECT CFM ✔ ✔ ✔ ✔ ✔ ✔

Table 7-2: L2CA_CONNECT Primitives

Description

Connect request from higher layer protocol to remote device.

psm_local has been added to provide a way of identifying where the confirmationshould be sent.

Parameters

type L2CA_CONNECT_REQL2CA_CONNECT_RSPL2CA_CONNECT_INDL2CA_CONNECT_CFM

bd_addr Bluetooth Device address of the remote entity.

cid Channel identifier assigned by L2CAP to this connection.

identifier Local identifier supplied by L2CAP when an INDication is received. Should beused by the local higher entity in the corresponding response (RSP). Thisuniquely identifies the indication–response transaction.

phandle Protocol handle of the higher layer entity.

psm Required PSM of the remote higher entity.

psm_local Local PSM of the requesting higher entity.

response Either higher entity response to an incoming request (indication) or the result ofthe request. response can take the following values:

L2CA_CONNECTION_SUCCESSFULL2CA_CONNECTION_PENDINGL2CA_CONNECTION_REJ_PSML2CA_CONNECTION_REJ_SECURITYL2CA_CONNECTION_REJ_RESOURCESL2CA_CONNECTION_REJ_NOT_READYL2CA_CONNECTION_FAILEDL2CA_CONNECTION_TIMEOUT


L2CAP

© 2001 199

packet_type Set to zero for default. Can be one of the following to modify the default:

HCI_PKT_DM1 /* ACL only */HCI_PKT_DH1 /* ACL only */HCI_PKT_DM3 /* ACL only */HCI_PKT_DH3 /* ACL only */HCI_PKT_DM5 /* ACL only */HCI_PKT_DH5 /* ACL only */HCI_PKT_HV1 /* SCO only */HCI_PKT_HV2 /* SCO only */HCI_PKT_HV3 /* SCO only */

Notes

The Bluetooth device address can be obtained by Bluetooth Inquiry.

The value of PSM for the remote higher entity can be found by the use of Service Discovery.Service Discovery itself has a default PSM of 0x0001, as defined by Bluetooth SIG.


L2CAP

© 2001 200

7.4.3 L2CA_CONFIG

typ

e

cid

ou

tflu

sh_t

o

flu

sh_t

o

iden

tifi

er

mo

re_f

lag

in_m

tu

op

tio

ns

*op

tio

ns

ph

and

le

ou

tflo

w

resp

on

se

size

_op

tio

ns

L2CA CONFIG REQ ✔ ✔ ✔ ✔ ✔ ✔ ✔

L2CA CONFIG RSP ✔ ✔ ✔ ✔ ✔ ✔ ✔

L2CA CONFIG IND ✔ ✔ ✔ ✔ ✔ ✔ ✔

L2CA CONFIG CFM ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 7-3: L2CA_CONFIG Primitives

Description

Configuration request for a channel. The configuration request parameters are only applicableto the channel specified and not to L2CAP as a whole.

Parameters

type L2CA_CONFIG_REQL2CA_CONFIG_RSPL2CA_CONFIG_INDL2CA_CONFIG_CFM


outflush_to Number of milliseconds to wait before an L2CAP packet that cannot beacknowledged at the physical layer is dropped. (Named flush_to forL2CA_CONFIG_CFM)

identifier Local identifier supplied by L2CAP when an indication (IND) is received.Should be used by the local higher entity in the corresponding response (_RSP).This uniquely identifies the indication–response transaction.

more_flag Flag set to indicate that there is more to come.

in_mtu Maximum MTU this channel can accept.

options A bit field indicating which of the configuration options are being provided:SPECIFY_MTU – bit 1SPECIFY_FLUSH – bit 2SPECIFY_QOS – bit 3

For example, if options is set to (SPECIFY_MTU+SPECIFY_FLUSH), only thein_mtu and outflush_to fields are used when sending the configuration - inthis case the outflow field is not used, and need not be specified.

*options Pointer to the memory containing the options data.



L2CAP

© 2001 201

outflow Structure QOS_FLOW_T containing the QoS parameters as follows:

typedef struct{ service_type_t service_type; /* best effort, etc */ token_rate_t token_rate; /* token rate */ token_bucket_t token_bucket; /* token bucket */ bandwidth_t peak_bw; /* peak bandwidth */ latency_t latency; /* latency */ variation_t delay_var; /* delay variation */}QOS_FLOW_T;

Currently only the Best Effort service type 0x01 is supported.

response Either higher entity response to an incoming request (indication) or the result ofthe request. Can take the following values:CONFIG_SUCCESSCONFIG_UNACCEPTABLECONFIG_REJECTEDCONFIG_INVALID_CIDCONFIG_UNKNOWNCONFIG_REJECTED_LOCALLYCONFIG_TIMEOUT

size_options Size of the options data in the memory pointed to by *options.

Notes

Care must be taken when selecting the configuration parameters not to cause resourceconflicts. Failure to do this will result in the request being rejected locally.


L2CAP

© 2001 202

7.4.4 L2CA_DATAWRITE

typ

e

cid

*dat

a

len

gth

ph

and

le

resu

lt

L2CA DATAWRITE REQ ✔ ✔ ✔ ✔

L2CA DATAWRITE CFM ✔ ✔ ✔ ✔ ✔

Table 7-4: L2CA_DATAWRITE Primitives

Description

Requests the sending of a L2CAP data packet.

Only one packet can be sent per channel at a time. Higher layers may only transmit anotherpacket when they receive a L2CA_DATAWRITE_CFM primitive.

Parameters

type L2CA_DATAWRITE_REQL2CA_DATAWRITE_CFM


*data Pointer to the memory containing the data.

length Length of the data in bytes.


result Result of the request. Can have the following values:WRITE_SUCCESSWRITE_TIMEOUTWRITE_LINK_TERMINATEDWRITE_NO_CONNECTION

Notes

The data field may be used in two ways:

� If the length field is NON-ZERO, the data field points to a pmalloc’ed block containing thepacket who’s length is indicated by the length field.

� If length is ZERO, the data field points to a message block chain as defined by mblk.h.


L2CAP

© 2001 203

7.4.5 L2CA_DATAREAD

typ

e

cid

cl_p

sm

len

gth

*dat

a

resu

lt

ph

and

le

L2CA DATAREAD IND ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 7-5: L2CA_DATAREAD Primitives

Description

Indicates the arrival of a new L2CAP data packet.

Parameters

type L2CA_DATAREAD_IND



length Length of the data in bytes.

cl_psm PSM number for connectionless reception.

result Result of the operation. Can have the following values:READ_SUCCESSREAD_FAIL



L2CAP

© 2001 204

7.4.6 L2CA_DISCONNECT

typ

e

cid

iden

tifi

er

ph

and

le

resu

lt

L2CA DISCONNECT REQ ✔ ✔

L2CA DISCONNECT RSP ✔ ✔ ✔

L2CA DISCONNECT IND ✔ ✔ ✔ ✔

L2CA DISCONNECT CFM ✔ ✔ ✔ ✔

Table 7-6: L2CA_DISCONNECT Primitives

Description

Request to disconnect a specific L2CAP channel identified by the cid.

Parameters

type L2CA_DISCONNECT_REQL2CA_DISCONNECT_RSPL2CA_DISCONNECT_INDL2CA_DISCONNECT_CFM


identifier Local identifier supplied by L2CAP when an indication is received. Should beused by the local higher entity in the corresponding response (_RSP). This is touniquely identify the indication–response transaction.


result Result of the request. Can have the following values:L2CA_DISCONNECT_SUCCESSFULL2CA_DISCONNECT_TIMEOUT


L2CAP

© 2001 205

7.4.7 L2CA_TIMEOUT

typ

e

cid

ph

and

le

L2CA TIMEOUT IND ✔ ✔ ✔

Table 7-7: L2CA_TIMEOUT Primitives

Description

Indicates that the RTX or ERTX timer has expired. These are Bluetooth specified timers.

Parameters

type L2CA_TIMEOUT_IND



7.4.8 L2CA_QOSVIOLATION

typ

e

bd

_ad

dr

ph

and

le

L2CA QOSVIOLATION IND ✔ ✔ ✔

Table 7-8: L2CA_QOSVIOLATION Primitives

Description

Quality of service violation indication.

Parameters

type L2CA_QOSVIOLATION_IND




L2CAP

© 2001 206

7.4.9 L2CA_PING

typ

e

bd

_ad

dr

*dat

a

len

gth

ph

and

le

psm

_lo

cal

resu

lt

size

L2CA PING REQ ✔ ✔ ✔ ✔ ✔

L2CA PING CFM ✔ ✔ ✔ ✔ ✔

Table 7-9: L2CA_PING Primitives

Description

Ping request to remote device (send echo request signal).

Parameters

type L2CA_PING_REQL2CA_PING_CFM



length Length (size) of the data for the request in bytes.


psm_local PSM of the local higher entity.

result Result of the request. Can have the following values:L2CA_PING_OKL2CA_PING_TIMEOUTL2CA_PING_REJECTED

size Size of the data for the confirm in bytes.


L2CAP

© 2001 207

7.4.10 L2CA_GETINFO

typ

e

bd

_ad

dr

*in

fo_d

ata

info

_typ

e

ph

and

le

psm

resu

lt

size

L2CA GETINFO REQ ✔ ✔ ✔ ✔

L2CA GETINFO CFM ✔ ✔ ✔ ✔ ✔

Table 7-10: L2CA_GETINFO Primitives

Description

Request information from remote device.

Parameters

type L2CA_GETINFO_REQL2CA_GETINFO_CFM


*info_data Pointer to the memory containing the info data.

info_type Identifier of the information type required. Currently only the following isspecified:

Maximum connectionless MTU size, 0x0001.


psm Required PSM of the remote higher entity.

result Result of the request. Can have the following values:L2CA_GETINFO_OKL2CA_GETINFO_NOT_SUPPORTEDL2CA_GETINFO_TIMEOUTL2CA_GETINFO_REJECTED

size Size of the data in bytes.


L2CAP

© 2001 208

7.4.11 L2CA_GROUP_CREATE

typ

e

psm

_lo

cal

cid

ph

and

le

psm

resp

on

se

L2CA GROUP CREATE REQ ✔ ✔

L2CA GROUP CREATE CFM ✔ ✔ ✔ ✔ ✔

Table 7-11: L2CA_GROUP_CREATE Primitives

Description

Creates a group so that connectionless data can be sent using the returned cid.

Parameters

type L2CA_GROUP_CREATE_REQL2CA_GROUP_CREATE_CFM

psm_local The psm of the local requesting protocol.

cid Returned channel identifier for connectionless use.


psm Copy of the psm from L2CA_GROUP_CREATE_REQ.

response Logical connection setup codes. Can have the following values:L2CA_GROUP_SUCCESSFULL2CA_GROUP_FAIL


L2CAP

© 2001 209

7.4.12 L2CA_GROUP_CLOSE

typ

e

psm

_lo

cal

cid

ph

and

le

psm

resp

on

se

L2CA GROUP CLOSE REQ ✔ ✔ ✔

L2CA GROUP CLOSE CFM ✔ ✔ ✔ ✔

Table 7-12: L2CA_GROUP_CLOSE Primitives

Description

Closes a group for use of connectionless data for a particular cid.

Parameters

type L2CA_GROUP_CLOSE_REQL2CA_GROUP_CLOSE_CFM

psm_local The psm of the local requesting protocol.

cid Returned channel identifier for connectionless use.


psm Copy of the psm from L2CA_GROUP_CLOSE_REQ.

response Logical connection setup codes. Can have the following values:L2CA_GROUP_SUCCESSFULL2CA_GROUP_FAIL


L2CAP

© 2001 210

7.4.13 L2CA_ENABLE_CONNECTIONLESS

typ

e

ph

and

le

psm

resp

on

se

L2CA ENABLE CONNECTIONLESS REQ ✔ ✔ ✔

L2CA ENABLE CONNECTIONLESS CFM ✔ ✔ ✔

Table 7-13: L2CA_ENABLE_CONNECTIONLESS Primitives

Description

Enables the reception of connectionless data. This is required so that TCS can page all devicesin a connectionless group.

Parameters

type L2CA_ENABLE_CONNECTIONLESS_REQL2CA_ENABLE_CONNECTIONLESS_CFM


psm The psm of a connectionless channel data stream to enable reception for.

response Logical connection setup codes. Can have the following values:L2CA_CONNECTLESS_SUCCESSFULL2CA_CONNECTLESS_FAIL

7.4.14 L2CA_DISABLE_CONNECTIONLESS

typ

e

ph

and

le

psm

resp

on

se

L2CA DISABLE CONNECTIONLESS REQ ✔ ✔ ✔

L2CA DISABLE CONNECTIONLESS CFM ✔ ✔ ✔

Table 7-14: L2CA_DISABLE_CONNECTIONLESS Primitives

Description

Disables the reception of connectionless data.

Parameters

type L2CA_DISABLE_CONNECTIONLESS_REQL2CA_DISABLE_CONNECTIONLESS_CFM


psm The psm of a connectionless channel data stream to disable reception for.

response Logical connection setup codes. Can have the following values:L2CA_CONNECTLESS_SUCCESSFULL2CA_CONNECTLESS_FAIL


L2CAP

© 2001 211


In this section, we provide by way of example a number of usage scenarios and show theexpected typical primitive exchanges that will be seen at the L2CAP API.




7.5.1 Registration

Application L2CAP API

L2CA_Register_Req

L2CA_Register_CFM

Figure 7-1: Registration

Register Application with L2CAP.


msg_ptr = (L2CA_REGISTER_REQ_T *)pmalloc(sizeof(L2CA_REGISTER_REQ_T))


msg_ptr->type = L2CA_REGISTER_REQmsg_ptr->psm = APPLICATION_PSMmsg_ptr->phandle = APP_L2CAPQUEUE

RFCOMM now sends the message to L2CAP via the scheduler.

put_message(L2CAP_IFACEQUEUE, L2CAP_PRIM, msg_ptr);


l2cap_register_req(APPLICATION_PSM, APP_L2CAPQUEUE);

Where the APPLICATION_PSM is the protocol serial multiplexor that identifies theapplication, and APP_L2CAPQUEUE is the phandle that identifies the application, inthis example.

Once sent, the application returns control to the scheduler and awaits the next event.

register_cfm_handler(L2CA_REGISTER_CFM_T* msg_ptr){

Free the memory block occupied by the L2CA_REGISTER_CFM primitive:


L2CAP

© 2001 212


7.5.2 Connection Establishment and Configuration–Outgoing


L2CA_Connect_Req

L2CA_Connect_Cfm

L2CA_Config_Req

L2CA_Config_Cfm

L2CA_Config_Ind

L2CA_Config_Rsp

Figure 7-2: Connection Establishment–Outgoing

Connection Request from Application.


msg_ptr = (L2CA_CONNECT_REQ_T *)pmalloc(sizeof(L2CA_CONNECT_REQ_T))

The members of the structures are then set up.

msg_ptr->type = L2CA_CONNECT_REQmsg_ptr->bd_addr.lap = value_of_lapmsg_ptr->bd_addr.nap = value_of_napmsg_ptr->bd_addr.uap = value_of_uapmsg_ptr->psm = psm_remote /* found via SDP */msg_ptr->psm_local = APPLICATION_PSM

The application now sends the message to L2CAP via the scheduler.



l2cap_connect_req(p_bd_addr, APPLICATION_PSM, psm_remote);

Where the APPLICATION_PSM is the protocol serial multiplexor that identifies theapplication, psm_remote is the PSM of the remote application (discovered using SDP)and p_bd_addr is a pointer to the memory containing the bluetooth address structure.



L2CAP

© 2001 213

connect_cfm_handler(L2CA_CONNECT_CFM_T* msg_ptr){extract msg_ptr-> cid and store in cid for future referencealso, extract msg_ptr-> response and store as local responseFree the memory block occupied by the L2CA_CONNECT_CFM primitive. pfree(msg_ptr) return}If local response = L2CA_CONNECTION_SUCCESSFULThen we can continue with the configuration.


msg_ptr = (L2CA_CONFIG_REQ_T *)pmalloc(sizeof(L2CA_CONFIG_REQ_T))msg_ptr->type = L2CA_CONFIG_REQ;msg_ptr->cid = cid;msg_ptr->in_mtu = DEFAULT_MTUmsg_ptr->options = SPECIFY_MTU | SPECIFY_FLUSH | SPECIFY_QOSmsg_ptr->outflow.service_type = SERVICE_BEST_EFFORT /* default */msg_ptr->outflow.token_rate = DEFAULT_TOKEN_RATEmsg_ptr->outflow.token_bucket = DEFAULT_TOKEN_BUCKETmsg_ptr->outflow.peak_bw = DEFAULT_PEAK_BWmsg_ptr->outflow.latency = DEFAULT_LATENCYmsg_ptr->outflow. delay_var = DEFAULT_DELAY_VARmsg_ptr->outflush_to = DEFAULT_FLUSH_TOmsg_ptr->more = FALSE




l2cap_config_req(cid, SPECIFY_MTU | SPECIFY_FLUSH | SPECIFY_QOS,DEFAULT_MTU, p_outflow, DEFAULT_FLUSH_TO, FALSE);

Where p_outflow is a pointer to the structure containing the Quality of Serviceparameters.


config_cfm_handler(L2CA_CONFIG_CFM_T* msg_ptr){The handler needs to check the confirmed values and store if relevant, checking:msg_ptr-> response = CONFIG_SUCCESSFree the memory block occupied by the L2CA_CONFIG_CFM primitive. pfree(msg_ptr) return}

The application must now wait for the L2CA_CONFIG_IND from the remote L2CAP andrespond with L2CA_CONFIG_RSP.


L2CAP

© 2001 214

7.5.3 Connection Establishment and Configuration–Incoming


L2CA_Connect_Ind

L2CA_Connect_Rsp

L2CA_Config_Ind

L2CA_Config_Rsp

L2CA_Config_Req

L2CA_Config_Cfm

Figure 7-3: Connection Establishment–Incoming

Here the order of events is slightly different. The ‘application’ is presented an event from L2CAPto start the primitive exchange.

connect_ind_handler(L2CA_CONNECT_IND_T* msg_ptr){extract msg_ptr-> cid and store in cid for future reference, andextract msg_ptr-> identifier and store in identifier for future referenceFree the memory block occupied by the L2CA_CONNECT_IND primitive.pfree(msg_ptr)Now check that we are OK to accept connection, if so respond positively


msg_ptr = (L2CA_CONNECT_RSP_T *)pmalloc(sizeof(L2CA_CONNECT_RSP_T))

The members of the structures are then set up:

msg_ptr->type = L2CA_CONNECT_RSPmsg_ptr->cid = cidmsg_ptr->identifier = identifiermsg_ptr->response = L2CA_CONNECTION_SUCCESSFUL




l2cap_connect_rsp(cid, identifier, L2CA_CONNECTION_SUCCESSFUL);



L2CAP

© 2001 215

return}

config_ind_handler(L2CA_CONFIG_IND_T* msg_ptr){extract msg_ptr-> cid and store in cid for future reference, andextract msg_ptr-> identifier and store in identifier for future referencestore and deal with msg_ptr->options,ditto msg_ptr->size_optionsFree the memory block occupied by the L2CA_CONFIG_IND primitive.pfree(msg_ptr)Now check that we are o.k. to accept config params, if so respond positively


msg_ptr = (L2CA_CONFIG_RSP_T *)pmalloc(sizeof(L2CA_CONFIG_RSP_T))


msg_ptr->type = L2CA_CONFIG_RSPmsg_ptr->cid = cidmsg_ptr->identifier = identifiermsg_ptr->response = CONFIG_SUCCESSmsg_ptr->options /* from wherever stored and modified if necessary */msg_ptr->size_options /* ditto */




l2cap_config_rsp(cid, identifier, size_options, p_options, CONFIG_SUCCESS,FALSE);

Where p_options is a pointer to the structure containing the options, and size_options isthe size of that structure.

}

The application now sends it’s own L2CA_CONFIG_REQ and awaits theL2CA_CONFIG_CFM from the remote device.


L2CAP

© 2001 216

7.5.4 Data Transfer


L2CA_Datawrite_Req

L2CA_Datawrite_Cfm

Figure 7-4: Data Transfer

Send data on the connection identified by cid.

data_ptr = pmalloc(sizeof(DATA))


msg_ptr = (L2CA_DATAWRITE_REQ_T *)pmalloc(sizeof(L2CA_DATAWRITE_REQ_T))

msg_ptr->type = L2CA_DATAWRITE_REQ;msg_ptr->cid = cid;msg_ptr->data = data_ptrmsg_ptr->length = sizeof(DATA)




l2cap_datawrite_req(cid, sizeof(DATA), data_ptr);

Where data_ptr is a pointer to the data.


data_cfm_handler(L2CA_DATAWRITE_CFM_T* msg_ptr){deal with msg_ptr-> result, if requiredFinally free the memory block occupied by the L2CA_DATAWRITE_CFM primitive. pfree(msg_ptr) return}


L2CAP

© 2001 217

7.5.5 Disconnection – Local Initiation


L2CA_Disconnect_Req

L2CA_Disconnect_Cfm

Figure 7-5: Disconnection – Local Initiation

Request the disconnection of the connection identified by cid.


msg_ptr = (L2CA_DISCONNECT_REQ_T *)pmalloc(sizeof(L2CA_DISCONNECT_REQ_T))

msg_ptr->type = L2CA_DISCONNECT_REQ;msg_ptr->cid = cid;

The application now sends the message to L2CAP via the scheduler



l2cap_disconnect_req(cid);

Once sent, The application returns control to the scheduler and awaits the next event.

disconnect_cfm_handler(L2CA_DISCONNECT_CFM_T* msg_ptr){deal with msg_ptr-> result, if requiredFree the memory block occupied by the L2CA_DISCONNECT_CFM primitive. pfree(msg_ptr) return}

7.5.6 Disconnection – Remote Initiation


L2CA_Disconnect_Ind

L2CA_Disconnect_Rsp

Figure 7-6: Disconnection–Remote Initiation


L2CAP

© 2001 218

In this case the application is presented an event from L2CAP to start the primitive exchange.

disconnect_ind_handler(L2CA_DISCONNECT_IND_T* msg_ptr){extract msg_ptr-> cid and store in cid for future reference, andextract msg_ptr-> identifier and store in identifier for future referenceFree the memory block occupied by the L2CA_DISCONNECT_IND primitive.pfree(msg_ptr)

Respond to the disconnect ind


msg_ptr = (L2CA_DISCONNECT_RSP_T *)pmalloc(sizeof(L2CA_DISCONNECT_RSP_T))


msg_ptr->type = L2CA_DISCONNECT_RSPmsg_ptr->cid = cidmsg_ptr->identifier = identifier




l2cap_disconnect_rsp(identifier, cid);


return}


Device Manager

© 2001 219

8 Device ManagerThis chapter contains the following sections:

� Overview on page 219

� Key Concepts on page 220


� Device Manager API Primitives – General on page 225

� Device Manager API Primitives – Application Manager Related on page226

� Device Manager API Primitives – Link Control on page230

� Device Manager API Primitives – Link Policy on page239

� Device Manager API Primitives – Host Control and Baseband on page249

� Device Manager API Primitives – Status Parameters on page257

� Device Manager API Primitives – SCO Control Related on page 259

� Device Manager API Primitives – Security Manager Related on page265


8.1 Overview

Contextually, there are three entities that use the services of the Device Manager. These areillustrated in Figure 8-1.

Device Manager

Application / ApplicationManager

HCI

L2CAP

SCO Control

ServiceRequests

ServiceConfirms and

Indications

HCI CommandsHCI Events

ServiceRequests

ServiceConfirms and

Indications

ServiceConfirms and

Indications

ServiceRequests

Figure 8-1: Device Manager Interfaces


Device Manager

© 2001 220

The Device Manager to L2CAP interface is strictly local to L2CAP and is not an accessible API.Therefore, the L2CAP interface is not discussed further in this document.

The remaining entity interfaces are accessed via a common API. The Service Requests,Confirms and Indications shown in figure 8.1. are defined as primitives. The primitives arespecific to a higher layer entity, such as SCO (Synchronous Connection Oriented) Control orApplication Manager, and are considered as individual logical interfaces. The primitive nameincludes a mnemonic to indicate the logical interface, e.g. DM_SCO_ is used to prefix theprimitives associated with the SCO Control Entity.

There can be zero, one or more than one SCO Control Entity. For example, a Bluetooth devicecontaining both Cordless Telephony and Headset profile functionality has two SCO ControlEntities: one for cordless telephony, and one for the headset. A registration primitive sent fromthe application (SCO control entity) during run-time initialisation indicates to the DeviceManager whether that particular SCO control entity is present.

The interface associated with the Application Manager supports the following:

• HCI Commands and Events (DM_HCI_),

• Security Manager primitives (DM_SM_), and

• Device Manager private primitives (DM_).

Within this document the SCO Control and Application Manager interfaces are dealtwith as if they are separate interfaces.

The Application Manager HCI Commands and Events interface is required for applicationsupport for cases such as Inquiry, where the application indirectly requires a Bluetooth serviceto be executed that is not a direct result of the provision of a communications service via anadapted layer. The Application Manager HCI Commands and Events interface is equivalent tothe HCI Command and Event interface, except for a number of HCI commands and events thatare handled locally by the Device Manager, and are not available at the Application ManagerHCI Commands and Events interface.

The Device Manager, at initialisation, sends a number of HCI Commands to the Link Manager.The commands sent allow the Device Manager to adapt to the capabilities of the HostController. The HCI Commands that are available at the Application Manager HCI Commandsand Events interface allow a more expert user the ability to ‘fine tune’ the operation of the hostcontroller device.

Whereas the HCI interface uses a hci_connection_handle to identify a link to a remote device,the Device Manager API uses the Bluetooth device address, the Device Manager providing thenecessary translation.

In this description of the API, not all the primitives that are supported by the interface are listed.The vast majority of the Application Manager HCI Commands and Events interface primitives atthe API directly replicate a HCI command. These primitives are likely to be required by ‘expert’Bluetooth users (users who are very familiar with the Bluetooth specification, especially theHCI). The examples contained within this User Guide can be used as templates for theoperation of the API, and the information on the full set of primitives is contained in the headerfiles dm_prim.h and hci.h.

Device specific management is a function of either the host controller software or theapplication, not the Device Manager.

8.2 Key Concepts

This section discusses the concepts introduced by the Bluetooth specification that are key toDM and that a user of DM requires knowledge of in order to understand and use the API.


Device Manager

© 2001 221

8.2.1 Device Discoverability and InquiryFor a Bluetooth device to communicate with another Bluetooth device, it has to know theBluetooth device address of that device. This may be entered via a user interface. However,the Bluetooth specification includes a mode called ‘Inquiry’ whereby a device invites otherdevices within range to supply it with their Bluetooth device addresses. Once a Bluetoothdevice address has been obtained by this means, a communications link can then beestablished between the two devices, the ‘called’ device being referred to as the remote device.

Whether a Bluetooth device responds to an Inquiry can be controlled by the application. This isreferred to as discoverability, i.e. the application can determine whether the device is able to bediscovered by other Bluetooth devices. In addition, the application can control whether thedevice can be made connectable, i.e. whether it will respond to call set up attempts directedspecifically at it.

• connection establishment requires knowledge of the remote device’s Bluetooth deviceaddress

• the Bluetooth device address of a device within range may be discovered by an Inquiry

• the discoverability and connectabilty of a device can be controlled by the application

Limited Discoverability is a special case whereby a device in limited discoverable mode mustalso respond to a general inquiry that uses the General Inquiry Access Code (GIAC). ManyBluetooth devices currently only implement a single correlator, and as such can only respond toa single sync word, i.e. can only respond to a single Inquiry Access Code. Thus to implementlimited discoverability it is necessary for the controlling software to time-share between theLimited Inquiry Access Code (LIAC) and the GIAC. The algorithm for this has to beimplemented in the Application Manager. The algorithm is outlined as an example in thesection on Limited Discoverability Mode on page 288.

8.2.2 Security ManagerThe Device Manager incorporates security management functionality. The functionalitysupported is based on that described in the Security Architecture White Paper, seehttp://www.Bluetooth.com. This includes two basic concepts, that of device related security,and that of service related security. The device security aspects are really associated withwhether keys have been exchanged with another Bluetooth device. If keys have beensuccessfully exchanged, then the device can be considered as ‘trusted’ and added to thetrusted device database. The service database contains the security level for each service(application). Here the idea is to use the security methods to control the access to protectedservices, for example services that use the cellphone, where there is the call-time revenue toprotect. Similarly, for services where ease of access by remote devices is required then therecan be no security applied, for example, business card exchange.

The Security Manager includes four modes of operation:

In mode 0, there is no Bluetooth security automatically enabled. Mode 0 is for use byapplications that perform their own security procedures. The service database isunused in this mode, whereas the device database is used only for link keys. Unknownlink keys result in a link key request being forwarded to the application. This is thedefault mode at startup.

In mode 1, the Security Manager automatically accepts all access requests withoutinitiating authentication, encryption, or authorisation procedures. Any attempt by anapplication to perform authentication or encryption procedures will be rejected. TheSecurity Manager will respond to peer-invoked security procedures as for mode 2.



Device Manager

© 2001 222

In mode 2, access requests are subject to the security requirements registered in theservice and device databases. The Security Manager will respond to link key requestsusing the device database - if a link key is unknown, the request is forwarded to theapplication. PIN code requests are forwarded to the application. The application mayinvoke security procedures in this mode.

In mode 3, the host controller is configured to perform authentication and possiblyencryption at LMP link setup. The Security Manager still uses the service database tocontrol authorisation and encryption. The encryption level for mode 3 is specified in’mode3_enc’. If the host controller will not enter authentication mode, then the requestfails (DM_SM_SET_SEC_MODE_CFM has a negative response). If the host controllerdoes enter authentication mode, then the request succeeds. Note that the requestedencryption level may not be supported - in this case the request still succeeds and theactual encryption level is returned in DM_SM_SET_SEC_MODE_CFM.

8.2.3 Link PolicyThe BlueStack Device Manager contains comprehensive functionality to ease the managementof link policy (e.g. park, hold, sniff modes). There are two ways in which link policy may becontrolled:

Firstly, using the Link Manager settings as defined by the Bluetooth specification. These definethe connection modes that are allowed (hold/sniff/park) for a particular link. These settings arecontrolled by the DM_HCI primitives:

DM_HCI_HOLD_MODEDM_HCI_SNIFF_MODEDM_HCI_EXIT_SNIFF_MODEDM_HCI_PARK_MODEDM_HCI_EXIT_PARK_MODEDM_HCI_QOS_SETUP_REQDM_HCI_ROLE_DISCOVERYDM_HCI_SWITCH_ROLEDM_HCI_WRITE_LP_SETTINGS

Secondly, the Device Manager can be configured to control the mode of the connectionaccording to the following settings:

DM_LINK_POLICY_DEFAULT DM does not manage the link in any way. It is left to thehigher layers to control the park and sniff modes. This isthe default mode if no DM policy is specified.

DM_LINK_POLICY_KEEP_ACTIVE DM tries to keep the link active as much as possible. Ifthe link is placed into park mode or sniff mode, DM willtry to return the link to active mode as soon as possible.

DM_LINK_POLICY_KEEP_SNIFF DM tries to keep the link in sniff mode. If the link getsparked, DM will try to unpark it and then enter sniffmode. This mode is intended for use in very low data-rate applications.


Device Manager

© 2001 223

DM_LINK_POLICY_KEEP_PARKED DM tries to keep the link in park mode as much aspossible, while it is "idle" and there are no SCOconnections with the remote device.

The link is deemed to be "idle" if there has been no ACLdata in either direction during the last ’park_idle_time’seconds.

Once the idle criteria are met, DM will try to park theconnection. If the connection is parked at any time andthe idle criteria are not met, DM will try to unpark theconnection.

If ACL data is seen while the connection is parked, DMwill unpark the connection. If a locally-initiated SCOconnection is requested while the ACL connection isparked, DM will unpark the connection beforeattempting to establish the SCO connection.

DM_LINK_POLICY_TRANSPARENT This policy is intended for use by applications that don’treally care what mode the link is in, and do not want toactively control the mode.

The DM will allow the remote device to place the link inany mode. However, if downstream ACL traffic or anoutgoing SCO connect request occurs while the link isparked, the DM will unpark the link to allow datatransfer.

DM_LINK_POLICY_NO_CHANGE Not really a mode, this simply means that the currentDM link policy is not changed. This is used to changethe LM link policy settings without affecting the DM linkpolicy settings.

Notes

The DM will accept mode change requests from the application (i.e. DM_HCI_PARK_MODE,DM_HCI_EXIT_SNIFF_MODE etc) only when the ACL connection is in theDM_LINK_POLICY_DEFAULT mode. When it is in any of the other modes, any mode changerequests will just be answered with a mode change event, DM_HCI_MODE_CHANGE_EVENT,indicating the current mode.

In all modes, the DM will keep the application informed of any changes of mode by issuingDM_HCI_MODE_CHANGE_EVENT events.

It is the responsibility of the caller to specify compatible LM and DM link policies.

The DM_SET_DEFAULT_LINK_POLICY and DM_HCI_WRITE_LP_SETTINGS primitives areused to control the overall link policy settings.

8.2.4 ACL Link ManagementThe BlueStack L2CAP layer automatically manages the setting up, and tearing down, of ACLlinks as a result of higher layers requesting logical connections to remote devices (i.e.RFCOMM, SDP, TCS). The DM provides the interface to L2CAP for ACL link management.

In addition, it is recognised that the application may wish to setup an ACL link to a remotedevice for the purposes of pairing or bonding procedures or to monitor the setting up of ACLlinks. To facilitate this, DM provides an additional interface defined by the following primitives:


Device Manager

© 2001 224

DM_ACL_OPEN_REQ, DM_ACL_OPEN_CFM, DM_ACL_CLOSE_REQ, DM_ACL_OPENED_INDand DM_ACL_CLOSED_IND.

8.2.5 SCO Flow ControlSCO flow control is introduced across the HCI. It is a credit based system, where the HostController announces at initialization (or reset) the number of buffers that it has available, andthe size of packet that the buffers can hold. It is up to the higher layer entity (the SCO Controlentity) to apportion the buffers between different SCO connections, if there is more than oneconnection.

The number of buffers effectively defines a credit limit, and the higher layer SCO entity maysend SCO packets to the Host Controller up to that limit. As the packets are successfullytransmitted, the Host Controller passes a HCI Event to the Device Manager, and this HCI Eventis passed to the higher layer SCO Control entity as a DM_DATA_SEND_IND primitive. Thisprimitive contains information on the number of packets successfully transmitted.

The higher layer SCO Control entity maintains a credit counter that is maintained in a manneras illustrated by Figure 8-2 on page 224.

SCO Host ControllerSCO Control

DM_Buffer_Size_Ind (CDT = 5)

SCO Data Packet

SCO Data Packet

SCO Data Packet

SCO Data Packet

Sending Packet

Sending Packet

Sending Packet

Sending Packet

Credit = 3

Credit = 2+2=4

Credit = 2

Credit = 3

Credit = 4

Credit = 5

DM_Data_Sent (2 Packets)

Clear to Send

Figure 8-2: SCO Control Entity Credit Counter

If the higher layer SCO Control entity runs out of credits, it asserts flow control, in this exampleto the SCO entity. It is up to the system designer to decide whether the data is buffered locallyor if it is discarded. For real-time speech applications, discarding the packets is recommended.

The SCO Data packets themselves are not routed via the SCO Control to the DeviceManager interface.

Further information on how to set up and use an SCO data channel can be found onpage 301 .


Device Manager

© 2001 225

8.2.6 Local NameThe local name is a user specifiable ‘friendly’ name that is used to identify the Bluetooth device.For example, a Bluetooth device could be programmed to have the local name ‘Paul’s laptop’.The local name can be a maximum size of 248 bytes. If it is less than 248 bytes, it isrepresented as a null terminated string. International Alphabet 5 (IA5) notation is usedthroughout. For example, the local name ‘Paul’s laptop’ would be represented as the following:

0x50 0x61 0x75 0x6c 0x60 0x73 0x20 0x6c 0x61 0x70 0x74 0x6f 0x70 0x00

Within BlueStack, when changing the local name, the data is stored using a maximum of 4 x 64byte buffers. This makes more efficient use of the memory pool resources because it avoidsthe need for a single 256 byte buffer. Within these buffers the encoding rules described aboveapply. However, all 4 buffers must be allocated and pointers to those buffers must be provided.Null pointers are not allowed in association with the user friendly name exchanges.

Returned friendly names are stored using a maximum buffer size defined in dm_config.h:

#define NAME_LENGTH_TRUNCATION 40

If a received name is longer than this value, the name is truncated to a zero terminated string ofthe defined truncation length.

8.2.7 Parameter CachingThe Device Manager provides a facility whereby remote device parameters may be cached.The application can write the page mode and clock offset parameters to the Device Manager ona per device basis. This allows the Device Manager to use this information at a later time,which can improve connection establishment times under certain circumstances.


The dm_config.h file contains the definitions for the host ACL and SCO buffers. These valuesmay be tailored to the resource availability of the host processor environment.

8.4 Device Manager API Primitives – General

In this section only a selection of the complete DM API is described.

DM API primitives are named with the following convention:

DM_HCI_primitive-name These are HCI commands as described in the Bluetoothspecification that are accessible at the API.

DM_SCO_primitive-name These are primitives used in association with SCO control.

DM_SM_primitive-name These are primitives used in association with securitymanagement.

DM_primitive-name These are DM specific primitives. These may often relateclosely to the Bluetooth HCI specification.

Where a HCI command is used for SCO control or security management unmodified it appearswith the naming convention DM_HCI_primitive-name.

The primitives described here are those that are most commonly used and needed for basicoperation of a Bluetooth application.

Please refer to file dm_prim.h and hci.h for a description of the Device Manager primitives notdescribed here.


Device Manager

© 2001 226

8.5 Device Manager API Primitives – Application Manager Related

8.5.1 DM_AM_REGISTER

typ

e

ph

and

le

DM AM REGISTER REQ ✔ ✔

DM AM REGISTER CFM ✔ ✔

Table 8-1: DM_AM_REGISTER Primitives

Description

DM_AM_REGISTER registers a higher layer entity as the Application Manager with the DeviceManager.

Parameters

type DM_AM_REGISTER_REQDM_AM_REGISTER_CFM

phandle Protocol handle of the registering entity, the Application Manager.


Device Manager

© 2001 227

8.5.2 DM_WRITE_CACHED_PAGE_MODE

typ

e

bd

_ad

dr

pag

e_sc

an_m

od

e

pag

e_sc

an_r

ep_m

od

e

ph

and

le

stat

us

DM WRITE CACHED PAGE MODE REQ ✔ ✔ ✔ ✔

DM WRITE CACHED PAGE MODE CFM ✔ ✔ ✔

Table 8-2: DM_WRITE_CACHED_PAGE_MODE Primitives

Description

Cache the page mode parameters for a given bd_addr.

Parameters

type DM_WRITE_CACHED_PAGE_MODE_REQ

DM_WRITE_CACHED_PAGE_MODE_CFM

bd_addr Bluetooth device address.

page_scan_mode Modes as defined in the Bluetooth HCI specification.HCI_PAGE_SCAN_MODE_MANDATORY

page_scan_rep_mode R0, R1 or R2 as defined in the Bluetooth HCI specification.HCI_PAGE_SCAN_REP_MODE_R0HCI_PAGE_SCAN_REP_MODE_R1HCI_PAGE_SCAN_REP_MODE_R2

phandle Protocol handle of higher entity (application manager).

status 0 indicates success, all other values indicate failure.

Notes

This primitive has been provided in order to allow the most efficient parameters to be used forsetting up ACL baseband connections. This will reduce the baseband connection setup time.The correct values for a particular bd_addr may be obtained in the inquiry results returned frominquiry.

Once the cache is set-up for a bd_addr, the cached values will be updated by subsequentinquiry results.

See also DM_WRITE_CACHED_CLOCK_OFFSET.


Device Manager

© 2001 228

8.5.3 DM_WRITE_CACHED_CLOCK_OFFSET

typ

e

bd

_ad

dr

clo

ck_o

ffse

et

ph

and

le

stat

us

DM WRITE CACHED CLOCK OFFSET REQ ✔ ✔ ✔

DM WRITE CACHED CLOCK OFFSET CFM ✔ ✔ ✔

Table 8-3: DM_WRITE_CACHED_CLOCK_OFFSET Primitives

Description

Cache the clock offset parameter for a given bd_addr.

Parameters

type DM_WRITE_CACHED_CLOCK_OFFSET_REQ

DM_WRITE_CACHED_CLOCK_OFFSET_CFM

bd_addr Bluetooth device address.

clock_offset The clock offset between master and slave, only bits 0:14 valid as defined in theBluetooth HCI specification.



Notes

This primitive has been provided in order to allow the most efficient parameters to be used forsetting up ACL baseband connections. This will reduce the baseband connection setup time.The correct value for a particular bd_addr may be obtained in the inquiry results returned frominquiry.

Once the cache is set-up for a bd_addr, the cached values will be updated by subsequentinquiry results or DM_READ_CLOCK_OFFSET.

See also DM_WRITE_CACHED_PAGE_MODE.


Device Manager

© 2001 229

8.5.4 DM_CLEAR_PARAM_CACHE

typ

e

bd

_ad

dr

ph

and

le

stat

us

DM CLEAR PARAM CACHE REQ ✔ ✔

DM CLEAR PARAM CACHE CFM ✔ ✔ ✔

Table 8-4: DM_CLEAR_PARAM_CACHE Primitives

Description

Clear all cached parameters for a given bd_addr.

Parameters

type DM_CLEAR_PARAM_CACHE_REQ

DM_CLEAR_PARAM_CACHE_CFM

bd_addr Bluetooth Device Address of the remote device.



Notes

See also DM_WRITE_CACHED_PAGE_MODE and DM_WRITE_CACHED_CLOCK_OFFSET.


Device Manager

© 2001 230

8.6 Device Manager API Primitives – Link Control

8.6.1 DM_HCI_INQUIRY

com

mo

n_o

p_c

od

e

lap

inq

uir

y_le

ng

th

nu

m_r

esp

on

ses

DM HCI INQUIRY ✔ ✔ ✔ ✔

Table 8-5: DM_HCI_INQUIRY Primitive

Description

DM_HCI_INQUIRY requests the generation of a HCI Inquiry command to be sent to the LinkManager.

Parameters

common_op_code

DM_HCI_INQUIRY

lap Lower Address Part of the Bluetooth Device Address that defines the InquiryAccess Code. The following are valid:0x9E8B33 General/Unlimited Inquiry Access Code (GIAC)0x9E8B00 Limited Dedicated Inquiry Access Code (LIAC)

inquiry_length

Length of time in units of 1.28 seconds before an inquiry is halted. Takes avalue in the range 1 to 48 (0x01 to 0x30).

num_responsesNumber of responses before a HCI inquiry complete is reported. Takes a valuein the range 0 to 255 (0x00 to 0xFF). A value of 0 indicates that there is no limitplaced on the number of responses expected.

Notes

The value of num_responses is dependent on the resources (memory) available to theapplication manager to store the responses. The inquiry length is more application dependent,for example, taking into consideration how long user would wait for the result of the inquiry.

Setting the value of num_responses to 0 will result on the inquiry complete being reported at theend of the timeout period.

It is recommended that num_responses is always set to greater than 0 and that for any value ofnum_responses a timeout be used by the application.


Device Manager

© 2001 231

8.6.2 DM_HCI_INQUIRY_RESULT

typ

e

resu

lt

nu

m_r

esp

on

ses

ph

and

le

DM HCI INQUIRY RESULT ✔ ✔ ✔ ✔

Table 8-6: DM_HCI_INQUIRY_RESULT Primitive

Description

DM_HCI_INQUIRY_RESULT indicates the result of the inquiry. HCI Inquiry Result is generated asthe inquiry responses are received at the Host Controller.

Parameters

type DM_HCI_INQUIRY_RESULT

result HCI Inquiry Result. Structure containing the result of the inquiry, see below.

num_responsesNumber of inquiry responses contained in this message. Default is 1.


The HCI Inquiry Result structure is as defined in hci.h:

typedef struct{ BD_ADDR_T bd_addr; page_scan_rep_mode_t page_scan_rep_mode; uint8_t page_scan_period_mode; page_scan_mode_t page_scan_mode; uint24_t dev_class;

/* Lower 3 bytes only used */ bt_clock_offset_t clock_offset;} HCI_INQ_RESULT_T;


Device Manager

© 2001 232

8.6.3 DM_HCI_INQUIRY_COMPLETE

typ

e

ph

and

le

stat

us

DM HCI INQUIRY COMPLETE ✔ ✔ ✔

Table 8-7: DM_HCI_INQUIRY_COMPLETE Primitive

Description

Indication of the completion of the inquiry. It is generated as the result of the maximum numberof responses being received, the time period expiring or as a result of an error (indicated usingthe status field).

Parameters

type DM_HCI_INQUIRY_COMPLETE


status 0 indicates success, all other values indicate failure. The error codes aredefined in the Bluetooth HCI specification (www.Bluetooth.com).

Notes

The num_responses parameter has been removed for version 1.1 of the Bluetooth specification.If you are using a version 1.0b compatible host controller it may send this parameter but yourapplication will not be able to see it.



Device Manager

© 2001 233

8.6.4 DM_HCI_INQUIRY_CANCEL

com

mo

n_o

p_c

od

e

DM HCI INQUIRY CANCEL ✔

Table 8-8: DM_HCI_INQUIRY_CANCEL Primitive

Description

Requests the cancellation of an existing inquiry.

Parameters

common_op_code

DM_HCI_INQUIRY_CANCEL

8.6.5 DM_HCI_INQUIRY_CANCEL_COMPLETE

typ

e

ph

and

le

stat

us

DM HCI INQUIRY CANCEL COMPLETE ✔ ✔ ✔

Table 8-9: DM_HCI_INQUIRY_CANCEL_COMPLETE Primitive

Description

Indication of the completion of the inquiry cancel request.

Parameters

type DM_HCI_INQUIRY_CANCEL_COMPLETE


status 0 indicates success, all other values indicate failure. The error codes aredefined in the Bluetooth HCI specification (www.Bluetooth.com).



Device Manager

© 2001 234

8.6.6 DM_HCI_CHANGE_PACKET_TYPE

com

mo

n_o

p_c

od

e

con

nec

tio

n_h

and

le

pac

ket_

typ

e

DM HCI CHANGE PACKET TYPE ✔ ✔ ✔

Table 8-10: DM_HCI_CHANGE_PACKET_TYPE Primitive

Description

Request change of packet type on a SCO connection.

Parameters

common_op_codeDM_HCI_CHANGE_PACKET_TYPE

connection_handle

HCI connection handle for SCO link. This is passed to the application in theDM_SCO_CONNECT_CFM or DM_SCO_CONNECT_IND primitive.

packet_type Packet type for the connection as defined in the Bluetooth specification:

HCI_PKT_HV1 /* SCO only */HCI_PKT_HV2 /* SCO only */HCI_PKT_HV3 /* SCO only */

Notes

With BlueStack, the DM_HCI_CHANGE_PACKET_TYPE primitive is only usable for SCO links.

The packet_type is normally used to denote the allowable packet types; the lower layers makingthe instantaneous choice. For example an SCO connection may wish to exclude HV1 packettypes:

msg_ptr->packet_type = HCI_PKT_HV2 | HCI_PKT_HV3


Device Manager

© 2001 235

8.6.7 DM_HCI_CHANGE_LINK_KEY

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI CHANGE LINK KEY ✔ ✔

Table 8-11: DM_HCI_CHANGE_LINK_KEY Primitive

Description

Change link key for the specified device.

Parameters

common_op_code DM_HCI_CHANGE_LINK_KEY


8.6.8 DM_HCI_MASTER_LINK_KEY

com

mo

n_o

p_c

od

e

Key

_fla

g

DM HCI MASTER LINK KEY ✔ ✔

Table 8-12: DM_HCI_MASTER_LINK_KEY Primitive

Description

Use the master device link keys.

Parameters

common_op_code DM_HCI_MASTER_LINK_KEY

key_flag Semi-permanent or Temporary link key as defined in the Bluetooth HCIspecification.HCI_LINK_KEY_SEMIPERMHCI_LINK_KEY_TEMP


Device Manager

© 2001 236

8.6.9 DM_HCI_REMOTE_NAME_REQUEST

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI REMOTE NAME REQUEST ✔ ✔

Table 8-13: DM_HCI_REMOTE_NAME_REQUEST Primitive

Description

Request the remote (friendly) name of a remote device, which is identified by its BluetoothDevice Address.

Parameters

common_op_code DM_HCI_REMOTE_NAME_REQUEST


8.6.10 DM_HCI_READ_REMOTE_FEATURES

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI READ REMOTE FEATURES ✔ ✔

Table 8-14: DM_HCI_READ_REMOTE_FEATURES Primitive

Description

Read remote features.

Parameters

common_op_code DM_HCI_READ_REMOTE_FEATURES



Device Manager

© 2001 237

8.6.11 DM_HCI_READ_REMOTE_VERSION

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI READ REMOTE VERSION ✔ ✔

Table 8-15: DM_HCI_READ_REMOTE_VERSION Primitive

Description

Read remote version.

Parameters

common_op_code DM_HCI_READ_REMOTE_VERSION


8.6.12 DM_HCI_READ_CLOCK_OFFSET

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI READ CLOCK OFFSET ✔ ✔

Table 8-16: DM_HCI_READ_CLOCK_OFFSET Primitive

Description

Read clock offset.

Parameters

common_op_code DM_HCI_READ_CLOCK_OFFSET



Device Manager

© 2001 238

8.6.13 DM_HCI_REMOTE_NAME_COMPLETE

typ

e

bd

_ad

dr

*nam

e_p

art

ph

and

le

stat

us

DM HCI REMOTE NAME COMPLETE ✔ ✔ ✔ ✔ ✔

Table 8-17: DM_HCI_REMOTE_NAME_COMPLETE Primitive

Description

Notification that the remote name request procedure has been completed. The result of therequest is contained in status. If the status is successful, then the remote name is containedin 4 x 64 byte buffers.

Parameters

type DM_HCI_REMOTE_NAME_COMPLETE

bd_addr Bluetooth Device Address of the remote device

*name_part Array of 4 pointers, each pointing to a 64 byte buffer that contains part of theremote name. NULL pointers are considered as an error.


status 0 indicates success, all other values indicate failure. The error codes aredefined in the Bluetooth HCI specification.


Device Manager

© 2001 239

8.7 Device Manager API Primitives – Link Policy

8.7.1 DM_SET_DEFAULT_LINK_POLICY

typ

e

link_

po

licy_

sett

ing

s_in

link_

po

licy_

sett

ing

s_o

ut

DM_SET_DEFAULT_LINK_POLICY ✔ ✔ ✔

Table 8-18: DM_SET_DEFAULT_LINK_POLICY Primitive

Description

Defines the default Link Manager link policy settings for incoming and outgoing connections.

Parameters

type DM_SET_DEFAULT_LINK_POLICY

link_policy_settings_in Incoming link policy.

link_policy_settings_out Outgoing link policy.

Notes

See section 8.2.3 for a description of the link policy settings available.


Device Manager

© 2001 240

8.7.2 DM_HCI_WRITE_LP_SETTINGS

typ

e

bd

_ad

dr

link_

po

licy_

sett

ing

s

dm

_po

licy

u

DM HCI WRITE LP SETTINGS ✔ ✔ ✔ ✔ ✔

Table 8-19: DM_HCI_WRITE_LP_SETTINGS Primitive

Description

Write link policy settings to Link Manager.

Parameters

type DM_HCI_WRITE_LP_SETTINGS

bd_addr Bluetooth address of remote device to which a link exists.

link_policy_settings Link Manager link policy settings - i.e. hold/sniff/park allowed, asdefined in the Bluetooth HCI specification. These will be sent to theHost Controller via HCI_WRITE_LINK_POLICY_SETTINGS command.Can be set to HCI_LINK_POLICY_NO_CHANGE if the LM link policy isnot to be changed.

dm_policy Device manager link policy settings. The values are:

DM_LINK_POLICY_DEFAULTDM_LINK_POLICY_KEEP_ACTIVEDM_LINK_POLICY_KEEP_SNIFFDM_LINK_POLICY_KEEP_PARKEDDM_LINK_POLICY_TRANSPARENTDM_LINK_POLICY_NO_CHANGE

See section 8.2.3 for a description of these settings.

u A union of parameters for the dm policy settings:

DM_LINK_POLICY_KEEP_SNIFF

max_interval Max sniff interval.

min_interval Min sniff interval.

attempt Sniff attempt.

timeout Sniff timeout.

DM_LINK_POLICY_KEEP_PARKED

max_interval Maximum park interval.

min_interval Minimum park interval.

park_idle_time The amount of time, in microseconds, for which the ACL link should be idlebefore being parked. DM will try to keep the link active until there has beenno ACL data in either direction for this amount of time.


Device Manager

© 2001 241

Notes

Use the bd_addr to identify the (ACL) link at this interface

The LM Link Policy settings, link_policy_settings, can be logically ‘OR’d, for exampleENABLE_MS_SWITCH | ENABLE_HOLD | ENABLE_PARK.

It is the responsibility of the caller to specify compatible LM and DM link policies.

8.7.3 DM_HCI_WRITE_LP_SETTINGS_COMPLETE

typ

e

ph

and

le

stat

us

bd

_ad

dr

DM_HCI_WRITE_LP_SETTINGS_COMPLETE ✔ ✔ ✔ ✔

Table 8-20: DM_HCI_WRITE_LP_SETTINGS_COMPLETE Primitive

Description

Read link policy settings from Link Manager.

Parameters

type DM_HCI_WRITE_LP_SETTINGS_COMPLETE


status HCI success code.

bd_addr Bluetooth address of link.

Notes

Reference: section 8.2.3.


Device Manager

© 2001 242

8.7.4 DM_HCI_READ_LP_SETTINGS

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI READ LP SETTINGS ✔ ✔

Table 8-21: DM_HCI_READ_LP_SETTINGS Primitive

Description


Parameters

common_op_code DM_HCI_READ_LP_SETTINGS


Notes

Use the bd_addr to identify the (ACL) link at this interface

8.7.5 DM_HCI_READ_LP_SETTINGS_COMPLETE

typ

e

ph

and

le

stat

us

bd

_ad

dr

link_

po

licy

DM_HCI_READ_LP_SETTINGS_COMPLETE ✔ ✔ ✔ ✔ ✔

Table 8-22: DM_HCI_READ_LP_SETTINGS_COMPLETE Primitive

Description


Parameters

type DM_HCI_WRITE_LP_SETTINGS_COMPLETE


status HCI success code.


link_policy LM link policy settings.

Notes



Device Manager

© 2001 243

8.7.6 DM_HCI_PARK_MODE

com

mo

n_o

p_c

od

e

bd

_ad

dr

max

_in

terv

al

min

_in

terv

al

DM HCI PARK MODE ✔ ✔ ✔ ✔

Table 8-23: DM_HCI_PARK_MODE Primitive

Description

This command requests the Link Manager to place the baseband connection associated withthe specified bd_addr into Park mode.

Parameters

common_op_code DM_HCI_PARK_MODE

bd_addr Bluetooth Device Address of remote device.

max_interval Maximum time between consecutive beacons in 0.625ms increments.

min_interval Minimum time between consecutive beacons in 0.625ms increments.

Notes

The Interval command parameters specify the acceptable length of the interval betweenbeacons. However, the remote device may request a shorter interval. The Max_Intervalparameter specifies the acceptable longest length of the interval between beacons. TheMin_Interval parameter specifies the acceptable shortest length of the interval betweenbeacons. The Beacon Min Interval cannot be greater than the Beacon Max Interval.



Device Manager

© 2001 244

8.7.7 DM_HCI_EXIT_PARK_MODE

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI EXIT PARK MODE ✔ ✔

Table 8-24: DM_HCI_EXIT_PARK_MODE Primitive

Description

Exit park mode for the baseband link to the device identified by bd_addr.

Parameters

common_op_code DM_HCI_EXIT_PARK_MODE

bd_addr Bluetooth Device Address of remote device.

Notes



Device Manager

© 2001 245

8.7.8 DM_HCI_HOLD_MODE

com

mo

n_o

p_c

od

e

bd

_ad

dr

max

_in

terv

al

min

_in

terv

al

DM HCI HOLD MODE ✔ ✔ ✔ ✔

Table 8-25: DM_HCI_HOLD_MODE Primitive

Description

This command is used to request the Link Manager to place the ACL baseband connectionassociated with the remote device, identified by specified bd_addr, into hold mode. TheMax_Interval and Min_Interval command parameters specify the length of time the Host wantsto put the connection into the hold mode. The local and remote devices will negotiate the lengthof time to spend in hold mode.

Parameters

common_op_code DM_HCI_HOLD_MODE


max_interval Maximum length of hold time in 0.625ms increments.

min_interval Minimum length of hold time in 0.625ms increments.

Notes



Device Manager

© 2001 246

8.7.9 DM_HCI_SNIFF_MODE

com

mo

n_o

p_c

od

e

bd

_ad

dr

max

_in

terv

al

min

_in

terv

al

atte

mp

t

tim

eou

t

DM HCI SNIFF MODE ✔ ✔ ✔ ✔ ✔ ✔

Table 8-26: DM_HCI_SNIFF_MODE Primitive

Description

This command is used to request the Link Manager to place the ACL baseband connectionassociated with the remote device, identified by specified bd_addr, into sniff mode.

Parameters

common_op_code DM_HCI_SNIFF_MODE


max_interval Maximum acceptable period between sniffs in 0.625ms increments.

min_interval Minimum acceptable period between sniffs in 0.625ms increments.

attempt Number of slots for sniff attempt in 0.625ms increments.

timeout Number of slots before timeout for sniff attempt in 0.625ms increments.

Notes


SCO connections cannot be put into sniff mode.


Device Manager

© 2001 247

8.7.10 DM_HCI_EXIT_SNIFF_MODE

com

mo

n_o

p_c

od

e

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI EXIT SNIFF MODE ✔ ✔ ✔

Table 8-27: DM_HCI_EXIT_SNIFF_MODE Primitive

Description

End sniff mode for the connection to the remote device identified by bd_addr.

Parameters

common_op_code DM_HCI_EXIT_SNIFF_MODE


Notes



Device Manager

© 2001 248

8.7.11 DM_HCI_ROLE_DISCOVERY

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI ROLE DISCOVERY ✔ ✔

Table 8-28: DM_HCI_ROLE_DISCOVERY Primitive

Description

Discover the role (master/slave) of a Bluetooth device.

Parameters

common_op_code DM_HCI_ROLE_DISCOVERY


8.7.12 DM_HCI_SWITCH_ROLE

com

mo

n_o

p_c

od

e

bd

_ad

dr

role

DM HCI SWITCH ROLE ✔ ✔ ✔

Table 8-29: DM_HCI_SWITCH_ROLE Primitive

Description

Switch the role (master/slave) of a Bluetooth device.

Parameters

common_op_code DM_HCI_SWITCH_ROLE


role MASTER or SLAVE


Device Manager

© 2001 249

8.8 Device Manager API Primitives – Host Controller and Baseband

8.8.1 DM_HCI_CHANGE_LOCAL_NAME

com

mo

n_o

p_c

od

e

*nam

e_p

art

DM HCI CHANGE LOCAL NAME ✔ ✔

Table 8-30: DM_HCI_CHANGE_LOCAL_NAME Primitive

Description

Change the name of the local device (assumed local Bluetooth Device Address).

Parameters

common_op_code

DM_HCI_CHANGE_LOCAL_NAME

*name_part Array of 4 pointers, each pointing to a 64 byte buffer that contains part of theremote name. Cannot be NULL.

8.8.2 DM_HCI_CHANGE_LOCAL_NAME_COMPLETE

typ

e

ph

and

le

stat

us

DM HCI CHANGE LOCAL NAME COMPLETE ✔ ✔ ✔

Table 8-31: DM_HCI_CHANGE_LOCAL_NAME_COMPLETE Primitive

Description

Indication of the success or otherwise of a previous change local name request.

Parameters

type DM_HCI_CHANGE_LOCAL_NAME_COMPLETE




Device Manager

© 2001 250

8.8.3 DM_HCI_WRITE_SCAN_ENABLE

com

mo

n_o

p_c

od

e

scan

_en

able

DM HCI WRITE SCAN ENABLE ✔ ✔

Table 8-32: DM_HCI_WRITE_SCAN_ENABLE Primitive

Description

Writes the scan_enable parameter to the Host Controller. The selection of the value of thescan_enable parameter controls the scan mode that the local Bluetooth device is in.

Parameters

common_op_code

DM_HCI_WRITE_SCAN_ENABLE

scan_enable Scan mode of the local deviceHCI_SCAN_ENABLE_OFFHCI_SCAN_ENABLE_INQHCI_SCAN_ENABLE_PAGE

HCI_SCAN_ENABLE_INQ_AND_PAGE.


Device Manager

© 2001 251

8.8.4 DM_HCI_WRITE_CURRENT_IAC_LAP

com

mo

n_o

p_c

od

e

nu

m_c

urr

ent_

IAC

*IA

C_L

AP

[]

DM HCI WRITE CURRENT IAC LAP ✔ ✔ ✔

Table 8-33: DM_HCI_WRITE_CURRENT_IAC_LAP Primitive

Description

Writes the current

Parameters

common_op_code

DM_HCI_WRITE_CURRENT_IAC_LAP

num_current_IAC

Specifies the number of IACs that the Bluetooth device should simultaneouslyscan for. See Notes.

*IAC_LAP[] Pointer to an array of IAC LAP values

Notes

The number of current IACs that the local device can support should be determined using theHCI_Read_Number_Of_Supported_IAC command.


Device Manager

© 2001 252

8.8.5 DM_HCI_FLUSH

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI FLUSH ✔ ✔

Table 8-34: DM_HCI_FLUSH Primitive

Description

Request to discard all data that is currently in the transmit buffers awaiting transmission.

Parameters

common_op_code

DM_HCI_FLUSH


8.8.6 DM_HCI_READ_AUTO_FLUSH_TIMEOUT

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI READ AUTO FLUSH TIMEOUT ✔ ✔

Table 8-35: DM_HCI_READ_AUTO_FLUSH_TIMEOUT Primitive

Description

Request for reading the automatic flush timeout.

Parameters

common_op_code

DM_HCI_READ_AUTO_FLUSH_TIMEOUT



Device Manager

© 2001 253

8.8.7 DM_HCI_WRITE_AUTO_FLUSH_TIMEOUT

com

mo

n_o

p_c

od

e

bd

_ad

dr

Flu

shT

imeo

ut

DM HCI WRITE AUTO FLUSH TIMEOUT ✔ ✔ ✔

Table 8-36: DM_HCI WRITE_AUTO_FLUSH_TIMEOUT Primitive

Description

Request to write the automatic flush timeout value.

Parameters

common_op_code

DM_HCI_WRITE_AUTO_FLUSH_TIMEOUT

bd_addr Bluetooth address of the remote device that the connection to the auto flush willapply to.

FlushTimeout 11 bit value, 0.625ms increments.


Device Manager

© 2001 254

8.8.8 DM_HCI_READ_TX_POWER_LEVEL

com

mo

n_o

p_c

od

e

bd

_ad

dr

leve

l_ty

pe

DM HCI READ TX POWER LEVEL ✔ ✔ ✔

Table 8-37: DM_HCI_READ_TX_POWER_LEVEL Primitive

Description

Read the transmit power level of the local device for the link to the specified remote device.

Parameters

common_op_code

DM_HCI_READ_TX_POWER_LEVEL

bd_addr Bluetooth address of remote device.

level_type Read the current or the maximum power level as defined in the Bluetooth HCIspecification.HCI_READ_CURRENT_TX_POWERHCI_READ_MAX_TX_POWER


Device Manager

© 2001 255

8.8.9 DM_HCI_READ_SCO_FLOW_CONTROL_ENABLE

com

mo

n_o

p_c

od

e

DM HCI READ SCO FLOW CONTROL ENABLE ✔

Table 8-38: DM_HCI_READ_SCO_FLOW_CONTROL_ENABLE Primitive

Description

Request to read the SCO link Flow Control settings

Parameters

common_op_code

DM_HCI_READ_SCO_FLOW_CONTROL_ENABLE

8.8.10 DM_HCI_WRITE_SCO_FLOW_CONTROL_ENABLE

com

mo

n_o

p_c

od

e

SC

OF

low

Co

ntr

olE

nab

le

DM HCI WRITE SCO FLOW CONTROL ENABLE ✔ ✔

Table 8-39: DM_HCI_WRITE_SCO_FLOW_CONTROL_ENABLE Primitive

Description

Request to write the SCO link Flow Control setting

Parameters

common_op_code

DM_HCI_WRITE_SCO_FLOW_CONTROL_ENABLE

SCOFlowControlEnableValue 1 to enable , 0 to disable as defined in the Bluetooth HCI specification.HCI_SCO_FLOW_CONTROL_DISABLEDHCI_SCO_FLOW_CONTROL_ENABLED


Device Manager

© 2001 256

8.8.11 DM_HCI_READ_LINK_SUPERV_TIMEOUT

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI READ LINK SUPERV TIMEOUT ✔ ✔

Table 8-40: DM_HCI_READ_LINK_SUPERV_TIMEOUT Primitive

Description

Read the link supervision timeout.

Parameters

common_op_code

DM_HCI_READ_LINK_SUPERV_TIMEOUT


8.8.12 DM_HCI_WRITE_LINK_SUPERV_TIMEOUT

com

mo

n_o

p_c

od

e

bd

_ad

dr

tim

eou

t

DM HCI WRITE LINK SUPERV TIMEOUT ✔ ✔ ✔

Table 8-41: DM_HCI_WRITE_LINK_SUPERV_TIMEOUT Primitive

Description

Write the link supervision timeout value.

Parameters

common_op_code

DM_HCI_WRITE_LINK_SUPERV_TIMEOUT


timeout Timeout in increments of 0.625ms, 0 for no timeout.


Device Manager

© 2001 257

8.9 Device Manager API Primitives – Status Parameters

8.9.1 DM_HCI_FAILED_CONTACT_COUNTER

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI FAILED CONTACT COUNTER ✔ ✔

Table 8-42: DM_HCI_FAILED_CONTACT_COUNTER Primitive

Description

Read Failed Contact counter.

Parameters

common_op_code

DM_HCI_FAILED_CONTACT_COUNTER


8.9.2 DM_HCI_RESET_CONTACT_COUNTER

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI RESET CONTACT COUNTER ✔ ✔

Table 8-43: DM_HCI_RESET_CONTACT_COUNTER Primitive

Description

Reset the Failed Contact counter.

Parameters

common_op_code

DM_HCI_RESET_CONTACT_COUNTER



Device Manager

© 2001 258

8.9.3 DM_HCI_GET_LINK_QUALITY

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI GET LINK QUALITY ✔ ✔

Table 8-44: DM_HCI_GET_LINK_QUALITY Primitive

Description

Request to get the link quality parameter.

Parameters

common_op_code

DM_HCI_ GET_LINK_QUALITY


8.9.4 DM_HCI_READ_RSSI

com

mo

n_o

p_c

od

e

bd

_ad

dr

DM HCI READ RSSI ✔ ✔

Table 8-45: DM_HCI_READ_RSSI Primitive

Description

Request to read the link RSSI value.

Parameters

common_op_code

DM_HCI_READ_RSSI



Device Manager

© 2001 259

8.10 Device Manager API Primitives – SCO Control Related

8.10.1 DM_SCO_INCOMING_REGISTER

typ

e

ph

and

le

pv_

cbar

g

DM SCO INCOMING REGISTER REQ ✔ ✔ ✔

Table 8-46: DM_SCO_INCOMING_REGISTER primitive

Description

Register request to SCO interface, registering a task that has an interest in incoming SCOconnections. Multiple tasks may register with the DM as SCO incoming tasks, and the DM willthen inform each registered task of any incoming SCO connections.

Parameters

type DM_SCO_INCOMING_REGISTER_REQ

phandle Protocol handle of higher entity.

pv_cbarg The ’pv_cbarg’ is an opaque value which the DM will copy into all upstreamSCO primitives sent to the registered task - the meaning of the value isdetermined by the task. This allows a single task to register multiple times,supplying a different value of ’pv_cbarg’ each time which can perhaps be usedfor discrimination between multiple entities within the task.


Device Manager

© 2001 260

8.10.2 DM_SCO_INCOMING_UNREGISTER

typ

e

ph

and

le

pv_

cbar

g

DM SCO INCOMING UNREGISTER REQ ✔ ✔ ✔

Table 8-47: DM_SCO_INCOMING_UNREGISTER primitive

Description

Request to unregister an incoming SCO handler. DM will no longer issueDM_SCO_CONNECT_IND primitives to this handler. In the case where the unregister requestcollides with a DM_SCO_CONNECT_IND, the task is still expected to respond with aDM_SCO_CONNECT_RES.

Parameters

type DM_SCO_INCOMING_UNREGISTER_REQ


pv_cbarg Application defined parameter. See DM_SCO_INCOMING_REGISTER fordetails.


Device Manager

© 2001 261

8.10.3 DM_SCO_CONNECT

typ

e

bd

_ad

dr

pac

ket_

typ

e

enc_

mo

de

han

dle

acce

pt

lm_s

co_h

and

le

pv_

cbar

g

ph

and

le

stat

us

DM SCO CONNECT REQ ✔ ✔ ✔ ✔

DM SCO CONNECT RES ✔ ✔ ✔

DM SCO CONNECT IND ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

DM SCO CONNECT CFM ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 8-48: DM_SCO_CONNECT Primitive

Description

Requests the establishment of a SCO connection.

Parameters

type DM_SCO_CONNECT_REQDM_SCO_CONNECT_RESDM_SCO_CONNECT_INDDM_SCO_CONNECT_CFM


packet_type Packet type for the connection as defined in the Bluetooth specification. Thefollowing are defined for SCO:HCI_PKT_HV1 /* SCO only */HCI_PKT_HV2 /* SCO only */HCI_PKT_HV3 /* SCO only */

enc_mode Encryption mode.

handle The HCI connection handle.


lm_sco_handleSCO handle as supplied by the Link Manager, orHCI_LM_SCO_HANDLE_INVALID if unknown. Used to discriminate between SCOconnections when there are multiple SCO connections between two Bluetoothdevices.

accept Set TRUE to accept the connection request, FALSE to reject.



Notes

The SCO connection is added to an already existing ACL connection. Therefore the higherlayer SCO Control entity must ensure that an ACL connection has been established.


Device Manager

© 2001 262

8.10.4 DM_SCO_DISCONNECT

typ

e

han

dle

pv_

cbar

g

ph

and

le

reas

on

stat

us

DM SCO DISCONNECT REQ ✔ ✔ ✔

DM SCO DISCONNECT IND ✔ ✔ ✔ ✔ ✔ ✔

Table 8-49: DM_SCO_DISCONNECT Primitives

Description

Requests the disconnection of a SCO connection.

Parameters

type DM_SCO_DISCONNECT_REQDM_SCO_DISCONNECT_IND

handle HCI connection handle.



reason Reason for disconnection. The valid values are defined in the Bluetooth HCIspecification.


Notes

The disconnection of a SCO link does not force the disconnection of the associated ACLconnection.


Device Manager

© 2001 263

8.10.5 DM_SCO_BUFFER_SIZE

typ

e

max

_nu

m_p

acke

ts

ph

and

le

size

DM SCO BUFFER SIZE IND ✔ ✔ ✔ ✔

Table 8-50: DM_SCO_BUFFER_SIZE Primitive

Description

An indication of Host Controller buffer size for SCO. This is sent once only on start-up or onreset.

Parameters

type DM_SCO_BUFFER_SIZE_IND

max_num_packets

Maximum number of SCO packets of the specified size (size) that can bebuffered on the host controller.


size Maximum size of a single SCO packet.

Notes

The host should not send more than max_num_packets before asserting flow control locally.For SCO it may be acceptable to discard packets if flow control is asserted.

Device Manager does not forward this message unless there is a SCO control entity registeredwith Device Manager.


Device Manager

© 2001 264

8.10.6 DM_SCO_ DATA_SENT

typ

e

hci

_co

nn

ecti

on

_han

dle

nu

m_c

om

ple

ted

ph

and

le

DM SCO DATA SENT IND ✔ ✔ ✔ ✔

Table 8-51: DM_SCO_DATA_SENT Primitive

Description

Data sent indication for each SCO Interface. Sent upon receivinghci_number_completed_packets event - one such primitive is sent for each SCO connection inthe HCI event.

Parameters

type DM_SCO_DATA_SENT_IND

hci_connection_handle

Handle identifying the SCO link

num_complete Number of packets successfully transmitted.


Notes

This is used by the SCO control application as confirmation that the SCO packets have beensuccessfully transmitted from the host controller. The primitive contains details of the number ofpackets that have been transmitted.


Device Manager

© 2001 265

8.11 Device Manager API Primitives – Security Manager Related

8.11.1 DM_SM_PIN_REQUEST

typ

e

bd

_ad

dr

ph

and

le

pin

[]

pin

_len

gth

DM SM PIN REQUEST RES ✔ ✔ ✔ ✔

DM SM PIN REQUEST IND ✔ ✔ ✔

Table 8-52: DM_SM_PIN_REQUEST Primitive

Description

The indication of a request for a PIN code. DM_SM_PIN_REQUEST_RES is the response tothe PIN code request.

Parameters

type DM_SM_PIN_REQUEST_RESDM_SM_PIN_REQUEST_IND



pin[] Array containing the PIN. This has a maximum size ofHCI_MAX_PIN_LENGTH.

pin_length

Length of the PIN in bytes (1 to HCI_MAX_PIN_LENGTH).The pin_length is set to 0 to reject the request


Device Manager

© 2001 266

8.11.2 DM_SM_LINK_KEY_REQUEST

typ

e

bd

_ad

dr

ph

and

le

key[

]

valid

DM SM LINK KEY REQUEST RES ✔ ✔ ✔ ✔

DM SM LINK KEY REQUEST IND ✔ ✔ ✔

Table 8-53: DM_SM_LINK_KEY_REQUEST Primitive

Description

The indication of a request for a Link Key. DM_SM_LINK_KEY_REQUEST_RES is theresponse to the Link Key request.

type DM_SM_LINK_KEY_REQUEST_RESDM_SM LINK_KEY_REQUEST_IND



key[] Array containing the Link Key. This has a size of SIZE_LINK_KEY.

valid TRUE if Link Key validFALSE if Link Key not valid


Device Manager

© 2001 267

8.11.3 DM_SM_SET_DEFAULT_SECURITY

typ

e

secl

_def

ault

DM SM SET DEFAULT SECURITY REQ ✔ ✔

Table 8-54: DM_SM_SET_DEFAULT_SECURITY Primitives

Description

Sets the default security level to be applied in security modes 2 and 3 in cases where a servicehas not been registered with the Security Manager. The "default" default security level isdefined by SECL_DEFAULT, and using this primitive overrides SECL_DEFAULT.

Parameters

type DM_SET_DEFAULT_SECURITY_REQ

secl_default New default security level. Can take one of the following values:SECL_NONESECL_IN_AUTHORISATIONSECL_IN_AUTHENTICATIONSECL_IN_ENCRYPTIONSECL_OUT_AUTHORISATIONSECL_OUT_AUTHENTICATIONSECL_OUT_ENCRYPTIONSECL_IN_CONNECTIONLESS


Device Manager

© 2001 268

8.11.4 DM_SM_REGISTER

typ

e

pro

toco

l_id

chan

nel

ou

tgo

ing

_ok

secu

rity

_lev

el

psm

DM SM REGISTER REQ ✔ ✔ ✔ ✔ ✔ ✔

Table 8-55: DM_SM_REGISTER Primitives

Description

Registers the security requirements for access to a service or a multiplexing protocol layerwhen the Security Manager is in security mode 2 or 3. The registered security level is applied toall incoming connections on the specified ’channel’, and optionally to all outgoing connectionson that channel if ’outgoing_ok’ is TRUE.

Parameters

type DM_SM_REGISTER_REQ

protocol_id Protocol at which security is to be applied.SEC_PROTOCOL_L2CAPSEC_PROTOCOL_RFCOMMSEC_PROTOCOL_USER

channel Channel for the protocol defined by the protocol_id (e.g. RFCOMM serverchannel number)

outgoing_ok Flag indicating whether the security level of the outgoing connections from thisapplication are subject to the same security level as registered here. (Thesecurity level always applies to incoming connections) This is set TRUE if thisregistration applies to outgoing connections in addition to incomingconnections.

See also DM_SM_REGISTER_OUTGOING.

security_level Level of security to be applied. Can take one of the following values:SECL_NONESECL_IN_AUTHORISATIONSECL_IN_AUTHENTICATIONSECL_IN_ENCRYPTIONSECL_OUT_AUTHORISATIONSECL_OUT_AUTHENTICATIONSECL_OUT_ENCRYPTIONSECL_IN_CONNECTIONLESS

psm The L2CAP PSM number is required if connectionless security is used. If thereis a conflict, where multiple services based on the same PSM have differentconnectionless security requirements, then connectionless reception will be


Device Manager

© 2001 269

disabled for that PSM. If connectionless security does not matter, set ’psm’ tozero.

Notes

The user can extend the protocol_id fields in the file dm_prim.h should more than oneapplication layer identifier be required.

8.11.5 DM_SM_REGISTER_OUTGOING

typ

e

bd

_ad

dr

pro

toco

l_id

rem

ote

_ch

ann

el

ou

tgo

ing

_sec

uri

ty_l

evel p

sm

DM SM REGISTER OUTGOING REQ ✔ ✔ ✔ ✔ ✔ ✔

Table 8-56: DM_SM_REGISTER_OUTGOING_REQ Primitives

Description

Registers the security requirements for outgoing connections to the specified protocol andchannel on the specified remote device. This is typically used to control security whenconnecting to a remote RFCOMM server channel.

Parameters

type DM_SM_REGISTER_OUTGOING_REQ


protocol_id Protocol at which security is to be applied.SEC_PROTOCOL_L2CAPSEC_PROTOCOL_RFCOMMSEC_PROTOCOL_USER

remote_channelRemote channel for the protocol defined by the protocol_id (e.g. RFCOMMserver channel number)

outgoing_security_level Level of security to be applied. Can take one of the followingvalues:SECL_NONESECL_IN_AUTHORISATIONSECL_IN_AUTHENTICATIONSECL_IN_ENCRYPTIONSECL_OUT_AUTHORISATIONSECL_OUT_AUTHENTICATIONSECL_OUT_ENCRYPTIONSECL_IN_CONNECTIONLESS

psm The L2CAP PSM number is required if connectionless security is used. If thereis a conflict, where multiple services based on the same PSM have different


Device Manager

© 2001 270

connectionless security requirements, then connectionless reception will bedisabled for that PSM. If connectionless security does not matter, set ’psm’ tozero.

Notes

The user can extend the protocol_id fields in the file dm_prim.h should more than oneapplication layer identifier be required.

If the same security level is to be applied for both incoming and outgoing connections, then theprimitive DM_SM_REGISTER_REQ should be used, with the parameter outgoing_ok set toTRUE. That is, it is not necessary to have to use both DM_SM_REGISTER_REQ andDM_SM_REGISTER_OUTGOING where the security level is identical.

8.11.6 DM_SM_UNREGISTER

typ

e

pro

toco

l_id

chan

nel

DM SM UNREGISTER REQ ✔ ✔ ✔

Table 8-57: DM_SM_UNREGISTER Primitives

Description

Unregisters the security requirements for a service previously registered withDM_SM_REGISTER_REQ.

Parameters

type DM_SM_UNREGISTER_REQ

protocol_id Identity of previously registered protocol that is to be unregistered.SEC_PROTOCOL_L2CAPSEC_PROTOCOL_RFCOMMSEC_PROTOCOL_USER

channel Channel for the protocol defined by the protocol_id (e.g. RFCOMM serverchannel number)

Notes

See also DM_SM_UNREGISTER_OUTGOING_REQ.


Device Manager

© 2001 271

8.11.7 DM_SM_UNREGISTER_OUTGOING

typ

e

bd

_ad

dr

pro

toco

l_id

rem

ote

_ch

ann

el

DM SM UNREGISTER OUTGOING REQ ✔ ✔ ✔ ✔

Table 8-58: DM_SM_UNREGISTER_OUTGOING Primitives

Description

Unregisters the security requirements for a service previously registered withDM_SM_REGISTER_OUTGOING_REQ.

Parameters

type DM_SM_UNREGISTER_OUTGOING_REQ


protocol_id Identity of previously registered protocol that is to be unregistered.SEC_PROTOCOL_L2CAPSEC_PROTOCOL_RFCOMMSEC_PROTOCOL_USER

remote_channelRemote channel for the protocol defined by the protocol_id (e.g. RFCOMMserver channel number)

Notes

See also DM_SM_UNREGISTER_REQ.


Device Manager

© 2001 272

8.11.8 DM_SM_ACCESS

typ

e

bd

_ad

dr

ph

and

le

chan

nel

prt

oo

col_

id

inco

min

g

gra

nte

d

pv_

con

text

n_c

on

text

DM SM ACCESS REQ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

DM SM ACCESS CFM ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

Table 8-59: DM_SM_ACCESS Primitives

Description

Request from a protocol layer (e.g. L2CAP, RFCOMM, or a higher layer) to determine if theremote device ’bd_addr’ is to be granted access to that protocol layer’s channel. The SecurityManager will search its service and device databases, may perform some security procedures,and may request authorisation from the application. The result is returned in aDM_SM_ACCESS_CFM primitive.

Parameters

type DM_SM_ACCESS_REQDM_SM_ACCESS_CFM


protocol_id Identity of the protocol that is requesting access.SEC_PROTOCOL_L2CAPSEC_PROTOCOL_RFCOMMSEC_PROTOCOL_USER

channel Channel for the protocol defined by the protocol_id that the access is beingrequested on (e.g. RFCOMM server channel number)


incoming Direction of connection request.TRUE for incoming connection requestFALSE for outgoing connection request

granted Whether the access request is granted or refused.TRUE for grantedFALSE for refused

pv_context Data supplied by the user application to determine the context. If only one userapplication can be NULL.

n_context Data supplied by the user application to determine the context. If only one userapplication can be NULL.

Notes


Device Manager

© 2001 273

8.11.9 DM_SM_SET_SEC_MODE_REQ

typ

e

ph

and

le

mo

de

mo

de3

_en

c

succ

ess

DM SM SET SEC MODE REQ ✔ ✔ ✔

DM SM SET SEC MODE CFM ✔ ✔ ✔ ✔ ✔

Table 8-60: DM_SM_SET_SEC_MODE Primitives

Description

Request to place the security manager into the specified security mode. The result is returnedin a DM_SM_SET_SEC_MODE_CFM primitive.

Parameters

type DM_SM_SET_SEC_MODE_REQDM_SM_SET_SEC_MODE_CFM

phandle Protocol handle of higher entity .

mode Security mode. Can take one of the following values:SEC_MODE0_OFFSEC_MODE1_NON_SECURESEC_MODE2_SERVICESEC_MODE3_LINK

mode3_enc Encryption level for mode 3. One of:HCI_ENC_MODE_OFFHCI_ENC_MODE_PT_TO_PTHCI_ENC_MODE_PT_TO_PT_AND_BCAST

success Result of the request.TRUE if the requested security mode has been activated.FALSE if the request is unsuccessful

Notes

It is recommended that the security mode be changed only when the system is not in theprocess of creating or accepting any new connections.


Device Manager

© 2001 274

8.11.10 DM_SM_ADD_DEVICE_REQ

typ

e

ph

and

le

bd

_ad

dr

up

dat

e_tr

ust

_lev

el

tru

sted

up

dat

e_lin

k_ke

y

link_

key

succ

ess

DM SM ADD DEVICE REQ ✔ ✔ ✔ ✔ ✔ ✔

DM SM ADD DEVICE CFM ✔ ✔ ✔

Table 8-61: DM_SM_ADD_DEVICE Primitives

Description

Request to add a device to the Security Manager’s device database, or to modify the record foran existing entry. The operation will be confirmed in a DM_SM_ADD_DEVICE_CFM primitive.

Parameters

type DM_SM_ADD_DEVICE_REQDM_SM_ADD_DEVICE_CFM

bd_addr Bluetooth device address of remote device.


update_trust_levelThe trust level is changed to ’trusted’ if ’update_trust_level’ is TRUE.

trusted The trust level of the remote device, TRUE = trusted, FALSE = untrusted.

update_link_key Whether the link key is to be overwrittenTRUE overwrite link keyFALSE do not overwrite link key

link_key The new link key, for when update_link_key is set TRUE.

success Result of the request.TRUE if the request is successful.FALSE if the request is unsuccessful

Notes

The update_link_key flag can be used where an update of trust level is being made without anew link key having been derived. In this case the update_link_key flag is set to FALSE.


Device Manager

© 2001 275

8.11.11 DM_SM_REMOVE_DEVICE

typ

e

bd

_ad

dr

ph

and

le

succ

ess

DM SM REMOVE DEVICE REQ ✔ ✔

DM SM REMOVE DEVICE CFM ✔ ✔ ✔ ✔

Table 8-62: DM_SM_REMOVE_DEVICE Primitives

Description

Request to remove a device from the Security Manager’s device database. The operation willbe confirmed in a DM_SM_REMOVE_DEVICE_CFM primitive.

Parameters

type DM_SM_REMOVE_DEVICE_REQDM_SM_REMOVE_DEVICE_CFM

bd_addr Bluetooth device address of remote device to be removed from the devicedatabase.


success Result of the request.TRUE if the request is successful.FALSE if the request is unsuccessful

Notes


Device Manager

© 2001 276

8.11.12 DM_SM_AUTHORISE

typ

e

bd

_ad

dr

ph

and

le

pro

toco

l_id

chan

nel

inco

min

g

auth

ori

sed

DM SM AUTHORISE RES ✔ ✔ ✔ ✔ ✔ ✔

DM SM AUTHORISE IND ✔ ✔ ✔ ✔ ✔ ✔

Table 8-63: DM_SM_AUTHORISE Primitive

Description

A request for authorisation from the Security Manager to the application. This is only performedwhen an untrusted or unknown device is attempting to access a service that requiresauthorisation in security mode 2.

The application must make a decision and then respond with a DM_SM_AUTHORISE_RESprimitive containing the result. Devices can be marked as trusted using theDM_SM_ADD_DEVICE_REQ primitive.

Parameters

type DM_SM_AUTHORISE_RESDM_SM_AUTHORISE_IND


protocol_id Identity of the protocol to which access is being requested.SEC_PROTOCOL_L2CAPSEC_PROTOCOL_RFCOMMSEC_PROTOCOL_USER

channel Channel for the protocol defined by the protocol_id that the access is beingrequested on (e.g. RFCOMM server channel number)


incoming Direction of connection request.TRUE for incoming connection requestFALSE for outgoing connection request

authorised Whether the authorisation is granted or refused.TRUE for grantedFALSE for refused


Device Manager

© 2001 277

8.11.13 DM_SM_AUTHENTICATE

typ

e

bd

_ad

dr

ph

and

le

succ

ess

DM SM AUTHENTICATE REQ ✔ ✔

DM SM AUTHENTICATE CFM ✔ ✔ ✔ ✔

Table 8-64: DM_AUTHENTICATE Primitive

Description

The DM_SM_AUTHENTICATE_REQ primitive can be used by the application (or applicationmanager) to authenticate a remote device. If the device has already been authenticated, theSecurity Manager responds immediately, otherwise it performs the HCI authenticationprocedure, which may involve pairing.

Parameters

type DM_SM_AUTHENTICATE_REQDM_SM_AUTHENTICATE_CFM



success Whether the authentication was successful.TRUE for successFALSE for failure

Notes

This request will be rejected in security mode 1.


Device Manager

© 2001 278

8.11.14 DM_SM_ENCRYPT

typ

e

bd

_ad

dr

ph

and

le

encr

ypt

succ

ess

encr

ypte

d

DM SM ENCRYPT REQ ✔ ✔ ✔

DM SM ENCRYPT CFM ✔ ✔ ✔ ✔ ✔

Table 8-65: DM_SM_ENCRYPT Primitive

Description

The DM_SM_ENCRYPT_REQ primitive can be used by the applications (or applicationmanager) to request encryption activation or encryption de-activation of a link at any time,. If thelink encryption is already in the requested state, the Security Manager responds immediately,otherwise it performs the relevant HCI procedure.

The link must have been authenticated before encryption is allowed.

Parameters

type DM_SM_ENCRYPT_REQDM_SM_ENCRYPT_CFM



encrypt Activate encryptionTRUE to activateFALSE to deactivate

success Whether the encryption was successful.TRUE for successFALSE for failure

encrypted Status of the link encryptionTRUE for encyrptedFALSE for clear (no encryption)

Notes

This request will be rejected in security mode 1.


Device Manager

© 2001 279

8.11.15 DM_SM_ENCRYPTION_CHANGE

typ

e

bd

_ad

dr

ph

and

le

encr

ypte

d

DM SM ENCRYPTION CHANGE ✔ ✔ ✔ ✔

Table 8-66: DM_SM_ENCRYPTION_CHANGE Primitive

Description

Notification of a possible change in the encryption status of a link due to a peer-initiatedencryption procedure.

Parameters

type DM_SM_ENCRYPTION_CHANGE



encrypted Status of the link encryptionTRUE for encryptedFALSE for clear (no encryption)


Device Manager

© 2001 280

8.12 ACL link management and monitoring

8.12.1 DM_ACL_OPEN

typ

e

ph

and

le

bd

_ad

dr

succ

ess

DM_ACL_OPEN_REQ ✔ ✔

DM_ACL_OPEN_CFM ✔ ✔ ✔ ✔

Table 8-67: DM_ACL_OPEN Primitives

Description

Request from an application task for the DM to create an ACL to the specified remote device.This might be used for pairing, for example. The DM allows both L2CAP and the application torequest ACLs. L2CAP uses the DM_ACLQUEUE interface primitives(DM_ACL_CONNECT_REQ / CFM), and the application uses the DM_IFACEQUEUE primitives(DM_ACL_OPEN_REQ/CFM). The DM keeps track of who has an interest in each ACL, andwill only disconnect the ACL when all interested parties have released the ACL (byDM_ACL_DISCONNECT_REQ and DM_ACL_CLOSE_REQ).

DM_ACL_OPEN_REQ registers the application’s interest in the ACL. DM will create the link if itdoes not already exist. DM will always respond with DM_ACL_OPEN_CFM, indicating successor failure. If successful, the application may subsequently call DM_ACL_CLOSE_REQ torelinquish its interest in the ACL - DM will then release the link if L2CAP is not using it.

The DM keeps the application informed of the state of all ACLs via the DM_ACL_OPENED_INDand DM_ACL_CLOSED_IND primitives. Note that there is no specific response toDM_ACL_CLOSE_REQ, as the DM_ACL_CLOSED_IND is only issued when all users of theACL have released it.

Parameters

type DM_ACL_OPEN_REQ

DM_ACL_OPEN_CFM



success HCI success code.


Device Manager

© 2001 281

8.12.2 DM_ACL_OPENED_IND

typ

e

ph

and

le

bd

_ad

dr

inco

min

g

dev

_cla

ss

DM_ACL_OPENED_IND ✔ ✔ ✔ ✔ ✔

Table 8-68: DM_ACL_OPENED_IND Primitive

Description

This primitive is issued to the application interface whenever an ACL is successfully established(incoming or outgoing).

Parameters

type DM_ACL_OPENED_IND



incoming Flag indicating peer-initiated ACL (TRUE) or locally-initiated (FALSE).

dev_class Class of device for peer, valid for incoming connections only.

8.12.3 DM_ACL_CLOSED_IND

typ

e

ph

and

le

bd

_ad

dr

DM_ACL_CLOSED_IND ✔ ✔ ✔

Table 8-69: DM_ACL_CLOSED_IND Primitive

Description

This primitive is issued to the application interface whenever a successfully established ACL isdisconnected.

Parameters

type DM_ACL_CLOSED_IND




In this section, we provide by way of example a number of usage scenarios and show theexpected typical primitive exchanges that will be seen at the DM APIs.



Device Manager

© 2001 282



8.13.1 RegistrationIn this example, both a SCO Control and Application Manager higher layer entities areregistering with the Device Manager. Where there is no SCO Control higher layer entity, theDevice Manager does not need the same registration to be made, for example from anotherentity, in order to operate. Logically in the absence of a SCO Control higher layer entity, thereis no support for the establishment and control of SCO connections.

Application manager Device Manager

DM AM_Register Req (AMQUEUE)

DM_AM_Register_Cfm

DM_SCO_Incoming_Register_Req (SCOQUEUE)

DM_SCO_Incoming_Register_Cfm

SCO Control

Figure 8-3: Registration Example

The first exchange is between the Application Manager and the Device Manager.

Register the Application Manager with the Device Manager.


msg_ptr = (DM_AM_REGISTER_REQ_T *)pmalloc(sizeof(DM_AM_REGISTER_REQ_T))


msg_ptr->type = DM_AM_REGISTER_REQmsg_ptr->phandle = AMQUEUE

The Application Manager now sends the message to Device Manager via the scheduler.

put_message(dm_ifacequeue, DM_PRIM, msg_ptr);

Method 2: Using the library functions (from dmlib.h)

dm_am_register_req(AMQUEUE);

Where AMQUEUE is the phandle of the application manager. The application managermay be part of the application.


Device Manager

© 2001 283

Once sent, the Application Manager returns control to the scheduler and awaits the next event.

register_cfm_handler(DM_AM_REGISTER_CFM_T* msg_ptr){

Free the memory block occupied by the DM_AM_REGISTER_CFM primitive.


The second exchange is totally independent of the first.

Register the incoming SCO connection control higher layer entity with the Device Manager.


msg_ptr = (DM_SCO_INCOMING_REGISTER_REQ_T *)pmalloc(sizeof(DM_SCO_INCOMING_REGISTER_REQ_T))


msg_ptr->type = DM_SCO_INCOMING_REGISTER_REQmsg_ptr->phandle = SCOQUEUE

SCO Control now sends the message to Device Manager via the scheduler.


Method 2: Using the library functions (from dmlib_sco.h)

dm_sco_incoming_register_req(SCOQUEUE, NULL);

Where SCOQUEUE is the phandle of the SCO control entity. The second parameter isset to NULL in this example as there is only one SCO control entity.

Once sent, SCO Control returns control to the scheduler and awaits the next event.

register_cfm_handler(DM_SCO_INCOMING_REGISTER_CFM_T* msg_ptr){

Free the memory block occupied by the DM_SCO_INCOMING_REGISTER_CFMprimitive.


8.13.2 SCO Connection EstablishmentThis section describes setting up of an outgoing SCO connection.


Device Manager

© 2001 284

SCO Control Device Manager

DM_SCO_Connect_Req

DM_SCO_Connect_Cfm

Figure 8-4: SCO Connection Establishment

Establish a SCO connection with a remote Bluetooth device.


msg_ptr = (DM_SCO_CONNECT_REQ_T *)pmalloc(sizeof(DM_SCO_CONNECT_REQ_T))


msg_ptr->type = DM_SCO_CONNECT_REQmsg_ptr->bd_addr.lap = value_of_lapmsg_ptr->bd_addr.nap = value_of_napmsg_ptr->bd_addr.uap = value_of_uapmsg_ptr->phandle = SCOQUEUEmsg_ptr->packet_type = 0 /* default */

SCO Control now sends the message to DM via the scheduler.


Method 2: Using the library functions (from dmlib_sco.h)

dm_sco_connect_req(p_bd_addr, 0, SCOQUEUE, NULL);

p_bd_addr is a pointer to the memory containing the bluetooth address structure. The secondparameter is the packet type, and is set to zero indicating the default, as in the method 1 case.SCOQUEUE is the phandle of the SCO control entity, this is used by DM as the return queuefor all response primitives. The value of the final parameter is returned by DM in all responseprimitives. It may be used to distinguish between several SCO channels. In this case it is set toNULL as there is only one SCO control entity.

Once sent, SCO Control returns control to the scheduler and awaits the next event.

connect_cfm_handler(DM_SCO_CONNECT_CFM_T* msg_ptr){

Free the memory block occupied by the DM_SCO_CONNECT_CFM primitive.



Device Manager

© 2001 285

8.13.3 InquiryThis section disscusses requesting an inquiry.

Device ManagerApplication Manager

DM_HCI_Inquiry

DM_HCI_Inquiry_Result

DM_HCI_Inquiry_Complete

DM_HCI_Remote_Name_Request

DM_HCI_Remote_Name_Complete



One or more responses, up to theMax number specified in the Inquiry.

Application Manager now decides whichdevice it wants to find further

information on.

Figure 8-5: Inquiry

Request an inquiry using the general inquiry code (GIAC).


msg_ptr = (DM_HCI_INQUIRY_T *)pmalloc(sizeof(DM_HCI_INQUIRY_T))


msg_ptr->common.op_code = DM_HCI_INQUIRYmsg_ptr->common.length = HCI_INQUIRY_PARAM_LENmsg_ptr->lap = 0x9E8B33msg_ptr->inquiry_length = 0x14 (= 25.6 seconds)msg_ptr->num_responses = 0x0a

The Application Manager now sends the message to the Device Manager via the scheduler.



dm_hci_inquiry(0x9E8B33, 0x14, 0x0a, NULL);

Where the values chosen are identical to those selected for method 1.

Once sent, the Application Manager returns control to the scheduler and awaits the next event.

The next procedure can be thought of in terms of a while loop (but we do not necessarilyrecommend this as a means of implementation):


Device Manager

© 2001 286

while (inquiry NOT complete){

inq_result_handler(DM_HCI_INQUIRY_RESULT_T* msg_ptr){

/* inquiry results are passed one at a time */ deal with msg_ptr->hci_inq_result.bd_addr deal with msg_ptr->hci_inq_result.dev_class etc. All are stored in the application manager. Some or all details may be passed to the user

Free the memory block occupied by the DM_HCI_INQUIRY_RESULT primitive.

pfree(msg_ptr) return}}

The above example can also be illustrated using Specification Design Language graphicalnotation.

START

HCIInquiry

Inquiring

InquiryResults

InquiryComplete

StoreResults

Inquiring

End

Figure 8-6: Inquiry–Flowchart

The termination of the while loop is made on the arrival of the HCI Inquiry Complete.

inq_complete_handler(DM_HCI_INQUIRY_COMPLETE_T* msg_ptr){

check msg_ptr->status to see if error


Device Manager

© 2001 287

Set the parameter that controls the while loop so that it is exited.

Finally, free the memory block occupied by the DM_HCI_INQUIRY_COMPLETEprimitive.


The Application Manager, probably in conjunction with the application and possibly with userinteraction, selects the device that it wants to discover further information about from the listgenerated by the inquiry response.


msg_ptr = (DM_HCI_REMOTE_NAME_REQUEST_T *)pmalloc(sizeof(DM_HCI_REMOTE_NAME_REQUEST_T))


msg_ptr->common.op_code = DM_HCI_REMOTE_NAME_REQUESTmsg_ptr->common.length = HCI_REMOTE_NAME_REQ_PARAM_LENmsg_ptr->bd_addr.lap = value_of_lapmsg_ptr->bd_addr.nap = value_of_napmsg_ptr->bd_addr.uap = value_of_uap

The Application Manager now sends the message to the Device Manager via the scheduler.



dm_hci_remote_name_request(p_bd_addr, NULL);

Where p_bd_addr is a pointer to the memory containing the bluetooth addressstructure.

Once sent, the Application Manager returns control to the scheduler and waits for the nextevent.

remote_name_complete_handler(DM_HCI_REMOTE_NAME_COMPLETE_T*msg_ptr){

if status == 0 /* i.e. success */extract msg_ptr->bd_addrextract msg_ptr->name

Finally, free the memory block occupied by theDM_HCI_REMOTE_NAME_COMPLETE primitive.



Device Manager

© 2001 288

8.13.4 Limited Discoverability ModeLimited Discoverability is a special case of discoverability mode (Inquiry Scan) whereby adevice in limited discoverable mode must also respond to a general inquiry that uses theGeneral Inquiry Access Code (GIAC). Many Bluetooth devices currently only implement asingle correlator, and as such can only respond to a single sync word, i.e. can only respond to asingle Inquiry Access Code. So, to implement limited discoverability it is necessary for thecontrolling software to time-share between the Limited Inquiry Access Code (LIAC) and theGIAC. The algorithm for this has to be implemented in the Application Manager. This sectionoutlines that algorithm.

The algorithm simply time shares the sync word correlator between the two IAC values. Thusthe algorithm is simply :


Device Manager

© 2001 289

Start

Inquiry Scan(GIAC)

Start Timer

wait timer expiry

Timer Expiry

Inquiry Scan(LIAC)

Start Timer

wait timer expiry

Timer Expiry

The selection of the timer value is important. The frequency hopping algorithm for scanning issuch that the clock phase that determines the scanning frequency only changes once every1.28seconds. The default parameters used for the inquiry scan activity are based around thisinterval of 1.28 seconds. Using the default inquiry scan activity, the scanning device entersinquiry scan for a window of 11.25ms every 1.28 seconds. Hence selecting a timeout of 1.28seconds would result in the device scanning using the GIAC and then 1.28 seconds later usingthe LIAC. The interval can be modified using the HCI Write Inquiry Scan Activity command.This could allow both GIAC and LIAC to be scanned for during the 1.28 second interval.


Device Manager

© 2001 290

Using the default settings, the resulting algorithm is then quite simple to implement:

Use the write scan enable command to set inquiry scan


msg_ptr = (DM_HCI_WRITE_SCAN_ENABLE_T *)pmalloc(sizeof(DM_HCI_WRITE_SCAN_ENABLE_T))


msg_ptr->common.op_code = DM_HCI_WRITE_SCAN_ENABLEmsg_ptr->common.length = HCI_WRITE_SCAN_ENABLE_PARAM_LENmsg_ptr->scan_enable = HCI_SCAN_ENABLE_INQ

Send message to DM



dm_hci_write_scan_enable(HCI_SCAN_ENABLE_INQ, NULL);

Write initial value for the IAC

current_IAC_LAP = LIAC


msg_ptr = (DM_HCI_WRITE_CURRENT_IAC_LAP_T *)pmalloc(sizeof(DM_HCI_WRITE_CURRENT_IAC_LAP_T))


msg_ptr->common.op_code = DM_HCI_WRITE_CURRENT_IAC_LAPmsg_ptr->common.length = HCI_WRITE_CURRENT_IAC_LAP_PARAM_LENmsg_ptr->num_current_IAC = 1msg_ptr->IAC_LAP[] = &LIAC

Send message to DM.



dm_hci_write_current_iac_lap(1, a_iac, NULL);

Where the values chosen are identical to those selected for method 1. The parametera_iac indicates the location of the array IAC_LAP[] = &LIAC.

Start Timer()


Device Manager

© 2001 291

OnTimerExpiry()

if (current_IAC_LAP == GIAC)

{

current_IAC_LAP = LIAC




msg_ptr->common.op_code = DM_HCI_WRITE_CURRENT_IAC_LAPmsg_ptr->common.length = HCI_WRITE_CURRENT_IAC_LAP_PARAM_LENmsg_ptr->num_current_IAC = 1msg_ptr->IAC_LAP[] = &LIAC

Then send the message to the DM.




Where the values chosen are identical to those selected for method 1. The parametera_iac indicates the location of the array IAC_LAP[] = &LIAC.

}

else

{

current_IAC_LAP = GIAC




msg_ptr->common.op_code = DM_HCI_WRITE_CURRENT_IAC_LAPmsg_ptr->common.length = HCI_WRITE_CURRENT_IAC_LAP_PARAM_LENmsg_ptr->num_current_IAC = 1msg_ptr->IAC_LAP[] = &GIAC

Then send the message to the DM.





Device Manager

© 2001 292

Where the values chosen are identical to those selected for method 1. The parametera_iac indicates the location of the array IAC_LAP[] = &GIAC.

}


HCI Transport

© 2001 293

9 HCI TransportBlueStack provides a portable interface for the HCI transport in HCI Top. You will need to readthis section in conjunction with the BlueStack Porting Guide if you are porting BlueStack to aplatform other than a PC running the Windows operating system.

The HCI transport carries the following services:

• HCI commands (including host controller initialisation)

• HCI events

• ACL bi-directional data

• SCO bi-directional data

There are three ’layers’ involved in the HCI transport, all of which are implemented as a set offunctions:

HCI Top Interface This is the interface to BlueStack higher layers for sending HCIcommands and ACL data. It also provides the application interfacefor transmission of SCO data.

This interface uses, as its subordinate, the host specific transportdriver for H:4, USB or BCSP.

HCI Driver Interface Provides a physical HCI transport independent interface for an HCItransport driver. This allows HCI Top to operate without knowledgeof the physical transport mechanism being used.

UART Driver Interface This defines a portable UART driver that is compatible with theBlueStack scheduler environment.

The interface provides support for the H:4 or BCSP transport driver.

Figure 9-1 shows the class relationship between the components of HCI Top.

The HCI Driver Interface is included within the Application Interface file, bluestack.h. Seethe section BlueStack Application Interface on page 37 for details of the HCI Driver Interface.


HCI Transport

© 2001 294

HCIdrv

HCIdrv_Init( )HCIdrv_Enum_Drivers( )HCIdrv_RegisterEventHandler( )HCIdrv_RegisterACLDataHandler( )HCIdrv_RegisterSCODataHandler( )HCIdrv_RegisterLinkFailHandler( )HCIdrv_SendCommand( )HCIdrv_SendACLData( )HCIdrv_SendSCOData( )HCIdrvReset( )HCIdrv_Select_Driver( )HCIdrv_Get_Current_Driver( )HCIdrv_Query_Driver_Available( )HCIdrv_Get_Driver_Name( )HCIdrv_Get_Driver_Description( )HCIdrv_Get_Driver_Id( )HCIdrv_RegisterSendCompleteHandler( )

USB_HCIdrv

Same public i/f as HCIdrv( )

HCItop

HCI_Init( )HCI_Command( )HCI_Send_ACL_Data_Packet( )HCI_Send_SCO_Data_Packet( )

BCSP_HCIdrv


UARTdrv

H4_HCIdrv


Figure 9-1: HCI Transport Component Relationship

You will need to consider the UART driver interface (UARTDrv for either H:4 or BCSP use) orthe USB interface (USB_HCIDrv) if you are porting BlueStack to a different platform. Theseinterfaces are described in the BlueStack Porting Guide.

9.1 HCI Top Interface

9.1.1 OverviewThe HCI Top Interface provides a transport independent API for all HCI transportcommunications. It is defined formally in HCItop.h.

It contains support for the following functions:

• SCO data channel transmission and reception

• ACL data channel transmission and reception

• HCI command interface

The ACL data and HCI command interfaces are for internal BlueStack use only. Theseinterfaces are associated with L2CAP and Device Manager.

Your application may need to use the SCO data channel functions if you wish to transfersynchronous data over the HCI interface in your design, for example a voice data stream.


HCI Transport

© 2001 295

The ACL data and HCI command functions are mentioned here only forcompleteness. You should not need to interface to these directly from yourapplication. Doing so may result in unexpected behaviour of BlueStack.

An outline of the use of the SCO data channel is given on page 301.

The following figure shows the relationship between the control and data flows for SCO withrespect to BlueStack and the SCO data handler in an application.

HCI

DM

DM_ API

HCI_Drv API

Application

SCO data

SCO Control(Connect,

Flow Control etc)

Figure 9-2: SCO Control and Data Flows

The overall implementation includes the mandatory credit based flow control mechanism in thedirection Host to Host Controller as specified in Chapter 3 of the Bluetooth specification H:1 forSCO data. See also page 222 . This should be provided by the Application that is responsiblefor transferring the SCO data.

The penultimate paragraph of Chapter 3 of specification H:1 also describes an optional creditbased flow control mechanism for SCO data for the direction Host Controller to Host usingcommand Set_Host_Controller_To_Host_Flow_Control. This mechanism is identical to themandatory Host to Host Controller mechanism. This manual does not include a description ofthis optional mechanism.


HCI Transport

© 2001 296

9.2 Downstream SCO Data Interface

SCO data are transmitted using the HCI_Send_SCO_Data_Packet function.

9.2.1 HCI_Send_SCO_Data_Packet

uint8_t HCI_Send_SCO_Data_Packet( HCI_SCO_DATA_COMMON_T *hci_header,MBLK_T *segment )

Description

This function sends the HCI SCO data packet, contained in the supplied message block of typeMBLK_T via pointer *segment, across the HCI.

The SCO channel will have been established by a preceding DM_SCO_CONNECT call. Thedata to be sent is associated with the SCO channel by the HCI connection handle fieldcontained in the structure HCI_SCO_DATA_COMMON_T via pointer *hci_header.

HCI_SCO_DATA_COMMON_T fields:


length Total HCI packet data length for all user data to be transmitted in the messageblock (or blocks for a linked list) *segment.

*segment would normally point to a linked list of MBLK_T references to data blocks. The pContfield in each MBLK_T points to the next block in the list.

The total HCI packet data length of HCI_SCO_DATA_COMMON_T is calculated by multiplying thedata block length of MBLK_T by the number of blocks to be sent in the HCI packet.

MBLK_T fields for upstream (transmitted) SCO data:

pData Pointer to the first data block in the packet.

pRelease Always set to NULL when calling HCI_Send_SCO_Data_Packet.

pCont Set to point to the start of the next data block. If only a single block is to betransmitted then this field should be set to NULL.

length Data block length for user data to be transmitted in message block *segment.If data are transmitted using a linked list of MBLK_T references to data blocksthe length field will normally be the same for each entry in the list.

pNext The SCO data handler may use this field to manage a transmit queue ofmessage blocks using its SCO flow control credits.

bufLength Not used.

pool Not used.


HCI Transport

© 2001 297

The HCI_Send_SCO_Data_Packet function will free both the header *hci_header and themessage block *segment whether or not the packet has been sent successfully.

This function is included in HCItop.h.

Returns

HCI_SUCCESS if the packet was accepted for sending.

HCI_ERROR_UNSPECIFIED if the packet was not accepted for sending.

9.2.2 Example

The following is an example of constructing a message block from an array of data namedtone_data :

if (tone_data[0]){ hci_header= (HCI_SCO_DATA_COMMON_T *)pmalloc(sizeof(HCI_SCO_DATA_COMMON_T)); hci_header->handle = handle; hci_header->length = MAX_TONE_LENGTH;

data_ptr = (uint8_t *)pmalloc(MAX_TONE_LENGTH); memcpy (data_ptr, &tone_data[0], MAX_TONE_LENGTH);

mblk_data_ptr = (MBLK_T *)pmalloc(sizeof(MBLK_T)); mblk_data_ptr->bufLength = 0; mblk_data_ptr->length = MAX_TONE_LENGTH; mblk_data_ptr->pCont = NULL; mblk_data_ptr->pData = data_ptr; mblk_data_ptr->pNext = NULL; mblk_data_ptr->pool = NULL; mblk_data_ptr->pRelease = data_ptr;

HCI_Send_SCO_Data_Packet( hci_header, mblk_data_ptr);}


HCI Transport

© 2001 298

9.3 Upstream SCO Data Interface

9.3.1 HCI_SCO_DATA_PACKET

typ

e

*hea

der

_ptr

*dat

a_p

tr

HCI SCO DATA PACKET IND ✔ ✔ ✔

Table 9-1: HCI_SCO_DATA_PACKET

Description

SCO data packet structure. This structure is returned to the SCO data handler function,sco_handler() .

The length of each data packet will be a maximum size of sco_packet_len bytes asindicated at initialisation by DM_SCO_BUFFER_SIZE_IND.

Parameters

*header_ptr Pointer to a header defining the originating source and the total data length in astructure of type HCI_SCO_DATA_COMMON_T .

HCI_SCO_DATA_COMMON_T fields:


length Total HCI packet data length for all user data received in the messageblock (or blocks for a linked list).

*data_ptr Data structure of type MBLK_T. This may refer to single or multiple linkedblocks as described below.

MBLK_T fields for upstream (received) SCO data:

pData Pointer to the first data block in the packet.

pRelease Pointer to pass to free the data subsequent to handling it.

pCont Set to point to the start of the next data block. The last block in thereceived packet has this field set to NULL.

length Data block length for user data received in message block. This maybe any value up to the maximum packet size minus the three bytesoccupied by *header_ptr.

pNext Not used. Reserved for future use.

bufLength Not used. Reserved for future use.

pool Not used. Reserved for future use.

*data_ptr would normally point to a linked list of MBLK_T references to data blocks. The pContfield in each MBLK_T points to the next block in the list.


HCI Transport

© 2001 299

Notes

The SCO data handler function is responsible for freeing the memory for *header_ptr,*data_ptr and the referenced data memory.

HCI SCO data is sent to the pre-defined scheduler queue SCOQUEUE.

SCOQUEUE may also be used for DM SCO management primitives. The scheduler queuehandler for SCOQUEUE may use the message id return parameter of the schedulerget_message call to distinguish between upstream DM primitives (DM_PRIM) and SCO HCIdata indications (HCI_PRIM).

The queue handler function is responsible for freeing all memory subsequent to use.

9.3.2 ExampleDuring start up, register an incoming SCO connection management task. In this example theSCO handler task is used (identifier SCOQUEUE):

void init_sco(void **gash){DM_SCO_INCOMING_REGISTER_REQ_T *dm_prim;

dm_prim = (DM_SCO_INCOMING_REGISTER_REQ_T *) pmalloc(sizeof(DM_SCO_INCOMING_REGISTER_REQ_T));

dm_prim->type = DM_SCO_INCOMING_REGISTER_REQ; dm_prim->phandle = SCOQUEUE;

dmPutMessage(DM_PRIM, dm_prim);}

Using get_message to receive SCO primitives and data:

void sco_handler(void **gash)

{

uint16_t m;

HCI_SCO_DATA_COMMON_T *hci_header;

HCI_SCO_DATA_PACKET_IND_T *sco_packet;

hci_connection_handle_t handle;

uint8_t *data_ptr;

uint16_t dataLen;

MBLK_T *mblk_data_ptr;

DM_UPRIM_T *dm_prim;

void *prim;

/*

* Extract the message from the SCO queue,

* is it SCO data or SCO commands

*/

get_message(SCOQUEUE, &m , (void **)&prim);

/*

* Primitive or Data

*/

if (m == DM_PRIM)


HCI Transport

© 2001 300

{

dm_prim = (DM_UPRIM_T*) prim;

/* Deal with SCO command primitive */

switch (dm_prim->type)

{

/* Indication that someone wishes to connect SCO */

case DM_SCO_CONNECT_IND:

{

DM_SCO_CONNECT_IND_T * ind =

(DM_SCO_CONNECT_IND_T *)dm_prim;

/* Accept the connection */

dm_sco_connect_res(ind->handle, TRUE);

}

case … /* Deal with other primitives */

}

pfree(dm_prim);

}

else

{

/* For any other m value it must be SCO data. */

sco_packet = (HCI_SCO_DATA_PACKET_IND_T *) prim;

sco_handle = sco_packet->header_ptr->handle; /* Global SCO handle */

mblk_data_ptr = ( MBLK_T * )sco_packet->data_ptr;

handle = sco_packet->header_ptr->handle;

dataLen = sco_packet->header_ptr->length;

data_ptr = mblk_data_ptr->pData;

for (m=0; m<dataLen;m++)

{

/* Deal with data accessed as *data_ptr++ */

}

/* free all the data */

mblk_free((MBLK_T *)(sco_packet->data_ptr));

pfree(sco_packet->header_ptr);

/* free the event primitive */

pfree(sco_packet);

}


HCI Transport

© 2001 301

9.4 SCO data application management

The following steps describe, in general terms, how to manage the establishment of an SCOchannel and the transfer of SCO data in your application. It refers, where relevant, to othersections of this manual.

Step Action

1 At power up, register your application handler(s) with Device Manager asshown on page 282 using the pre-defined phandle SCOQUEUE.

2 Perform an Inquiry, if required, to find the device you wish to connect to (e.g.using DM_HCI_INQUIRY – see page 285).

3 Establish an ACL connection using L2CA_CONNECT_REQ.

4 Establish the SCO connection using DM_SCO_CONNECT_REQ (see page 261 and283).

5 Use the DM_BUFFER_SIZE_IND to establish the number of credits for the flowcontrol from the sco_packet_len and the sco_total_packetsparameters. The parameter sco_packet_len also defines the maximumsize of the SCO data packets.

6 Construct an HCI_SCO_DATA_COMMON_T structure using the handle from thepreceding SCO connection and the total length of data that will be transmittedin your MBLK_T structure.

7 Construct your message block MBLK_T as a linked chain using the pCont fieldas the pointer to the next message block in the chain.

8 Send the SCO data using HCI_Send_SCO_Data_Packet (see page 296).

9 Decrement locally the number of flow control credits.

10 Confirm that the data has been sent using DM_SCO_DATA_SENT (see page 264).

11 DM_SCO_DATA_SENT also includes details of the number of packets that havebeen sent, and the flow control credits can be updated accordingly.

12 Upstream data is received as a queue of message blocks MBLK_T on the pre-defined SCO data handler scheduler queue (SCOQUEUE) (see page 298 )

9.5 UART Driver Function Interface and USB Interface

You will need to consider these interfaces if you are porting BlueStack to a different platform.

They are described in the BlueStack Porting Guide.


Writing a Port Entity

© 2001 302

Annex A Writing a Port EntityThis annex describes how to write a Port Entity and provides a simple model as an example.

It contains the following sections:

� Overview on page 302

� Example Action Functions on page 308

A.1 Overview

The Port Entity is the software sub-system located between RFCOMM and the application. Inmany cases the application has no knowledge of Bluetooth, other than that it is acommunications link.


Link Manager

HCI


SDP

RFCOMM


Management Entity

Provided Application BT AppApplication Layer

Integration Layer



Figure 9-3: Layers Required in an Application Running over Bluetooth

The Port Entity is required to provide the following functionality:

� adapt the service requests from the application into RFCOMM primitives and vice-versa

� the adaptation of the different operating system

In this example, the Bluetooth control functions for SDP searches, pairing, inquiry, and othermanagement functions are not included; they are assumed to be part of the ApplicationManager.

In this example, the application is opening a low-level driver as a file interface, for example asimple RS-232 connection to another device.



© 2001 303

The application expects only a few simple function calls:

file_descriptor = open(file_name, access)

close(file_descriptor)

read(file_descriptor, buffer, n)

write(file_descriptor, buffer, n)

In both the read and write functions, the buffer is large enough to hold the n bytes of data thatare to be transferred.

For this example, the following assumptions have been made about the application:

� It is a client process only and always makes an outgoing connection to a server.

� It cannot accept an incoming connection request.

� It can receive incoming data, but it needs to initiate the connection to the server first.

Because the client only makes an outgoing connection, the port entity is simplified since there isno requirement for this application to include an entry in the local Service Discovery database–itis not a service that is provided to any other Bluetooth device.

The port entity is also simplified because the connection management it maintains does nothave to handle incoming connections.

Although the application only uses a small number of function calls, in order to design the portentity in an applicable manner usage of these function calls must be understood. The portentity has three main phases:

� open a multiplexer session with the remote RFCOMM

� establish a connection with the remote application server

� transfer the data

The application has only two phases:

� open the connection

� data transfer

While the data transfer phase is common to both the port entity and the application, the openphase for the application needs to be mapped according to the application’s requirements. Onefactor that influences the design approach is how the application transfers data. If theapplication requirement is session based (in other words the transfer of one or more packets orfiles) then an application might, for efficiency, only open the connection once before the firstdata are transferred.

Alternatively, the application can open the connection on a packet by packet basis.

The difference between these connection strategies is illustrated in Figure 9-4 on page 304.



© 2001 304

open

data data data data

open open open

data data data

Figure 9-4: Differences in Data Transfer

The first model (the connection is opened once) is appropriate when the data transfer time iscomparable to the connection opening time, it is more efficient to open the connection once andthen transfer the data. However, this does require the application to know when it can close theconnection.

The second model (the connection is opened for each transfer) is applicable when theconnection opening time is short in comparison with the data transfer time, for example when alarge file is being transferred.

For this example it is assumed that the connection is opened only once. Mapping to the portentity phases is now considered.

open

data data

Application

Port Entity

mux sessionconnection

data data

Figure 9-5: Port Entity Phases

The next step of the process is to map the calls from the application to the primitives ofRFCOMM.



© 2001 305

Application Port Entity RFCOMM

open

RFC_Start_Req

RFC_Start_Cfm

RFC_ParNeg_Req

RFC_ParNeg_Cfm

RFC_Establish_Req

RFC_Establish_Cfm

return

write

RFC_Data_Reqreturn

write

RFC_Data_Reqreturn

close

RFC_Release_Req

returnRFC_Close_Req

mux

connection

Figure 9-6: Port Entity Application to RFCOMM Calls

This relatively simple example does not include any parameter re-negotiation or flow control.However, it does indicate some of the additional states that have to be provided within the PortEntity.

For this example, there is no parameter re-negotiation - if the parameters cannot be negotiatedwith the remote end the connection is closed.

The example also illustrates the adaptation between the different operating environments. Theapplication makes simple function calls, which return control once the function is completed. Inthe case of the open() function, the Port Entity is involved in significant processing before thereturn is sent. The open() function is shown as a blocking call - it stops, waiting for the return.In fact, RFCOMM and the other layers of the stack return control to the scheduler a number oftimes during this processing as they wait for events in the form of messages from the remotedevice.

If the operating system is a multi-threaded operating system, the protocol stack and applicationneed to run under different threads. If the operating system is single threaded, the controlneeds to be transferred to the protocol stack scheduler.

The exact form of implementation of the Port Entity depends on the operating system theapplication is running on. The Port Entity has to be capable of having events posted to it from



© 2001 306

RFCOMM via a scheduler, and has to be capable of posting events to RFCOMM via ascheduler. Whether this event posting mechanism is provided by the embedded scheduler orby the host operating system depends on the capabilities of the operating system theapplication is running on.

The BlueStack Porting Guide explains how to set up the queue id for the Port Entity so thatRFCOMM can post events to the Port Entity using the embedded scheduler.

Closed

mux pending

mux

Establish Pending

Established

open/RFC_Start_Req

RFC_Start_Cfm/RFC_ParNeg_Req

RFC_ParNeg_Cfm/RFC_Establish_Req

RFC_Establish_Cfm/return

write/RFC_Data_Req

close/RFC_Release_ReqRFC_Close_Req

return

Figure 9-7: Message Exchange

The message exchanges can be represented as a state machine, as in Figure 9-7. Moreformally, these can be described in a state table. In the state table, a named action function isincluded to describe the action. For brevity, the state table does not describe any errorconditions. The action functions are described in pseudo-code after the table.



© 2001 307

Event Final State Action Function

Actions when in state Closed

open mux pending Send_Start_Req

Actions when in state mux pending

Start_Cfm mux Send_ParNeg_Req

Actions when in state mux

ParNeg_Cfm Establish Pending Send_Establish_Req

ParNeg_Cfm (-ve) Closed Send_Close_Req

Actions when in state Establish Pending

Establish_Cfm Established Send_Established_ok

Actions when in state Established

Write Established Send_Data

Read Established Read_Data

Data_Ind Established Store_Data

Close Closed Close_Connection

Table 9-2: Message Exchange State Table

In addition to message exchange, provision needs to be added for handling flow control. Theflow control strategy must be determined before implementation.

The events that originate from RFCOMM are posted to a common handler. The basic flow ofcontrol is shown in Figure 9-8:

Event

Determine event

Post event to statemachine

Action function

End

Figure 9-8: Basic Flow Control



© 2001 308

The Port Entity has a common message handler function for the events from RFCOMM with aformat as follows:

static void message_handler(RFCOMM_UPRIM_T* msg_ptr)

/* Switch on the type of message */ switch(msg_ptr->type)

case RFC_START_CFM: post event Start_Cfm to state machine case RFC_PARNEG_CFM: if parameters acceptable post event ParNeg_Cfm to state machine else post event ParNeg_Cfm (-ve) to state machine case RFC_ESTABLISH_CFM: post event Establish_Cfm to state machine case RFC_DATA_IND: post event Data_Ind to state machine case RFC_CLOSE_IND: case RFC_RELEASE_IND: post event Close to state machine

The function calls from the Port Entity interface to the application can be handled directly,posting the appropriate events into the state machine.

Before the application can run, both the Bluetooth device address and the routing information ofthe remote application must be obtained. These can be obtained across the air using BluetoothInquiry (DM_HCI_INQUIRY on page 230) and SDP search (SDC_SERVICE_SEARCH on page116, SDC_SERVICE_ATTRIBUTE on page 118 or SDC_SERVICE_SEARCH_ATTRIBUTE onpage 119) requests.

The Port Entity registers with RFCOMM as part of its own initialization routine.

A.2 Example Action Functions

The following sections describe example action functions.




Send_Start_ReqIn this action function, the Bluetooth Device Address has been obtained, probably as the resultof a Bluetooth Inquiry and is known to the application manager. The remote PSM has beenobtained, probably as the result of a SDP search request (SDC_SERVICE_SEARCH on page116, SDC_SERVICE_ATTRIBUTE on page 118 or SDC_SERVICE_SEARCH_ATTRIBUTE onpage 119). The phandle PORT1_QUEUE has been included with the scheduler configurationat build time. The port_speed and max_frame_size are arbitrary choices.



© 2001 309


msg_ptr = (RFC_START_REQ_T *)pmalloc(sizeof(RFC_START_REQ_T))


msg_ptr->type = RFC_START_REQmsg_ptr->bd_addr.lap = value_of_lapmsg_ptr->bd_addr.nap = value_of_napmsg_ptr->bd_addr.uap = value_of_uapmsg_ptr-> psm_remote = RFCOMM_PSM /* assume default */msg_ptr-> respond_phandle = PORT1_QUEUE;msg_ptr->sys_pars.port_speed = PORT_SPEED_UNUSEDmsg_ptr->sys_pars.max_frame_size = RFCOMM_MAX_FRAME_SIZE




rfc_start_req(p_bd_addr, RFCOMM_PSM, p_sys_pars, PORT1_QUEUE);

Where p_bd_addr is a pointer to the memory containing the bluetooth addressstructure, and p_sys_pars is a pointer to the memory containing the system parametersstructure.

Send_ParNeg_Req


msg_ptr = (RFC_PARNEG_REQ_T *)pmalloc(sizeof(RFC_PARNEG_REQ_T))


msg_ptr->type = RFC_PARNEG_REQmsg_ptr->mux_id = this_mux_idmsg_ptr-> loc_server_chan = local_server_chan /* assigned at registration */msg_ptr->rem_server_chan = remote_server_chan; /* found via SDP */msg_ptr->dlc_pars.max_frame_size = 127 /* RFCOMM default */msg_ptr->dlc_pars.credit_flow_control = TRUE; /* credit flow control requested */msg_ptr->dlc_pars.initial_credits = initial_credit_value;




rfc_parneg_req(this_mux_id, local_server_chan, remote_server_chan, p_dlc_pars);

Where p_dlc_pars is a pointer to the memory containing the dlc parameters structure,and local_server_chan is the local server channel assigned when the port entityregisters with RFCOMM.



© 2001 310

The local server channel number is passed to the Port Entity in the RFC_Register_Cfmprimitive, and the mux_id in the RFC_Start_Cfm primitive.

Send_Establish_Req


msg_ptr = (RFC_ESTABLISH_REQ_T *)pmalloc(sizeof(RFC_ESTABLISH_REQ_T))


msg_ptr->type = RFC_ESTABLISH_REQmsg_ptr->mux_id = this_mux_idmsg_ptr-> loc_server_chan = local_server_chan /* assigned at registration */msg_ptr->rem_server_chan = remote_server_chan; /* found via SDP */



rfc_establish_req(this_mux_id, local_server_chan, remote_server_chan);

Where local_server_chan is the local server channel assigned when the port entityregisters with RFCOMM.

Send_Close_Req


msg_ptr = (RFC_CLOSE_REQ_T *)pmalloc(sizeof(RFC_CLOSE_REQ_T))

The members of the structure are set up.

msg_ptr->type = RFC_CLOSE_REQmsg_ptr->mux_id = this_mux_id




rfc_close_req(this_mux_id);

Send_Established_ok(return)

Send_Datadata_ptr = pmalloc(sizeof(DATA))



© 2001 311


msg_ptr = (RFC_DATA_REQ_T *) pmalloc(sizeof(RFC_DATA_REQ_T))

msg_ptr->type = RFC_DATA_REQ;msg_ptr->mux_id = this_mux_id;msg_ptr->server_chan = serv_chan_nomsg_ptr->payload = data_ptrmsg_ptr->payload_length = sizeof(DATA)msg_ptr->credits = update_credits; /* no of new credits to give RFCOMM */




rfc_data_req(this_mux_id, serv_chan_no, update_credits, sizeof(DATA), data_ptr);

Where update_credits is the number of new credits that are being passed to RFCOMM,indicating the number of upstream data message buffers that have been cleared.

Read_DataHere the application reads the data from wherever it has been stored by the Store_Data actionfunction.

Store_Datadata_ind_handler(RFC_DATA_IND_T* msg_ptr){

deal with msg_ptr-> mux_id, if required

Store the data in a buffer that can be read by the application. If both the application andBlueStack are able to work with a common memory pool, then this can be achievedwithout a need to copy the data.

Finally free the memory block occupied by the RFC_DATA_IND primitive (not thedata!).


Close_Connection


msg_ptr = (RFC_RELEASE_REQ_T *)pmalloc(sizeof(RFC_RELEASE_REQ_T))




© 2001 312

msg_ptr->type = RFC_RELEASE_REQmsg_ptr->mux_id = this_mux_idmsg_ptr-> server_chan = serv_chan_no /* arbitrary example */



msg_ptr = (RFC_CLOSE_REQ_T *)pmalloc(sizeof(RFC_CLOSE_REQ_T))


msg_ptr->type = RFC_CLOSE_REQmsg_ptr->mux_id = this_mux_id




rfc_release_req(this_mux_id, serv_chan_no);rfc_close_req(this_mux_id);

(return)

The data handling is not symmetric–read and write are handled somewhat differently. Ideally,the data can be assembled in a memory block that is common to both BlueStack and theapplication. This allows the memory block to be allocated by the application and then freed byBlueStack when the data is transmitted. If this is not possible, the Port Entity is responsible forcopying the data.

Assuming that the data memory management is common, data to be written is allocated anarea of memory, and the write command transfers the location of that data to the Port Entity.The Port Entity is able to deal with this data directly. Received data is buffered by the PortEntity. It is the responsibility of the application to read the data.

Port Entity designers may want to implement additional functionality across their applicationinterfaces to avoid the need for the application to poll the Port Entity at intervals to see if there isany data to be read. However, there will be applications where this method is entirelyadequate.


Error Codes

© 2001 313

Annex B Error CodesThis annex lists the general error codes that BlueStack might return in abnormal circumstances.

These are specific errors that could be reported by individual subsystems of the stack. The topeight bits (SS_MASK) of the sixteen bit error word define the stack subsystem that the error isreported by. The bottom eight bits, which can be extracted using ERROR_MASK, define thespecific error type for that subsystem.

The following section from error.h provides the formal definition of the mask structure:

/*=================================================*Public Defines*==================================================*/

typedef uint16_t error_code_t;

/* Error masks */#define SS_MASK ((error_code_t)0xff00)#define ERROR_MASK ((error_code_t)0x00ff)

#define GENERAL_ERROR ((error_code_t)0x0000)#define RFCOMM_ERROR ((error_code_t)0x0100)#define L2CAP_ERROR ((error_code_t)0x0200)#define DM_ERROR ((error_code_t)0x0300)#define HCI_ERROR ((error_code_t)0x0400)#define LM_ERROR ((error_code_t)0x0500)#define SDP_ERROR ((error_code_t)0x0600)#define CS_ERROR ((error_code_t)0x0700)

The error codes for each subsystem named above are listed below.

Note that CS_ERROR codes are returned by the Communications Subsystem. This might be, forexample, as a result of a BCSP serial communications problem.

B.1 GENERAL_ERRORNO_ERRMEMORY_ERR

B.2 RFCOMM_ERRORRFC_MEMORY_ERRINVALID_MUX_ID_ERRINVALID_CID_ERRRFC_PROTOCOL_ERR

B.3 L2CAP_ERRORCONTROL_ERRCON_HANDLE_ERRCID_ERRSM_ERRSIGNAL_ERRPHANDLE_ERR /* No phandle for reply */


Error Codes

© 2001 314

B.4 DM_ERRORCOMMAND_STATUS_ERRCOMMAND_COMPLETE_ERRRM_ERRCMCB_ERRDM_HANDLE_INVALIDNUM_COMPLETED_PACKETSDM_PHANDLE_ERR /* No phandle for reply */

B.5 HCI_ERRORFILTER_CONDITION_TYPEFILTER_TYPEEVENT_TRANSLATIONCOMMAND_TRANSLATIONCOMMAND_COMPLETE_GROUPCOMMAND_COMPLETE

B.6 LM_ERRORLM_ERR_NO_ERRORLM_ERR_LC_LMP_FAILLM_ERR_LC_PAGE_SCAN_FAILLM_ERR_LC_END_PAGE_SCAN_FAILLM_ERR_LC_HOLD_FAILLM_ERR_LC_SET_ACL_PACKET_FAILLM_ERR_LC_DESTROY_ACL_FAILLM_ERR_LC_DESTROY_SCO_FAILLM_ERR_NO_INSTANCE_FOUND /* Null pointer for specified instance */LM_ERR_BAD_AM_ADDR /* am_addr exceeds limits */LM_ERR_UNKNOWN_STATE /* State Machine State in error */LM_ERR_PMALLOC_FAILEDLM_ERR_LC_INQUIRE_SCAN_FAILLM_ERR_LC_INQUIRE_FAILLM_ERR_ACL_LOOKUP_CONFLICT /* ACL Entry we are trying to fill is in use */LM_ERR_LC_ERROR /* General non-fatal LC error */LM_ERR_LM_FATAL_ERROR /* General fatal LM error */LM_ERR_LC_FATAL_ERROR /* General fatal LC error */LM_ERR_LC_NOT_RECOGNISED_HANDLE /* General LC handle error */

B.7 SDP_ERRORSDC_ERRSDS_ERR

B.8 CS_ERRORCS_LINK_FAILDRV_FAIL_CREATE_READ_THDDRV_FAIL_CREATE_READ_WRITE_EVENTDRV_FAIL_OPEN_DEVICEDRV_FAIL_CONFIG_PORTDRV_FAIL_MEMDRV_FAIL_READDRV_FAIL_WRITEDRV_FAIL_SLIP_DECODEDRV_SLIP_BUF_OVERFLOW


Changes in this version

© 2001 315

Annex C Changes in this versionThis Annex summarises the changes made to the BlueStack User Manual since C6066-UM-001v1.1 released in April 2001. In particular it lists where changes have been made to theAPI’s.

C.1 General

No changes

C.2 Introduction

Removed product icons

C.3 Overview

Added overview section on TCS Binary.

Added section on interface libaries and references to the interface libraries.

Added overview section on BlueStack Application Interface.

Removed sections on scheduler, inter-process communication and communications services tothe section BlueStack Application Interface.

C.4 BlueStack Application Interface

Added new section.

C.5 RFCOMM

Added new primitive RFC_NSC_IND.

Native primitive examples removed.

Interface library functions added to scenarios and examples.

C.6 SDP

Section page layout made consistent with rest of document.

SDS



SDC





© 2001 316

C.7 TCS

Added new primitive TCS_UNREGISTER (Request and Confirmation).

Added TCS_CALLING_PARTY_NUMBER and TCS_AUDIO_CONTROL parameters to TCS_INFO_REQand TCS_INFO_IND primitives.

C.8 L2CAP

Added phandle parameter to L2CA_ENABLE_CONNECTIONLESS_REQ andL2CA_ENABLE_CONNECTIONLESS_REQ primitives.



C.9 Device Manager

Substantial rework to reflect addition of Security Manager API to the Device Manager, and thechanges to the ‘DM_HCI’ API to align it more closely with the Bluetooth HCI interface. Theintroductory section has been amended to align with the changes.

Summary of Changes:

The primitive DM_REGISTER now DM_AM_REGISTER and applicable to Application Manageronly. The pidentifier field has now been removed as a result.

Descriptions of the new primitives DM_SCO_INCOMING_REGISTER andDM_SCO_INCOMING_UNREGISTER added.

The primitives DM_HCI_PIN_CODE_REQ_REPLY and DM_HCI_PIN_CODE_REQ_NEG_REPLYare replaced by the DM_SM_PIN_REQUEST_RES primitive.

The scope of the DM_HCI_CHANGE_PACKET_TYPE primitive is now restricted to SCOconnections only.

The primitive DM_AUTHENTICATE is replaced by the primitive DM_SM_AUTHENTICATE_REQ.

The primitive DM_SET_ENCRYPTION is replaced by the primitive DM_SM_ENCRYPT_REQ.

The primitive DM_CONNECT is renamed DM_SCO_CONNECT and a _RES variant is added.

The primitive DM_DISCONNECT is renamed DM_SCO_DISCONNECT.

The primitive DM_BUFFER_SIZE is renamed DM_SCO_BUFFER_SIZE.

The primitive DM_DATA_SENT is renamed DM_SCO_DATA_SENT.

The description of the primitive DM_SCO_DATA_PACKET is moved to the section ‘HCITransport’.

The primitives DM_READ_CACHED_COD_REQ and DM_READ_CACHED_COD_COMPLETE areremoved.

Some of the examples of primitive usage are now taken directly from the demonstrationcode supplied in BlueStackAPI.

The following primitives described in the user manual are amended to DM_HCI_xxx andas a result the type parameter is replaced by the common_op_code field.



© 2001 317

DM_CHANGE_LINK_KEYDM_MASTER_LINK_KEYDM_REMOTE_NAME_REQUESTDM_READ_REMOTE_FEATURESDM_READ_REMOTE_VERSIONDM_READ_CLOCK_OFFSETDM_HOLD_MODEDM_HCI_SNIFF_MODEDM_EXIT_SNIFF_MODEDM_PARK_MODEDM_EXIT_PARK_MODEDM_ROLE_DISCOVERYDM_SWITCH_ROLEDM_READ_LP_SETTINGSDM_WRITE_LP_SETTINGSDM_FLUSHDM_READ_AUTO_FLUSH_TIMEOUTDM_WRITE_AUTO_FLUSH_TIMEOUTDM_READ_TX_POWER_LEVELDM_READ_SCO_FLOW_CONTROL_ENABLEDM_WRITE_FLOW_CONTROL_ENABLEDM_READ_LINK_SUPERV_TIMEOUTDM_WRITE_LINK_SUPERV_TIMEOUTDM_FAILED_CONTACT_COUNTERDM_RESET_CONTACT_COUNTERDM_GET_LINK_QUALITYDM_READ_RSSI

Added to the section ‘Usage Scenarios and Examples’, a description of the algorithmrequired for implementing Limited Discoverability mode using sequential scanning. Forconsistency with this section, descriptions of the primitives DM_HCI_WRITE_SCAN_ENABLEand DM_HCI_WRITE_CURRENT_IAC_LAP added.



C.10 HCI Transport

Moved HCI_SCO_DATA_PACKET_IND primitive description to this section from Device ManagerSection

Re-ordered sections in order to accommodate the above in a logical fashion.

Class diagram updated to reflect current status of interface.

Typographical modifications to reflect the above and other DM_SCO related changes.

C.11 Annex A – Writing a port entity

Interface library functions added to examples.

C.12 Annex B – Error Codes

No changes


Glossary

© 2001 318

GlossaryTerms

eventAn instance of an asynchronous communication that carries no information other than the eventtype.

Big EndianStandard Network byte order, with most significant (high-order) bytes transferred before less-significant (low-order) bytes.

downstreamMoving towards higher layers of the stack – in other words, from L2CAP moving throughRFCOMM to higher level entities.

hostA label for all the subsystems that are found above the host controller interface, includingL2CAP, the Device Manager and any higher protocol layers.

host controllerA label for all the subsystems that are found below the host controller interface, which includesthe Link Manager and Link Controller.

phandleprotocol handle

server channelA logical channel on an RFCOMM multiplexer instance. It is a 5-bit number and can beconverted into a 6-bit DLCI by expanding it with the direction bit of the multiplexer instance.

upstreamIn the direction towards lower layers of the stack – in other words from entities above RFCOMMthrough to L2CAP.


Acronyms

© 2001 319

Acronyms

_CFM Confirmation–service primitive notation

_IND Indication–service primitive notation

_REQ Request–service primitive notation

_RES Response–service primitive notation (apart from L2CAP)

_RSP Response–service primitive notation (within L2CAP)

ACL Asynchronous ConnectionLess. This is a Bluetooth defi-nition of a basic bearerservice that provides asynchro-nous packet data transfer across the air interface.

BCSP BlueCore Serial Protocol – the Cambridge Silicon Radio Ltd proprietary HCItransport protocol

BD_ADDR Bluetooth Device Address. This is a 48-bit address that is unique to the Bluetoothdevice.

BOS Boring Of Scunthorpe

CFC Credit based flow control for RFCOMM

CID Connection Identifier (returned by L2CAP as the handle for a connection) This isthe logical channel identity that is used by both peers in L2CAP.

CLIP Calling Line Identity Presentation

CO Connection Oriented

CS Communications Subsystem

CTS Clear to Send

DCD Data Carrier Detect

DCE Data Communication Equipment

DLC Data Link Connection

DLCI Data Link Connection Identifier

DM Data Manager

DSR Data Set Ready

DTE Data Terminal Equipment

DTMF Dual-Tone Multi-Frequency

DTR Data Terminal Ready

DV Data Valid

ERTX Extended Response Timeout eXpired

ETSI European Telecommunications Standards Institute

GIAC General/unlimited Inquiry Access Code

GSM Global System for Mobile communications (previously Groupe Special Mobile)

GW Gateway

HCI Host Controller Interface


Acronyms

© 2001 320

HDLC High-level Data Link Control

HID Human Interface Device

IAC Inquiry Access Code

IC Incoming Call

ID IDentity

IrDA Infra-red Data Association

L2CAP Logical Link Control and Adaptation Protocol

LAP Lower Address Part–The Bluetooth Device Address is formed of three parts ofwhich the LAP is one.

LIAC Limited Inquiry Access Code

LM Link Manager

LMP Link Management Protocol

LSB Least Significant Bit

MCME Multiplexer Control Management Entity

MSB Most Significant Bit

MSC Modem Status Command

MTU Maximum Transmission Unit

NAP Non-significant Address Part–The Bluetooth Device Address is formed of threeparts of which the NAP is one. It is non-significant as unlike UAP and LAP, it isused only within the BD_ADDR.

NSC Non-Supported Command response

Obex Object exchange

OO Object-Oriented

OSI Open Systems Interconnection

PDU Protocol Data Unit

PEE Port Emulation Entity

PIN Personal Identity Number

PN Port Negotiation

PPE Port Proxy Entity

PSM Protocol/Service Multiplexer

QoS Quality of Service

RFCOMM Serial cable emulation based on ETSI GMS TS 07.10

RFR Ready For Receiving

RI Ring Indication

RLS Remote Line Status

RPN Remote Port Negotiation

RTR Ready to Receive


Acronyms

© 2001 321

RTS Ready To Send

RTX Response Timeout eXpired

SABM Set Asynchronous Balanced Mode

SCO Synchronous Connection Oriented–This is a Bluetooth definition of a basicbearer service that provides a synchronous circuit type data transfer serviceacross the air interface

SDC Service Discovery Client

SDP Service Discovery Protocol

SDS Service Discovery Server

SDSS Service Discovery Sub-System

SIG Special Interest Group

TCP/IP Transport Control Protocol/Internet Protocol

TCS Telephony Control Specification

TL Terminal

UAP Upper Address Part–The Bluetooth Device Address is formed of three parts ofwhich the UAP is one. The UAP is used in the initialization of the packet HeaderError Check (HEC) code.

UART Universal Asynchronous Receiver and Transmitter.

UIH Unnumbered Information with Header Check

USB Universal Serial Bus

UUID Universally Unique IDentifier

WAP Wireless Application Protocol

WUG Wireless User Group

XAP2 Cross Application Processor

bluestack user manual - pudn.comread.pudn.com/downloads164/sourcecode/unix_linux/...bluestack user...

Documents