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	buffer 参数为 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 中受支持。
目标平台	通用
标头	bluetoothleapis.h
Library	BluetoothApis.lib
DLL	BluetoothAPIs.dll

另请参阅

BTH_LE_GATT_SERVICE