BluetoothGATTGetDescriptorValue function (bluetoothleapis.h)

Article
10/13/2021

The BluetoothGATTGetDescriptorValue function gets the value of the specified descriptor.

Syntax

HRESULT BluetoothGATTGetDescriptorValue(
  [in]            HANDLE                        hDevice,
  [in]            PBTH_LE_GATT_DESCRIPTOR       Descriptor,
  [in]            ULONG                         DescriptorValueDataSize,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR_VALUE DescriptorValue,
  [out, optional] USHORT                        *DescriptorValueSizeRequired,
  [in]            ULONG                         Flags
);

Parameters

[in] hDevice

Handle to the service.

[in] Descriptor

Pointer to BTH_LE_GATT_DESCRIPTOR structure containing the parent descriptor of the descriptor value to be retrieved.

[in] DescriptorValueDataSize

The number of bytes allocated for the DescriptorValue parameter.

[out, optional] DescriptorValue

Pointer to BTH_LE_GATT_DESCRIPTOR_VALUE structure into which to return the descriptor value.

[out, optional] DescriptorValueSizeRequired

Pointer to buffer into which to store the number of additional bytes needed to return data in the buffer pointed to by DescriptorValue.

[in] Flags

Flags to modify the behavior of BluetoothGATTGetDescriptorValue:

Flag	Description
BLUETOOTH_GATT_FLAG_NONE	The client does not have specific GATT requirements (default).
BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED	The client requests the data to be transmitted over an encrypted channel.
BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED	The client requests the data to be transmitted over an authenticated channel.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE	The descriptor value is to be read directly from the device. This overwrites the one in the cache if one is already present.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE	The descriptor value is to be read from the cache (regardless of whether it is present in the cache or not).

Return value

The BluetoothGATTGetDescriptorValue 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	Both DescriptorValue and DescriptorValueSizeRequired are 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	A descriptor value was specified to be retrieved from the cache, but the descriptor value is not present in the cache.
ERROR_BAD_COMMAND	The current data in the cache appears to be inconsistent, and is leading to internal errors.
ERROR_BAD_NET_RESP	The target server did not provide an appropriate network response.
ERROR_SEM_TIMEOUT	The request timed-out.
ERROR_NO_SYSTEM_RESOURCES	The operation ran out of memory.
E_BLUETOOTH_ATT_INVALID_HANDLE	The attribute handle given was not valid on this server.
E_BLUETOOTH_ATT_READ_NOT_PERMITTED	The attribute cannot be read.
E_BLUETOOTH_ATT_WRITE_NOT_PERMITTED	The attribute cannot be written.
E_BLUETOOTH_ATT_INVALID_PDU	The attribute PDU was invalid.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHENTICATION	The attribute requires authentication before it can be read or written.
E_BLUETOOTH_ATT_REQUEST_NOT_SUPPORTED	Attribute server does not support the request received from the client.
E_BLUETOOTH_ATT_INVALID_OFFSET	Offset specified was past the end of the attribute.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHORIZATION	The attribute requires authorization before it can be read or written.
E_BLUETOOTH_ATT_PREPARE_QUEUE_FULL	Too many prepare writes have been queued.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_FOUND	No attribute found within the given attribute handle range.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_LONG	The attribute cannot be read or written using the Read Blob Request.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE	The Encryption Key Size used for encrypting this link is insufficient.
E_BLUETOOTH_ATT_INVALID_ATTRIBUTE_VALUE_LENGTH	The attribute value length is invalid for the operation.
E_BLUETOOTH_ATT_UNLIKELY	The attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION	The attribute requires encryption before it can be read or written.
E_BLUETOOTH_ATT_UNSUPPORTED_GROUP_TYPE	The attribute type is not a supported grouping attribute as defined by a higher layer specification.
E_BLUETOOTH_ATT_INSUFFICIENT_RESOURCES	Insufficient Resources to complete the request.
E_BLUETOOTH_ATT_UNKNOWN_ERROR	An error that lies in the reserved range has been received.

Remarks

The descriptor value is returned from the cache if one is already present. This would be the case most of the time, as all the device attributes are cached at the time of pairing or association. However, if it is not present, the descriptor value is read directly from the device, and will be cached upon successfully reading it from the device. If BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE or BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE is present, the descriptor value is read using the specified method.

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

Profile drivers should pre-allocate a sufficiently large buffer for the array of descriptor values to be returned in. Callers can determine the necessary buffer size by passing a non-NULL value in DescriptorValueSizeRequired and NULL in DescriptorValue.

The parent service must be present in the cache, otherwise the function will fail. The parent service must be a service returned by either BluetoothGATTGetServices or BluetoothGATTGetIncludedServices.

Example


////////////////////////////////////////////////////////////////////////////
// Determine Descriptor Value Buffer Size
////////////////////////////////////////////////////////////////////////////
                hr = BluetoothGATTGetDescriptorValue(
                        hCurrService,
                        currGattDescriptor,
                        0,
                        NULL,
                        &descValueDataSize,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                    PrintHr("BluetoothGATTGetDescriptorValue - Buffer Size", hr);
                    goto Done; // allow continuation
                }

                pDescValueBuffer = (PBTH_LE_GATT_DESCRIPTOR_VALUE)malloc(descValueDataSize);

                if (NULL == pDescValueBuffer) {
                    printf("pDescValueBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pDescValueBuffer, descValueDataSize);
                }

////////////////////////////////////////////////////////////////////////////
// Retrieve the Descriptor Value
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetDescriptorValue(
                        hCurrService,
                        currGattDescriptor,
                        (ULONG)descValueDataSize,
                        pDescValueBuffer,
                        NULL,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetDescriptorValue - Actual Data", hr);
                    goto Done; // allow continuation
                }

Requirements

Requirement	Value
Minimum supported client	Supported in Windows 8 and later versions of Windows.
Target Platform	Universal
Header	bluetoothleapis.h
Library	BluetoothAPIs.lib
DLL	BluetoothAPIs.dll