BluetoothGATTGetServices function

The BluetoothGATTGetServices function gets all the primary services available for a server.

Syntax

HRESULT BluetoothGATTGetServices(
  HANDLE               hDevice,
  USHORT               ServicesBufferCount,
  PBTH_LE_GATT_SERVICE ServicesBuffer,
  USHORT               *ServicesBufferActual,
  ULONG                Flags
);

Parameters

hDevice

Handle to the Bluetooth device from which to obtain the list of primary services.

ServicesBufferCount

The number of elements allocated for the ServicesBuffer parameter.

ServicesBuffer

Pointer to buffer containing a BTH_LE_GATT_SERVICE structure into which to return services.

ServicesBufferActual

Pointer to buffer into which the actual number of services were returned in the ServicesBuffer parameter.

Flags

Flags to modify the behavior of BluetoothGATTGetServices:

Flag Description
BLUETOOTH_GATT_FLAG_NONE The client does not have specific GATT requirements (default).

Return Value

This function returns the following values:

Return code Description
S_OK
The operation completed successfully.
ERROR_MORE_DATA
The buffer parameter is NULL and the number of items available is being returned instead.
ERROR_ACCESS_DENIED
Returned if both a parent service and a service handle are provided and the service hierarchy does not roll up to the provided parent service handle.
ERROR_INVALID_PARAMETER
One of the following conditions occurred:
  • ServicesBuffer is NULL, and ServicesBufferCount is 0
  • ServicesBuffer is non-NULL, but ServicesBufferCount is NULL
  • ServicesBuffer is non-NULL, and ServicesBufferCount is 0
ERROR_INVALID_USER_BUFFER
A buffer is specified, but the buffer count size is smaller than what is required, in bytes.
ERROR_INVALID_FUNCTION
Services were specified to be retrieved from the cache, but no services are present in the cache.
ERROR_BAD_COMMAND
The current data in the cache appears to be inconsistent, and is leading to internal errors.
ERROR_NO_SYSTEM_RESOURCES
The operation ran out of memory.

Remarks

Returned services are cached upon successful retrieval of services from the device directly. Unless a service-change event is received, the list of returned services is not expected to change.

Profile drivers should pre-allocate a sufficiently large buffer for the array of primary services to be returned in. Callers can determine the necessary buffer size by passing a non-NULL value in ServicesBufferActual and NULL in ServicesBuffer.

Do not modify the returned service structure, and then use the modified structure in subsequent function calls. Behavior is undefined if the caller does this.

Example

C++
////////////////////////////////////////////////////////////////////////////
// Determine Services Buffer Size
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetServices(
        hLEDevice,
        0,
        NULL,
        &serviceBufferCount,
        BLUETOOTH_GATT_FLAG_NONE);

if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
    PrintHr("BluetoothGATTGetServices - Buffer Size", hr);
    goto Done;
}

pServiceBuffer = (PBTH_LE_GATT_SERVICE)
        malloc(sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);

if (NULL == pServiceBuffer) {
    printf("pServiceBuffer out of memory\r\n");
    goto Done;
} else {
    RtlZeroMemory(pServiceBuffer, 
            sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);
}

//////////////////////////////////////////////////////////////////////////// // Retrieve Services ////////////////////////////////////////////////////////////////////////////

hr = BluetoothGATTGetServices(
        hLEDevice,
        serviceBufferCount,
        pServiceBuffer,
        &numServices,
        BLUETOOTH_GATT_FLAG_NONE);

if (S_OK != hr) {
    PrintHr("BluetoothGATTGetServices - Actual Data", hr);
    goto Done;
}

Requirements

   
Windows version Supported in Windows 8 and later versions of Windows.
Target Platform Universal
Header bluetoothleapis.h
Library BluetoothAPIs.lib
DLL BluetoothAPIs.dll

See Also

BTH_LE_GATT_SERVICE