BluetoothGATTGetDescriptors 函式 (bluetoothleapis.h)

BluetoothGATTGetDescriptors 函式會取得指定特性可用的所有描述項。

語法

HRESULT BluetoothGATTGetDescriptors(
  [in]            HANDLE                      hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC Characteristic,
  [in]            USHORT                      DescriptorsBufferCount,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR     DescriptorsBuffer,
  [out]           USHORT                      *DescriptorsBufferActual,
  [in]            ULONG                       Flags
);

參數

[in] hDevice

藍牙裝置或服務的句柄。 如果傳遞服務句柄，則服務必須是描述項的父系。

[in] Characteristic

BTH_LE_GATT_CHARACTERISTIC結構的指標，其中包含要擷取之描述元的父特性。

[in] DescriptorsBufferCount

為 DescriptorsBuffer 參數配置的元素數目。

[out, optional] DescriptorsBuffer

緩衝區的指標，其中包含要傳回描述項 的BTH_LE_GATT_DESCRIPTOR 結構。

[out] DescriptorsBufferActual

緩衝區的指標，描述項的實際數目是在 DescriptorsBuffer 參數中傳回的。

[in] Flags

用來修改 BluetoothGATTGetDescriptors 行為的旗標：

旗標	描述
BLUETOOTH_GATT_FLAG_NONE	客戶端沒有特定的 GATT 需求， (預設) 。

傳回值

此函式會傳回下列值：

傳回碼	描述
S_OK	作業已成功完成。
ERROR_MORE_DATA	緩衝區參數為 NULL，並改為傳回可用的項目數目。
ERROR_ACCESS_DENIED	如果同時提供父服務和服務句柄，而且服務階層不會匯總至提供的父服務句柄，則傳回 。
ERROR_INVALID_PARAMETER	發生下列其中一個情況： DescriptorsBuffer 為 NULL，而 DescriptorsBufferCount 為 0。 DescriptorsBuffer 為非 NULL，但 DescriptorsBufferCount 為 NULL。 DescriptorsBuffer 為非 NULL，而 DescriptorsBufferCount 為 0。
ERROR_INVALID_USER_BUFFER	指定緩衝區，但緩衝區計數大小小於所需的位元組大小。
ERROR_BAD_COMMAND	快取中的目前數據似乎不一致，而且會導致內部錯誤。
ERROR_NO_SYSTEM_RESOURCES	作業記憶體不足。

備註

從裝置成功擷取特性時，會快取傳回的特性。 除非收到服務變更事件，否則傳回的特性清單預期不會變更。

配置檔驅動程式應該預先配置夠大的緩衝區，以便傳回特性陣列。 呼叫端可以在 DescriptorsBufferActual 中傳遞非 NULL 值，並在 DescriptorsBuffer 中傳遞 NULL，以判斷必要的緩衝區大小。

請勿修改傳回的特性結構，然後在後續的函數調用中使用修改過的結構。 如果呼叫端執行此動作，則行為是未定義的。

父特性必須存在於快取中，否則函式將會失敗。 父服務必須是 BluetoothGATTGetServices 或 BluetoothGATTGetIncludedServices 所傳回的服務。

範例

////////////////////////////////////////////////////////////////////////////
// Determine Descriptor Buffer Size
////////////////////////////////////////////////////////////////////////////
GetDescriptors:
            hr = BluetoothGATTGetDescriptors(
                    hCurrService,
                    currGattChar,
                    0,
                    NULL,
                    &descriptorBufferSize,
                    BLUETOOTH_GATT_FLAG_NONE);
            
            if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                PrintHr("BluetoothGATTGetDescriptors - Buffer Size", hr);
                goto Done; // Allow continuation
            }
            
            if (descriptorBufferSize > 0) {
                pDescriptorBuffer = (PBTH_LE_GATT_DESCRIPTOR)
                        malloc(descriptorBufferSize 
                            * sizeof(BTH_LE_GATT_DESCRIPTOR));
            
                if (NULL == pDescriptorBuffer) {
                    printf("pDescriptorBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pDescriptorBuffer, descriptorBufferSize);
                }
            
////////////////////////////////////////////////////////////////////////////
// Retrieve Descriptors
////////////////////////////////////////////////////////////////////////////
    
                hr = BluetoothGATTGetDescriptors(
                        hCurrService,
                        currGattChar,
                        descriptorBufferSize,
                        pDescriptorBuffer,
                        &numDescriptors,
                        BLUETOOTH_GATT_FLAG_NONE);
            
                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetDescriptors - Actual Data", hr);
                    goto Done;
                }

                if (numDescriptors != descriptorBufferSize) {
                    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_DESCRIPTOR