Handling Events from the Bluetooth Stack

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This topic provides information about how an application can receive event notifications from the Bluetooth stack in a message queue.

Event Classes and Event Types

The Bluetooth Protocol Stack defines a variety of events for communicating with Bluetooth applications. These events, and the event classes into which they are divided, are defined in the file bt_api.h. Some of these events are the result of an asynchronous function call into the Bluetooth stack by the application, and some are the result of interactions with the peer Bluetooth device.

All Bluetooth events are communicated to the application in the form of the BTEVENT structure using a message queue. This structure includes the members dwEventId, which identifies which Bluetooth event has occurred, and baEventData, which contains the data that is specific to that event.

For example, at the conclusion of Secure Simple Pairing (SSP), the stack populates a BTEVENT structure with its dwEventId member set to BTE_SSP_PAIRING_COMPLETE and its baEventData structure set as a BT_SSP_PAIRING_COMPLETE_EVENT structure. The Status member of the BT_SSP_PAIRING_COMPLETE_EVENT structure communicates whether the SSP attempt was successful. **

The following table lists each event class and its associated event types.

Handling Stack Events using a Message Queue

The application on the peer Bluetooth device must set up a message queue to receive the event class from the Bluetooth stack. With message queues, the application listening for stack events can subscribe to specific events and does not miss any signaled events. Along with the events, the stack also sends data that offsets the need for the application to call back into the stack to get information about the events. To setup a message queue, the application must configure the MSGQUEUEOPTIONS structure and create a message queue by calling the CreateMsgQueue function.

The following code example shows how to create a message queue:

HANDLE hMsgQ = CreateMsgQueue(NULL, &mqOptions);
if (! hMsgQ) {
wprintf(L"Error creating message queue.\r\n");
goto exit;
}

To start receiving notification from the stack, the application on the peer Bluetooth device must call the RequestBluetoothNotifications function. A call to this function enables the application to register for a specific event class and receive notifications from the stack for only these events. When you call this function, in the dwClass parameter specify a bitmask for the event class that you want to register. The following example code shows how an application calls this function.

HANDLE hBTNotif = RequestBluetoothNotifications(
                                BTE_CLASS_CONNECTIONS | 
                                BTE_CLASS_DEVICE | 
                                BTE_CLASS_PAIRING | 
                                BTE_CLASS_STACK | 
                                BTE_CLASS_SERVICE, hMsgQ);

In the preceding example, the application calls RequestBluetoothNotifications to register for all of the Bluetooth event classes. These event classes include events that signal changes in the core stack, connection (including service connection), pairing, and local device. In the hMsgQ parameter, specify the message queue by passing a handle to the queue.

When an event is raised, the stack places BTEVENT in the message queue by using the handle to the queue passed to it by the application. The application must read the message queue by using the ReadMsgQueue function, which receives the event in a BTEVENT structure. Event data is received in the baEventData member of BTEVENT and can be used to populate structures that contain information specific to an event. To store information about specific events, an application can use the following additional structures, which are defined in bt_api.h:

BT_CONNECT_EVENT

BT_DISCONNECT_EVENT

BT_ROLE_SWITCH_EVENT

BT_MODE_CHANGE_EVENT

BT_LINK_KEY_EVENT

BT_AVDTP_STATE_CHANGE

BT_SERVICE_REQUEST

The following code example shows how to call the ReadMsgQueue to read the queue:

BOOL fRet = ReadMsgQueue (hMsgQ, &btEvent, sizeof(BTEVENT), &dwBytesRead, 10, &dwFlags);
if (! fRet) 
{
  wprintf(L"Error - Failed to read message from queue!\r\n");
  goto exit;
} 
else 
{
  wprintf(L"----------------------------------------\r\n");
  wprintf(L"Got event with id=%d.\r\n", btEvent.dwEventId);
  DumpBuff(L"", btEvent.baEventData, sizeof(btEvent.baEventData));
  ParseEvent(&btEvent);
}

To terminate Bluetooth event notifications, call the StopBluetoothNotifications function and specify the handle returned by RequestBluetoothNotifications as a parameter.

The following example code shows how to call StopBluetoothNotifications.

StopBluetoothNotifications(hBTNotif);

The BtNotify sample, which ships with Windows Mobile, contains source code for handling stack events using message queues. **

See Also

Other Resources

Bluetooth Application Development
MSMQ Application Development