How to Develop and Load a Bluetooth HCI Stack Extension Layer (Windows Embedded CE 6.0)

1/6/2010

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

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)
Ee495460.note(en-US,WinEmbedded.60).gifNote:
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

See Also

Other Resources

Host Controller Interface
Bluetooth OS Design Development