通过

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

另请参阅

BTH_LE_GATT_SERVICE