共用方式為

BluetoothGATTGetServices 函式 (bluetoothleapis.h)

  • 發行項

BluetoothGATTGetServices 函式會取得伺服器可用的所有主要服務。

語法

HRESULT BluetoothGATTGetServices(
  [in]            HANDLE               hDevice,
  [in]            USHORT               ServicesBufferCount,
  [out, optional] PBTH_LE_GATT_SERVICE ServicesBuffer,
  [out]           USHORT               *ServicesBufferActual,
  [in]            ULONG                Flags
);

參數

[in] hDevice

處理要從中取得主要服務清單的藍牙裝置。

[in] ServicesBufferCount

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

[out, optional] ServicesBuffer

緩衝區的指標，其中包含要傳回服務的 BTH_LE_GATT_SERVICE 結構。

[out] ServicesBufferActual

緩衝區指標，其中 在 ServicesBuffer 參數中傳回實際服務數目。

[in] Flags

用來修改 BluetoothGATTGetServices 行為的旗標：

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

傳回值

此函式會傳回下列值：

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

備註

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

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

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

範例


////////////////////////////////////////////////////////////////////////////
// Determine Services Buffer Size
////////////////////////////////////////////////////////////////////////////

    hr = BluetoothGATTGetServices(
            hLEDevice,
            0,
            NULL,
            &serviceBufferCount,
            BLUETOOTH_GATT_FLAG_NONE);
    
    if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
        PrintHr("BluetoothGATTGetServices - Buffer Size", hr);
        goto Done;
    }

    pServiceBuffer = (PBTH_LE_GATT_SERVICE)
            malloc(sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);
    
    if (NULL == pServiceBuffer) {
        printf("pServiceBuffer out of memory\r\n");
        goto Done;
    } else {
        RtlZeroMemory(pServiceBuffer, 
                sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);
    }
    
////////////////////////////////////////////////////////////////////////////
// Retrieve Services
////////////////////////////////////////////////////////////////////////////
    
    hr = BluetoothGATTGetServices(
            hLEDevice,
            serviceBufferCount,
            pServiceBuffer,
            &numServices,
            BLUETOOTH_GATT_FLAG_NONE);
    
    if (S_OK != hr) {
        PrintHr("BluetoothGATTGetServices - Actual Data", hr);
        goto Done;
    }

需求

需求 值
最低支援的用戶端 Windows 8 和更新版本的 Windows 支援。
目標平台 Universal
標頭 bluetoothleapis.h
程式庫 BluetoothAPIs.lib
Dll BluetoothAPIs.dll

另請參閱

BTH_LE_GATT_SERVICE