Handling Events from the Bluetooth Stack (Windows Embedded CE 6.0)

1/6/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 Windows Embedded CE Bluetooth Protocol Stack defines event classes and associated event types, in bt_api.h, that correspond to stack events. When the Bluetooth stack receives an event from a peer Bluetooth device, the stack assigns the event identifier for the associated event in the BTEVENT structure and populates this structure with information about the event. The stack then notifies the application on the peer Bluetooth device by writing the structure to the message queue. For example, if HCI_ConnectionCompleteEvent is raised, the stack populates the BTEVENT structure and sends the notification for the event class BTE_CLASS_CONNECTIONS for the BTE_CONNECTION event type.

For more information about events generated by the HCI layer in the stack, see Windows Embedded CE topic HCI Events.

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, 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, 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

The following code example shows how to call the ReadMsgQueueto 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 Embedded CE, contains source code for handling stack events using message queues.

For more information about this sample, see Windows Embedded CE topic Stack-Events Handling Sample.

See Also

Other Resources

Bluetooth Application Development
MSMQ Application Development