使用BluetoothGATTSetCharacteristicValue返回E_HANDLE错误及服务句柄获取问题

我之前也踩过这个坑，你遇到的E_HANDLE错误，本质上是因为你用的BTH_LE_GATT_CHARACTERISTIC结构体里的ServiceHandle不是合法有效的句柄——这个值不能随便填，必须通过Windows蓝牙GATT的标准枚举流程来获取。

正确的服务句柄获取流程 #

要拿到能正常工作的服务句柄，你得按下面的步骤一步步来：

• 先拿到蓝牙LE设备的有效句柄
  首先得通过BluetoothFindFirstDevice/BluetoothFindNextDevice找到目标蓝牙设备，然后用CreateFile打开它，确保返回的句柄不是INVALID_HANDLE_VALUE——这是后续所有GATT操作的基础。

• 枚举设备下的GATT服务
  调用BluetoothGATTGetServices枚举该设备的所有GATT服务，第一次调用可以传nullptr来获取服务数量，然后分配内存再调用一次拿到BTH_LE_GATT_SERVICE数组。每个服务结构体里的Handle字段就是你需要的有效服务句柄。

• 枚举目标服务下的特征
  拿着目标服务的句柄，调用BluetoothGATTGetCharacteristics枚举该服务下的特征。这时候返回的BTH_LE_GATT_CHARACTERISTIC结构体里的ServiceHandle会被自动填充为对应的服务句柄，这个值才是能被BluetoothGATTSetCharacteristicValue接受的。

你可能犯的错误 #

• 你大概率是手动构造了BTH_LE_GATT_CHARACTERISTIC结构体，而不是通过BluetoothGATTGetCharacteristics来获取——这种情况下结构体里的ServiceHandle是无效的，自然会返回E_HANDLE。
• 检查一下你打开设备时得到的句柄是不是有效的，CreateFile失败的话后续所有操作都会出问题。
• 确认你用的服务句柄是从BTH_LE_GATT_SERVICE.Handle来的，而不是随便填的数字。

可参考的代码片段 #

// 假设已经通过CreateFile拿到了有效的蓝牙设备句柄 hDeviceHandle

// 第一步：获取设备的GATT服务列表
BTH_LE_GATT_SERVICE* services = nullptr;
ULONG serviceCount = 0;
HRESULT hr = BluetoothGATTGetServices(hDeviceHandle, nullptr, &serviceCount, BLUETOOTH_GATT_FLAG_NONE);

if (hr == HRESULT_FROM_WIN32(ERROR_MORE_DATA)) {
    services = (BTH_LE_GATT_SERVICE*)malloc(serviceCount * sizeof(BTH_LE_GATT_SERVICE));
    hr = BluetoothGATTGetServices(hDeviceHandle, services, &serviceCount, BLUETOOTH_GATT_FLAG_NONE);

    if (SUCCEEDED(hr)) {
        // 第二步：遍历找到目标服务（这里用UUID匹配举例）
        for (ULONG i = 0; i < serviceCount; i++) {
            if (IsEqualGUID(services[i].ServiceUuid, YOUR_TARGET_SERVICE_UUID)) {
                // 第三步：获取该服务下的特征列表
                BTH_LE_GATT_CHARACTERISTIC* chars = nullptr;
                ULONG charCount = 0;
                hr = BluetoothGATTGetCharacteristics(hDeviceHandle, &services[i], nullptr, &charCount, BLUETOOTH_GATT_FLAG_NONE);

                if (hr == HRESULT_FROM_WIN32(ERROR_MORE_DATA)) {
                    chars = (BTH_LE_GATT_CHARACTERISTIC*)malloc(charCount * sizeof(BTH_LE_GATT_CHARACTERISTIC));
                    hr = BluetoothGATTGetCharacteristics(hDeviceHandle, &services[i], chars, &charCount, BLUETOOTH_GATT_FLAG_NONE);

                    if (SUCCEEDED(hr)) {
                        // 第四步：找到目标特征并设置值
                        for (ULONG j = 0; j < charCount; j++) {
                            if (IsEqualGUID(chars[j].CharacteristicUuid, YOUR_TARGET_CHAR_UUID)) {
                                // 准备要设置的特征值
                                BTH_LE_GATT_CHARACTERISTIC_VALUE charValue = {0};
                                charValue.DataSize = YOUR_DATA_LENGTH;
                                charValue.Data = YOUR_DATA_BUFFER;

                                // 调用设置接口
                                hr = BluetoothGATTSetCharacteristicValue(hDeviceHandle, &chars[j], &charValue, BLUETOOTH_GATT_FLAG_NONE);
                                if (SUCCEEDED(hr)) {
                                    // 设置成功的逻辑
                                } else {
                                    // 处理错误，比如打印hr值
                                }
                                break;
                            }
                        }
                        free(chars);
                    }
                }
                break;
            }
        }
        free(services);
    }
}

额外提醒 #

• 记得用完分配的内存后要free，别漏了导致内存泄漏。
• 所有GATT API调用都要仔细检查返回值，尤其是ERROR_MORE_DATA——这是Windows API常见的“先查大小再分配内存”的套路。
• 如果是桌面程序，确保运行时有足够的权限访问蓝牙设备；如果是UWP，要在manifest里声明蓝牙相关的权限。

内容的提问来源于stack exchange，提问作者Ahemd Elias