Bluetooth Application Development Events (Compact 2013)
3/26/2014
This topic provides information about the event notifications that the Bluetooth stack sends in message queues.
Event Classes and Event Types
The Windows Embedded Compact 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 the controller, 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 registered applications by writing the structure to the associated message queue. For example, if HCI_ConnectionCompleteEvent is raised, the stack populates the BTEVENT structure and sends the BTE_CONNECTION event notification to the applications registered for the BTE_CLASS_CONNECTIONS event class.
The following table lists each event class and its associated event types.
Event class |
Class Event IDs |
|---|---|
BTE_CLASS_CONNECTIONS |
|
BTE_CLASS_PAIRING |
|
BTE_CLASS_DEVICE |
|
BTE_CLASS_STACK |
|
BTE_CLASS_AVDTP |
|
BTE_CLASS_PAN |
|
BTE_CLASS_INQUIRY |
|
BTE_CLASS_SSP |
|
BTE_CLASS_SERVICE |
|
Event Data
Some events include data about the event in the BTEVENT.baEventData member.
The following table lists the BTE_CLASS_CONNECTIONS events and their associated structures.
Event ID |
Event Data |
|---|---|
BTE_CONNECTION |
|
BTE_DISCONNECTION |
|
BTE_ROLE_SWITCH |
|
BTE_MODE_CHANGE |
|
BTE_PAGE_TIMEOUT |
None. |
BTE_CONNECTION_AUTH_FAILURE |
None. |
BTE_SSR_EVENT |
The following table lists the BTE_CLASS_PAIRING events and their associated structures.
Event ID |
Event Data |
|---|---|
BTE_KEY_NOTIFY |
|
BTE_KEY_REVOKED |
BT_LINK_KEY_EVENT |
The following table lists the BTE_CLASS_DEVICE events and their associated structures.
Event ID |
Event Data |
|---|---|
BTE_LOCAL_NAME |
None. |
BTE_COD |
None. |
BTE_SCAN_MODE |
The following table lists the BTE_CLASS_STACK events and their associated structures.
Event ID |
Event Data |
|---|---|
BTE_STACK_UP |
None. |
BTE_STACK_DOWN |
None. |
BTE_WINSOCK_UP |
None. |
The following table lists the BTE_CLASS_AVDTP event and its associated structure.
Event ID |
Event Data |
|---|---|
BTE_AVDTP_STATE |
BT_AVDTP_STATE_CHANGE |
The following table lists the BTE_CLASS_PAN event and its associated structure.
Event ID |
Event Data |
|---|---|
BTE_PAN_CONNECTIONS |
BT_PAN_NUM_CONNECTIONS |
The following table lists the BTE_CLASS_INQUIRY events and their associated structures.
Event ID |
Event Data |
|---|---|
BTE_INQUIRY_RESULT |
|
BTE_INQUIRY_COMPLETE |
BT_INQUIRY_RESULT_EVENT |
BTE_INQUIRY_CANCEL |
None. |
All of the BTE_CLASS_SSP events are associated with the BTSSPEvent structure, which will in turn contain one of the structures in the following table.
Event ID |
Event Data |
|---|---|
BTE_SSP_USER_CONFIRMATION_REQUEST |
|
BTE_SSP_USER_PASSKEY_REQUEST |
|
BTE_SSP_PAIRING_COMPLETE |
|
BTE_SSP_USER_PASSKEY_NOTIFICATION |
|
BTE_SSP_KEYPRESS_NOTIFICATION |
|
BTE_SSP_IO_CAPABILITY_REQUEST |
|
BTE_SSP_IO_CAPABILITY_RESPONSE |
|
BTE_SSP_REMOTE_OOB_DATA_REQUEST |
|
BTE_SSP_PIN_CODE_REQUEST |
|
BTE_SSP_IO_CAPABILITY_NOTIFICATION |
|
BTE_SSP_AUTHENTICATION_COMPLETED |
BTE_CLASS_SERVICE
Event ID |
Event Data |
|---|---|
BTE_SERVICE_CONNECTION_REQUEST |
|
BTE_SERVICE_DISCONNECTION_REQUEST |
BT_SERVICE_REQUEST |
BTE_SERVICE_CONNECTION_EVENT |
BT_SERVICE_REQUEST |
BTE_SERVICE_DISCONNECTION_EVENT |
BT_SERVICE_REQUEST |
Handling Stack Events by Using a Message Queue
The application 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. Together with the events, the stack also sends data that offsets the need for the application to call back into the stack for information about the events. To set up 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 must call the RequestBluetoothNotifications function. A call to this function registers the queue for a specific event class or classes. The following example shows how to register for multiple event classes.
HANDLE hBTNotif = RequestBluetoothNotifications(
BTE_CLASS_CONNECTIONS |
BTE_CLASS_DEVICE |
BTE_CLASS_PAIRING |
BTE_CLASS_STACK |
BTE_CLASS_SSP,
hMsgQ);
When an event is raised, the stack puts a BTEVENT structure into the message queue. The application must read the message queue by using the ReadMsgQueue function. This function receives the event in a BTEVENT structure. Event data is received in the baEventData member of BTEVENT.
The following example shows how to call the ReadMsgQueue function to read the queue.
Important
For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.
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 stop receiving Bluetooth event notifications, call the StopBluetoothNotifications function.
For more information about Bluetooth event notifications and message queues, see the Windows Embedded Compact Stack-Events Handling Sample.