BluetoothGATTGetCharacteristicValue 函式 (bluetoothleapis.h)
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 函式會傳回下列值：
| 傳回碼 | 描述 |
|---|---|
|
作業已成功完成。 |
|
緩衝區參數為 NULL，而且會改為傳回可用的項目數目。 |
|
如果同時提供父服務與服務句柄，且服務階層不會匯總至提供的父服務句柄，則會傳回 。 |
|
AttributeValue 和 CharacteristicValueSizeRequired 都是 0。 |
|
指定緩衝區，但緩衝區計數大小小於位元組所需的大小。 |
|
快取中的目前數據似乎不一致，而且導致內部錯誤。 |
|
目標伺服器未提供適當的網路回應。 |
|
要求逾時。 |
|
特性值無法讀取，因為特性屬性所指定。 |
|
作業記憶體不足。 |
|
指定的屬性句柄在此伺服器上無效。 |
|
無法讀取屬性。 |
|
無法寫入屬性。 |
|
PDU 屬性無效。 |
|
屬性需要驗證，才能讀取或寫入。 |
|
屬性伺服器不支援從用戶端收到的要求。 |
|
指定的位移超過屬性的結尾。 |
|
屬性需要授權，才能讀取或寫入。 |
|
太多準備寫入已排入佇列。 |
|
在指定的屬性句柄範圍內找不到任何屬性。 |
|
屬性無法使用讀取 Blob 要求來讀取或寫入。 |
|
用於加密此連結的加密金鑰大小不足。 |
|
屬性值長度對作業無效。 |
|
所要求的屬性要求發生不太可能的錯誤，因此無法如要求完成。 |
|
屬性需要加密，才能讀取或寫入。 |
|
屬性類型不是由較高層規格所定義的支援群組屬性。 |
|
資源不足，無法完成要求。 |
|
收到位於保留範圍中的錯誤。 |
備註
如果已經有特性值，則會從快取傳回特性值。 這在大部分情況下都是如此，因為所有裝置屬性會在配對或關聯時快取。 不過，如果不存在，特性值會直接從裝置讀取，而且會在從裝置成功讀取時快取。 如果 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 支援。 |
| 目標平台 | Universal |
| 標頭 | bluetoothleapis.h |
| 程式庫 | BluetoothAPIs.lib |
| Dll | BluetoothAPIs.dll |