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 支援。 |
| 目標平台 | Universal |
| 標頭 | bluetoothleapis.h |
| 程式庫 | BluetoothAPIs.lib |
| Dll | BluetoothAPIs.dll |