bluetoothGATTGetCharacteristics 函数 (bluetoothleapis.h)

BluetoothGATTGetCharacteristics 函数获取可用于指定服务的所有特征。

语法

HRESULT BluetoothGATTGetCharacteristics(
  [in]            HANDLE                      hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE        Service,
  [in]            USHORT                      CharacteristicsBufferCount,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC CharacteristicsBuffer,
  [out]           USHORT                      *CharacteristicsBufferActual,
  [in]            ULONG                       Flags
);

参数

[in] hDevice

蓝牙设备或服务的句柄。

[in, optional] Service

包含要检索的包含服务的父服务的 BTH_LE_GATT_SERVICE 结构的地址。 如果将设备句柄传递给 hDevice，则此参数是必需的。 如果将服务句柄传递给 hDevice，则此参数是可选的，在这种情况下，服务句柄指定的服务将被视为父级。

[in] CharacteristicsBufferCount

为 CharacteristicsBuffer 参数分配的元素数。

[out, optional] CharacteristicsBuffer

指向缓冲区的指针，该缓冲区以 BTH_LE_GATT_CHARACTERISTIC 结构数组的形式返回特征。

[out] CharacteristicsBufferActual

指向缓冲区的指针，其中返回了 在 CharacteristicsBuffer 参数中返回的实际特征数。

[in] Flags

用于修改 BluetoothGATTGetCharacteristics 行为的标志：

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

返回值

此函数返回以下值：

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

注解

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

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

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

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

示例

////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Buffer Size
////////////////////////////////////////////////////////////////////////////

        hr = BluetoothGATTGetCharacteristics(
                hCurrService,
                currGattService,
                0,
                NULL,
                &charBufferSize,
                BLUETOOTH_GATT_FLAG_NONE);
        
        if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
            PrintHr("BluetoothGATTGetCharacteristics - Buffer Size", hr);
            goto Done;
        }
        
        if (charBufferSize > 0) {
            pCharBuffer = (PBTH_LE_GATT_CHARACTERISTIC)
                    malloc(charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
        
            if (NULL == pCharBuffer) {
                printf("pCharBuffer out of memory\r\n");
                goto Done;
            } else {
                RtlZeroMemory(pCharBuffer, 
                        charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
            }

////////////////////////////////////////////////////////////////////////////
// Retrieve Characteristics
////////////////////////////////////////////////////////////////////////////
    
            hr = BluetoothGATTGetCharacteristics(
                    hCurrService,
                    currGattService,
                    charBufferSize,
                    pCharBuffer,
                    &numChars,
                    BLUETOOTH_GATT_FLAG_NONE);

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

            if (numChars != charBufferSize) {
                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_SERVICE