共用方式為

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
 緩衝區參數為 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 支援。
目標平台 Universal
標頭 bluetoothleapis.h
程式庫 BluetoothApis.lib
Dll BluetoothApis.dll

另請參閱

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_SERVICE