bluetoothGATTGetCharacteristicValue 函数 (bluetoothleapis.h)

项目
02/26/2024

BluetoothGATTGetCharacteristicValue 函数获取指定特征的值。

语法

HRESULT BluetoothGATTGetCharacteristicValue(
  [in]            HANDLE                            hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC       Characteristic,
  [in]            ULONG                             CharacteristicValueDataSize,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC_VALUE CharacteristicValue,
  [out, optional] USHORT                            *CharacteristicValueSizeRequired,
  [in]            ULONG                             Flags
);

参数

[in] hDevice

服务的句柄。

[in] Characteristic

指向要检索的特征值的父特征的指针。

[in] CharacteristicValueDataSize

为 CharacteristicValue 参数分配的字节数。

[out, optional] CharacteristicValue

指向要在其中返回特征值的缓冲区的指针。

[out, optional] CharacteristicValueSizeRequired

指向缓冲区的指针，该缓冲区存储返回 由 CharacteristicValue 指向的缓冲区中的数据所需的字节数。

[in] Flags

用于修改 BluetoothGATTGetCharacteristicValue 行为的标志：

标志	描述
BLUETOOTH_GATT_FLAG_NONE	客户端没有特定的 GATT 要求 (默认) 。
BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED	客户端请求通过加密通道传输数据。
BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED	客户端请求通过经过身份验证的通道传输数据。
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE	特征值是直接从设备读取。这会覆盖缓存中的缓存（如果已存在）。
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE	无论其是否存在于缓存中) 中，特征值都将从缓存 (读取。

返回值

BluetoothGATTGetCharacteristicValue 函数返回以下值：

返回代码	说明
S_OK	操作已成功完成。
ERROR_MORE_DATA	buffer 参数为 NULL，将改为返回可用项数。
ERROR_ACCESS_DENIED	如果同时提供了父服务和服务句柄，并且服务层次结构不汇总到提供的父服务句柄，则返回。
ERROR_INVALID_PARAMETER	CharacteristicValue 和 CharacteristicValueSizeRequired 均为 0。
ERROR_INVALID_USER_BUFFER	指定了缓冲区，但缓冲区计数大小小于所需的大小（以字节为单位）。
ERROR_BAD_COMMAND	缓存中的当前数据似乎不一致，并导致内部错误。
ERROR_BAD_NET_RESP	目标服务器未提供适当的网络响应。
ERROR_SEM_TIMEOUT	请求超时。
ERROR_PRIVILEGE_NOT_HELD	特征值不可读，由特征属性规定。
ERROR_NO_SYSTEM_RESOURCES	操作内存不足。
E_BLUETOOTH_ATT_INVALID_HANDLE	给定的属性句柄在此服务器上无效。
E_BLUETOOTH_ATT_READ_NOT_PERMITTED	无法读取该属性。
E_BLUETOOTH_ATT_WRITE_NOT_PERMITTED	无法写入属性。
E_BLUETOOTH_ATT_INVALID_PDU	属性 PDU 无效。
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHENTICATION	属性需要经过身份验证，然后才能读取或写入该属性。
E_BLUETOOTH_ATT_REQUEST_NOT_SUPPORTED	属性服务器不支持从客户端收到的请求。
E_BLUETOOTH_ATT_INVALID_OFFSET	指定的偏移量超过属性的末尾。
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHORIZATION	属性需要经过授权才能读取或写入。
E_BLUETOOTH_ATT_PREPARE_QUEUE_FULL	太多准备写入已排队。
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_FOUND	在给定的属性句柄范围内找不到任何属性。
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_LONG	不能使用读取 Blob 请求读取或写入属性。
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE	用于加密此链接的加密密钥大小不足。
E_BLUETOOTH_ATT_INVALID_ATTRIBUTE_VALUE_LENGTH	属性值长度对于操作无效。
E_BLUETOOTH_ATT_UNLIKELY	请求的属性请求遇到了不太可能的错误，因此无法按请求完成。
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION	属性需要加密，然后才能读取或写入该属性。
E_BLUETOOTH_ATT_UNSUPPORTED_GROUP_TYPE	属性类型不是由更高层规范定义的支持分组属性。
E_BLUETOOTH_ATT_INSUFFICIENT_RESOURCES	资源不足，无法完成请求。
E_BLUETOOTH_ATT_UNKNOWN_ERROR	收到位于保留范围中的错误。

注解

如果已存在特征值，则从缓存返回特征值。大多数情况下都是这种情况，因为所有设备属性在配对或关联时都会缓存。但是，如果不存在，则直接从设备读取特征值，并在从设备成功读取特征值后缓存它。如果 存在BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE 或 BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE ，则使用指定的方法读取特征值。

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

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

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

示例


            if (currGattChar->IsReadable) {
////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Value Buffer Size
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        0,
                        NULL,
                        &charValueDataSize,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Buffer Size", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                pCharValueBuffer = (PBTH_LE_GATT_CHARACTERISTIC_VALUE)malloc(charValueDataSize);

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

////////////////////////////////////////////////////////////////////////////
// Retrieve the Characteristic Value
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        (ULONG)charValueDataSize,
                        pCharValueBuffer,
                        NULL,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Actual Data", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                PrintCharacteristicValue(pCharValueBuffer, 2, currGattChar->CharacteristicUuid);

                // Free before going to next iteration, or memory leak.
                free(pCharValueBuffer);
                pCharValueBuffer = NULL;
            }

要求

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

另请参阅

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_CHARACTERISTIC_VALUE

通过

bluetoothGATTGetCharacteristicValue 函数 (bluetoothleapis.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源