How to Develop and Load a Bluetooth HCI Stack Extension Layer

Article
03/19/2010

Other versions of this page are also available for the following:

Windows Embedded CE 6.0 R3

8/28/2008

Windows Embedded CE provides a flexible stack implementation that enables you to extend the base stack functionality. For example, you can enhance the functionality of the stack to include synchronous connection oriented (SCO) support.

The extension layer described in this section must be installed on top of the HCI layer. The extension layer must be developed as an installable stream device driver that makes use of a common set of APIs to manage the device. All Bluetooth stack layers, from HCI and up, follow the same guidelines for exporting interfaces and connecting to lower-level stacks. The templates for these functions are included in this section.

Note

The term ExtensionLayer_ is a placeholder for the name of the extension layer that you are creating. The term driver is a placeholder for the installable stream driver that loads the extension layer. For example, the extension layer name can have real stack layer prefixes such as HCI_, L2CAP_, SDP_, or RFCOMM_.

The extension layer described in this section is based on the BthLink sample. This sample extends the HCI layer and provides the functionality to generate a link key between two devices in the pairing process. For more information about BthLink, see Protocol Extension Sample.

For more information about the HCI layer, see Host Controller Interface.

Steps

Step Topic

Step	Topic
1. Implement the required commands that the extension layer must support.	HCI Commands Implementing Commands, Callbacks, and Events Handlers for an Extension Layer
2. Implement the required HCI event handlers and the HCI callback functions. For example, the sample BthLink implements: The HCI_ConnectionCompleteEvent event in the bthlink_ConnectionCompleteEvent handler to notify the HCI layer and the peer device that the connection has been established. The command complete callback function for the HCI_CreateConnection command in the bthlink_CreateConnection_Out function to create a connection between the HCI layer and the peer Bluetooth device.	HCI Events HCI Callbacks Implementing Commands, Callbacks, and Events Handlers for an Extension Layer
3. Declare function pointers to the event handler and callback functions created in step 2 and for the commands that the extension layer implements. The following code example shows function pointer declarations for bthlink_ConnectionCompleteEvent and bthlink_CreateConnection_Out declared in the BthLink sample. `static int bthlink_ConnectionCompleteEvent( void pUserContext, void pCallContext, unsigned char status, unsigned short connection_handle, BD_ADDR pba, unsigned char link_type, unsigned char encryption_mode); static int bthlink_CreateConnection_Out( void pCallContext, unsigned char status);`	Implementing Commands, Callbacks, and Events Handlers for an Extension Layer
4. Create a class to implement the Bluetooth stack extension layer. The BthLink sample creates a class named bthlink. This class is derived from SVSSynch and SVSRefObj, and is defined in svsutil.hxx to inherit the built-in multi threaded functionality.	Not applicable
5. Register the extension layer event handlers and the callback functions with the HCI layer. The following code example is an excerpt from the BthLink class constructor that registers bthlink_ConnectionCompleteEvent and bthlink_CreateConnection_Out with the HCI layer. `HCI_EVENT_INDICATION hei; HCI_CALLBACKS hc; hei.hci_ConnectionCompleteEvent = bthlink_ConnectionCompleteEvent; hc.hci_CreateConnection_Out = bthlink_CreateConnection_Out;`	Not applicable
6. Establish a connection from the extension layer to the HCI layer by calling the HCI_EstablishDeviceContext function. On registration, the extension layer establishes a connection with the HCI layer by supplying a table of events and command completion callbacks. A function table is received for the HCI layer. BthLink calls HCI_EstablishDeviceContext in the class constructor. The following code example shows how BthLink calls HCI_EstablishDeviceContext. `HANDLE hHCI; HCI_INTERFACE hci_if; HCI_EstablishDeviceContext (this, BTH_CONTROL_DEVICEONLY, NULL, 0, 0, &hei, &hc, &hci_if, &cHciHeaders, &cHciTrailers, &hHCI)` > [!NOTE] > BthLink passes BTH_CONTROL_DEVICEONLY in the call to HCI_EstablishDeviceContext to route all local device control packets.	Establishing Connections through HCI. Registering and Deregistering the Extension Layer
7. Close the existing connection to the HCI layer by calling the HCI_CloseDeviceContext function and pass the handle instance created by HCI_EstablishDeviceContext. BthLink calls HCI_CloseDeviceContext in the class destructor. The following code example shows how BthLink calls HCI_CloseDeviceContext. `HCI_CloseDeviceContext (hHCI);`	Closing Connections through HCI Registering and Deregistering the Extension Layer
8. Write functions to initialize, instantiate, deinitialize, and delete the extension layer. Implement the following functions: Extensionlayer_InitializeOnce Extensionlayer_UninitializeOnce Extensionlayer_CreateDriverInstance Extensionlayer_CloseDriverInstance	Setting Up and Shutting Down a Bluetooth Extension Layer
9. Create an installable stream device driver for the extension layer so that it can be installed on top of the HCI layer by using the following common functions: driver_Init driver_Deinit driver_Read driver_Write driver_Open driver_Close driver_IOControl driver_Seek driver_PowerUp driver_PowerDown	Creating an Installable Stream Driver for the Bluetooth Extension Layer
10. Load the extension layer from the application by using the following functions: RegisterDevice CreateFile	Loading a Bluetooth Extension Layer

