Qt Bluetooth 概述

使用Qt Bluetooth API的典型用例包括：

检索本地蓝牙设备的信息。
扫描范围内其他蓝牙设备并获取其信息。
使用 OBEX 对象推送配置文件 (OPP) 将文件推送到远程设备
使用串行端口配置文件 (SPP) 通过 RFCOMM 通道连接到远程设备。
创建一个允许通过 SPP 接受传入连接的 RFCOMM 服务器。
检索蓝牙低功耗设备的规格信息。
连接到蓝牙低功耗设备。
接收来自蓝牙低功耗设备的广告。

请注意，Android 和 Windows 不支持“对象推送配置文件”（Object Push Profile）。

注意： 在 Windows 系统上，Qt 无法配置 RFCOMM 功能的某些部分 。服务的“ServiceClassIds ”和“ProtocolDescriptorList ”字段会自动填充。因此，在 Windows 系统上为这些字段设置自定义值并注册服务时，可能无法获得预期结果。

注意： Win32 后端不支持接收信号强度指示器 (RSSI) 以及蓝牙低功耗 (Bluetooth LE) 设备广播的制造商特定数据。此外，仅能查找那些此前已通过 Windows 设置配对过的设备。

以下各节将介绍如何使用Qt Bluetooth 中的 C++ API 类来处理上述用例。

检索本地设备信息

Qt Bluetooth API 主要有三个用途。第一个是获取本地和远程设备信息。获取设备信息的第一步是检查设备上是否启用了蓝牙，并读取本地设备的地址和名称。QBluetoothLocalDevice 类提供了所有这些信息。此外，您还可以使用它来开启/关闭蓝牙、设置设备的可见性以及确定当前的连接状态。

QBluetoothLocalDevice localDevice;
QString localDeviceName;

// Check if Bluetooth is available on this device
if (localDevice.isValid()) {

    // Turn Bluetooth on
    localDevice.powerOn();

    // Read local device name
    localDeviceName = localDevice.name();

    // Make it visible to others
    localDevice.setHostMode(QBluetoothLocalDevice::HostDiscoverable);

    // Get connected devices
    QList<QBluetoothAddress> remotes;
    remotes = localDevice.connectedDevices();
}

扫描蓝牙设备

与QBluetoothLocalDevice 类似，该API提供了QBluetoothDeviceInfo ，用于获取远程设备的类似信息。虽然您可以自行创建QBluetoothDeviceInfo 对象并为其填充数据，但更简便的方法是使用QBluetoothDeviceDiscoveryAgent ，以自动搜索连接范围内可见的蓝牙设备。

voidMyClass::startDeviceDiscovery()
{

    // 创建一个发现代理并订阅其信号
    QBluetoothDeviceDiscoveryAgent*discoveryAgent = newQBluetoothDeviceDiscoveryAgent(this);
    connect(discoveryAgent,SIGNAL(deviceDiscovered(QBluetoothDeviceInfo)),
            this,SLOT(deviceDiscovered(QBluetoothDeviceInfo)));

    // 启动发现
   discoveryAgent->start();

    //...
}

// 在本地槽中，读取已发现设备的相关信息
voidMyClass::deviceDiscovered(constQBluetoothDeviceInfo&device)
{
    qDebug() << "Found new device:" << device.name() << '(' << device.address().toString() << ')';
}

设备间的数据交换

在两个支持蓝牙的设备之间进行通信时，更灵活的方法是建立一个虚拟串行端口连接，并通过该连接自由交换数据。这可以通过串行端口配置文件（SPP）来实现。串行端口配置文件通过蓝牙传输协议 RFCOMM 模拟串行连接。

要接收传入的 SPP 连接，您需要使用 `QBluetoothServer` 监听传入连接。

rfcommServer= newQBluetoothServer(QBluetoothServiceInfo::RfcommProtocol, this);
connect(rfcommServer, &QBluetoothServer::newConnection,
        this, QOverload<>::of(&ChatServer::clientConnected));
boolresult= rfcommServer->listen(localAdapter);
if(!result) {
    qWarning() << "Cannot bind chat server to" << localAdapter.toString();
   return;
}

请使用QBluetoothSocket 从另一台担任客户端角色的设备连接到此服务器：

voidChatClient::startClient(constQBluetoothServiceInfo&remoteService)
{
    if(socket)
        return;

    // 连接到服务
    socket= newQBluetoothSocket(QBluetoothServiceInfo::RfcommProtocol);
    qDebug() << "Create socket";
    socket->connectToService(remoteService);
    qDebug() << "ConnectToService done";

    connect(socket, &QBluetoothSocket::readyRead, this, &ChatClient::readSocket);
    connect(socket, &QBluetoothSocket::connected, this, QOverload<>::of(&ChatClient::connected));
    connect(socket, &QBluetoothSocket::disconnected, this, &ChatClient::disconnected);
    connect(socket, &QBluetoothSocket::errorOccurred, this, &ChatClient::onSocketErrorOccurred);
}

使用此类连接可双向交换任何形式的数据。它非常适合用于游戏，或用于在两台设备上的两个应用程序实例之间同步状态。有关如何配置服务器和客户端的更详细说明，请参阅QBluetoothServer 和QBluetoothSocket 类中的详细说明部分。开始使用 SPP 的一个很好的示例是“蓝牙聊天”示例。

蓝牙低功耗

蓝牙低功耗（Bluetooth Low Energy），也称为蓝牙智能（Bluetooth Smart），是一项使低功耗设备能够相互通信的新技术。有关此技术及相关 Qt API 的更多详细信息，请参阅《蓝牙低功耗概述》。

蓝牙低功耗概述

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.