bluetoothGATTGetIncludedServices 函式 (bluetoothleapis.h)

BluetoothGATTGetIncludedServices 函式會取得指定服務可用的所有內含服務。

語法

HRESULT BluetoothGATTGetIncludedServices(
  [in]            HANDLE               hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE ParentService,
  [in]            USHORT               IncludedServicesBufferCount,
  [out, optional] PBTH_LE_GATT_SERVICE IncludedServicesBuffer,
  [out]           USHORT               *IncludedServicesBufferActual,
  [in]            ULONG                Flags
);

參數

[in] hDevice

藍牙裝置或父服務的句柄。

[in, optional] ParentService

包含要擷取之內含服務的父服務 之BTH_LE_GATT_SERVICE 結構的位址。 如果裝置句柄傳遞至 hDevice，則需要此參數。 如果服務句柄傳遞至 hDevice，則此參數是選擇性的，在此情況下，服務句柄所指定的服務會被視為父代。

[in] IncludedServicesBufferCount

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

[out, optional] IncludedServicesBuffer

緩衝區的位址，其中包含要傳回內含服務的 BTH_LE_GATT_SERVICE 結構。

[out] IncludedServicesBufferActual

緩衝區的指標，在 IncludedServicesBuffer 參數中傳回實際包含的服務數目。

[in] Flags

用來修改 BluetoothGATTGetIncludedServices 行為的旗標：

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

傳回值

此函式會傳回下列值：

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

備註

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

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

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

範例

////////////////////////////////////////////////////////////////////////////
// Determine Included Services Buffer Size
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetIncludedServices(
     hLEDevice,
     gattService,
     0,
     NULL,
     &inclServicesBufferSize,
     BLUETOOTH_GATT_FLAG_NONE);

     if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
         PrintHr("BluetoothGATTGetIncludedServices - Buffer Size", hr);
         goto Done;
     }

     if (inclServicesBufferSize > 0) {
         pInclServicesBuffer = (PBTH_LE_GATT_ PBTH_LE_GATT_SERVICE)
                    malloc(inclServicesBufferSize * sizeof(BTH_LE_GATT_SERVICE));

         if (NULL == pInclServicesBuffer) {
             printf("pInclServicesBuffer out of memory\r\n");
             goto Done;
         } else {
             RtlZeroMemory(pInclServicesBuffer, 
                    inclServicesBufferSize * sizeof(BTH_LE_GATT_SERVICE));
         }

         ////////////////////////////////////////////////////////////////////////////
         // Retrieve Included Services
         ////////////////////////////////////////////////////////////////////////////

         hr = BluetoothGATTGetIncludedServices (
              hLEDevice,
              gattService,
              inclServicesBufferSize,
              pInclServicesBuffer,
              &numIncludedServices
              BLUETOOTH_GATT_FLAG_NONE);

         if (S_OK != hr) {
             PrintHr("BluetoothGATTGetIncludedServices - Actual Data", hr);
             goto Done;
         }
     }

需求

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

另請參閱

BTH_LE_GATT_SERVICE