bluetoothGATTGetDescriptorValue 函数 (bluetoothleapis.h)
BluetoothGATTGetDescriptorValue 函数获取指定描述符的值。
语法
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
);
参数
[in] hDevice
服务的句柄。
[in] Descriptor
指向 BTH_LE_GATT_DESCRIPTOR 结构的指针，该结构包含要检索的描述符值的父描述符。
[in] DescriptorValueDataSize
为 DescriptorValue 参数分配的字节数。
[out, optional] DescriptorValue
指向 BTH_LE_GATT_DESCRIPTOR_VALUE 结构（要在其中返回描述符值）的指针。
[out, optional] DescriptorValueSizeRequired
指向缓冲区的指针，用于存储 DescriptorValue 指向的缓冲区中返回数据所需的其他字节数。
[in] Flags
用于修改 BluetoothGATTGetDescriptorValue 行为的标志：
| 标志 | 描述 |
|---|---|
| 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 | 无论它是否存在于缓存中) ，都将从缓存 (读取描述符值。 |
返回值
BluetoothGATTGetDescriptorValue 函数返回以下值：
| 返回代码 | 说明 |
|---|---|
|
操作已成功完成。 |
|
缓冲区参数为 NULL ，将改为返回可用项数。 |
|
如果同时提供了父服务和服务句柄，并且服务层次结构不汇总到提供的父服务句柄，则返回 。 |
|
DescriptorValue 和 DescriptorValueSizeRequired 均为 0。 |
|
指定了缓冲区，但缓冲区计数大小小于所需的大小（以字节为单位）。 |
|
指定了要从缓存中检索的描述符值，但缓存中不存在描述符值。 |
|
缓存中的当前数据似乎不一致，并导致内部错误。 |
|
目标服务器未提供适当的网络响应。 |
|
请求超时。 |
|
操作内存不足。 |
|
给定的属性句柄在此服务器上无效。 |
|
无法读取属性。 |
|
无法写入特性。 |
|
属性 PDU 无效。 |
|
属性需要身份验证，然后才能读取或写入该属性。 |
|
属性服务器不支持从客户端收到的请求。 |
|
指定的偏移量超过属性的末尾。 |
|
属性需要授权才能读取或写入。 |
|
太多准备写入已排队。 |
|
在给定的属性句柄范围内找不到任何属性。 |
|
不能使用读取 Blob 请求读取或写入属性。 |
|
用于加密此链接的加密密钥大小不足。 |
|
属性值长度对于操作无效。 |
|
请求的属性请求遇到不太可能的错误，因此无法按请求完成。 |
|
属性需要加密，然后才能读取或写入该属性。 |
|
属性类型不是更高层规范所定义的受支持的分组属性。 |
|
资源不足，无法完成请求。 |
|
已收到位于保留范围内的错误。 |
注解
描述符值从缓存中返回（如果已存在）。 大多数情况下都是这种情况，因为所有设备属性都在配对或关联时缓存。 但是，如果不存在，则直接从设备读取描述符值，并在从设备成功读取后缓存它。 如果 存在BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE 或 BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE ，则使用指定的方法读取描述符值。
直接从设备成功检索描述符值后，将缓存返回的描述符值。 除非收到服务更改事件，否则描述符值不会更改。
配置文件驱动程序应为要返回的描述符值数组预先分配足够大的缓冲区。 调用方可以通过在 DescriptorValueSizeRequired 中传递非 NULL 值和 DescriptorValue 中的 NULL 值来确定必要的缓冲区大小。
父服务必须存在于缓存中，否则函数将失败。 父服务必须是 BluetoothGATTGetServices 或 BluetoothGATTGetIncludedServices 返回的服务。
示例
////////////////////////////////////////////////////////////////////////////
// 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
}
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | 在 Windows 8 及更高版本的 Windows 中受支持。 |
| 目标平台 | 通用 |
| 标头 | bluetoothleapis.h |
| Library | BluetoothAPIs.lib |
| DLL | BluetoothAPIs.dll |