1. Implement the required commands that the extension layer must support.

HCI Commands

Implementing Commands, Callbacks, and Events Handlers for an Extension Layer

2. Implement the required HCI event handlers and the HCI callback functions.

For example, the sample BthLink implements:

The HCI_ConnectionCompleteEvent event in the bthlink_ConnectionCompleteEvent handler to notify the HCI layer and the peer device that the connection has been established.
The command complete callback function for the HCI_CreateConnection command in the bthlink_CreateConnection_Out function to create a connection between the HCI layer and the peer Bluetooth device.

HCI Events

HCI Callbacks

Implementing Commands, Callbacks, and Events Handlers for an Extension Layer

3. Declare function pointers to the event handler and callback functions created in step 2 and for the commands that the extension layer implements.

The following code example shows function pointer declarations for bthlink_ConnectionCompleteEvent and bthlink_CreateConnection_Out declared in the BthLink sample.

static int  bthlink_ConnectionCompleteEvent(
  void *pUserContext, 
  void *pCallContext, 
  unsigned char status, 
  unsigned short connection_handle, 
  BD_ADDR *pba, 
  unsigned char link_type, 
  unsigned char encryption_mode);
static int bthlink_CreateConnection_Out(
  void *pCallContext, 
  unsigned char status);

Implementing Commands, Callbacks, and Events Handlers for an Extension Layer

4. Create a class to implement the Bluetooth stack extension layer.

The BthLink sample creates a class named bthlink. This class is derived from SVSSynch and SVSRefObj, and is defined in svsutil.hxx to inherit the built-in multi threaded functionality.

Not applicable

5. Register the extension layer event handlers and the callback functions with the HCI layer.

The following code example is an excerpt from the BthLink class constructor that registers bthlink_ConnectionCompleteEvent and bthlink_CreateConnection_Out with the HCI layer.

HCI_EVENT_INDICATION hei;
HCI_CALLBACKS hc;
hei.hci_ConnectionCompleteEvent = 
bthlink_ConnectionCompleteEvent;
hc.hci_CreateConnection_Out = 
bthlink_CreateConnection_Out;

Not applicable

6. Establish a connection from the extension layer to the HCI layer by calling the HCI_EstablishDeviceContext function.

On registration, the extension layer establishes a connection with the HCI layer by supplying a table of events and command completion callbacks. A function table is received for the HCI layer.

BthLink calls HCI_EstablishDeviceContext in the class constructor. The following code example shows how BthLink calls HCI_EstablishDeviceContext.

HANDLE hHCI;
HCI_INTERFACE hci_if;
HCI_EstablishDeviceContext (this,
  BTH_CONTROL_DEVICEONLY, NULL, 0, 0, 
  &hei, &hc, &hci_if, &cHciHeaders, 
  &cHciTrailers, &hHCI)

> [!NOTE] > BthLink passes BTH_CONTROL_DEVICEONLY in the call to HCI_EstablishDeviceContext to route all local device control packets.

Establishing Connections through HCI.

Registering and Deregistering the Extension Layer

7. Close the existing connection to the HCI layer by calling the HCI_CloseDeviceContext function and pass the handle instance created by HCI_EstablishDeviceContext.

BthLink calls HCI_CloseDeviceContext in the class destructor. The following code example shows how BthLink calls HCI_CloseDeviceContext.

HCI_CloseDeviceContext (hHCI);

Closing Connections through HCI

Registering and Deregistering the Extension Layer

8. Write functions to initialize, instantiate, deinitialize, and delete the extension layer.

Implement the following functions:

Extensionlayer_InitializeOnce
Extensionlayer_UninitializeOnce
Extensionlayer_CreateDriverInstance
Extensionlayer_CloseDriverInstance

Setting Up and Shutting Down a Bluetooth Extension Layer

9. Create an installable stream device driver for the extension layer so that it can be installed on top of the HCI layer by using the following common functions:

driver_Init
driver_Deinit
driver_Read
driver_Write
driver_Open
driver_Close
driver_IOControl
driver_Seek
driver_PowerUp
driver_PowerDown

Creating an Installable Stream Driver for the Bluetooth Extension Layer

10. Load the extension layer from the application by using the following functions:

Loading a Bluetooth Extension Layer

Share via

How to Develop and Load a Bluetooth HCI Stack Extension Layer

Steps

See Also

Other Resources

Additional resources