bluetoothGATTGetDescriptors 函数 (bluetoothleapis.h)

BluetoothGATTGetDescriptors 函数获取可用于指定特征的所有描述符。

语法

HRESULT BluetoothGATTGetDescriptors(
  [in]            HANDLE                      hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC Characteristic,
  [in]            USHORT                      DescriptorsBufferCount,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR     DescriptorsBuffer,
  [out]           USHORT                      *DescriptorsBufferActual,
  [in]            ULONG                       Flags
);

参数

[in] hDevice

蓝牙设备或服务的句柄。 如果传递了服务句柄，则该服务必须是描述符的祖父级。

[in] Characteristic

指向包含要检索的描述符的父特征的 BTH_LE_GATT_CHARACTERISTIC 结构的指针。

[in] DescriptorsBufferCount

为 DescriptorsBuffer 参数分配的元素数。

[out, optional] DescriptorsBuffer

指向包含要返回描述符 的BTH_LE_GATT_DESCRIPTOR 结构的缓冲区的指针。

[out] DescriptorsBufferActual

指向在 DescriptorsBuffer 参数中返回实际数量的描述符的缓冲区的指针。

[in] Flags

用于修改 BluetoothGATTGetDescriptors 行为的标志：

标志	描述
BLUETOOTH_GATT_FLAG_NONE	客户端没有特定的 GATT 要求 (默认) 。

返回值

此函数返回以下值：

返回代码	说明
S_OK	操作已成功完成。
ERROR_MORE_DATA	buffer 参数为 NULL，将改为返回可用项数。
ERROR_ACCESS_DENIED	如果同时提供了父服务和服务句柄，并且服务层次结构不汇总到提供的父服务句柄，则返回 。
ERROR_INVALID_PARAMETER	出现以下情况之一： DescriptorsBuffer 为 NULL，DescriptorsBufferCount 为 0。 DescriptorsBuffer 为非 NULL，但 DescriptorsBufferCount 为 NULL。 DescriptorsBuffer 为非 NULL，DescriptorsBufferCount 为 0。
ERROR_INVALID_USER_BUFFER	指定了缓冲区，但缓冲区计数大小小于所需的大小（以字节为单位）。
ERROR_BAD_COMMAND	缓存中的当前数据似乎不一致，并导致内部错误。
ERROR_NO_SYSTEM_RESOURCES	操作内存不足。

注解

直接从设备成功检索特征后，将缓存返回的特征。 除非收到服务更改事件，否则返回的特征列表预期不会更改。

配置文件驱动程序应为要返回的特征数组预先分配足够大的缓冲区。 调用方可以通过在 DescriptorsBufferActual 中传递非 NULL 值和在 DescriptorsBuffer 中传递 NULL 来确定必要的缓冲区大小。

请勿修改返回的特征结构，然后在后续函数调用中使用修改后的 结构。 如果调用方执行此操作，则行为未定义。

父特征必须存在于缓存中，否则函数将失败。 父服务必须是 BluetoothGATTGetServices 或 BluetoothGATTGetIncludedServices 返回的服务。

示例

////////////////////////////////////////////////////////////////////////////
// Determine Descriptor Buffer Size
////////////////////////////////////////////////////////////////////////////
GetDescriptors:
            hr = BluetoothGATTGetDescriptors(
                    hCurrService,
                    currGattChar,
                    0,
                    NULL,
                    &descriptorBufferSize,
                    BLUETOOTH_GATT_FLAG_NONE);
            
            if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                PrintHr("BluetoothGATTGetDescriptors - Buffer Size", hr);
                goto Done; // Allow continuation
            }
            
            if (descriptorBufferSize > 0) {
                pDescriptorBuffer = (PBTH_LE_GATT_DESCRIPTOR)
                        malloc(descriptorBufferSize 
                            * sizeof(BTH_LE_GATT_DESCRIPTOR));
            
                if (NULL == pDescriptorBuffer) {
                    printf("pDescriptorBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pDescriptorBuffer, descriptorBufferSize);
                }
            
////////////////////////////////////////////////////////////////////////////
// Retrieve Descriptors
////////////////////////////////////////////////////////////////////////////
    
                hr = BluetoothGATTGetDescriptors(
                        hCurrService,
                        currGattChar,
                        descriptorBufferSize,
                        pDescriptorBuffer,
                        &numDescriptors,
                        BLUETOOTH_GATT_FLAG_NONE);
            
                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetDescriptors - Actual Data", hr);
                    goto Done;
                }

                if (numDescriptors != descriptorBufferSize) {
                    printf("buffer size and buffer size actual size mismatch\r\n");
                    goto Done;
                }
            }

要求

要求	值
最低受支持的客户端	在 Windows 8 及更高版本的 Windows 中受支持。
目标平台	通用
标头	bluetoothleapis.h
Library	BluetoothApis.lib
DLL	BluetoothAPIs.dll

另请参阅

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_DESCRIPTOR