QLowEnergyAdvertisingData Class
QLowEnergyAdvertisingData 类表示在蓝牙低功耗广播期间要广播的数据。更多内容...
| 头文件： | #include <QLowEnergyAdvertisingData> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Bluetooth) target_link_libraries(mytarget PRIVATE Qt6::Bluetooth) |
| qmake： | QT += bluetooth |
- 所有成员的列表，包括继承的成员
- QLowEnergyAdvertisingData 属于“隐式共享类”。
公共类型
| enum | Discoverability { DiscoverabilityNone, DiscoverabilityLimited, DiscoverabilityGeneral } |
公共函数
| QLowEnergyAdvertisingData() | |
| QLowEnergyAdvertisingData(const QLowEnergyAdvertisingData &other) | |
| ~QLowEnergyAdvertisingData() | |
| QLowEnergyAdvertisingData::Discoverability | discoverability() const |
| bool | includePowerLevel() const |
| QString | localName() const |
| QByteArray | manufacturerData() const |
| quint16 | manufacturerId() const |
| QByteArray | rawData() const |
| QList<QBluetoothUuid> | services() const |
| void | setDiscoverability(QLowEnergyAdvertisingData::Discoverability mode) |
| void | setIncludePowerLevel(bool doInclude) |
| void | setLocalName(const QString &name) |
| void | setManufacturerData(quint16 id, const QByteArray &data) |
| void | setRawData(const QByteArray &data) |
| void | setServices(const QList<QBluetoothUuid> &services) |
| void | swap(QLowEnergyAdvertisingData &other) |
| QLowEnergyAdvertisingData & | operator=(const QLowEnergyAdvertisingData &other) |
静态公共成员
| quint16 | invalidManufacturerId() |
相关的非成员
| bool | operator!=(const QLowEnergyAdvertisingData &data1, const QLowEnergyAdvertisingData &data2) |
| bool | operator==(const QLowEnergyAdvertisingData &data1, const QLowEnergyAdvertisingData &data2) |
详细说明
这些数据可包括设备名称、设备提供的 GATT 服务等。通过此类设置的数据将在调用 `QLowEnergyController::startAdvertising()` 启动广播时使用。该类的对象可表示一个广播数据数据包或一个扫描响应数据包。
广告数据限制
广告数据的最大长度取决于蓝牙设备和平台的蓝牙协议栈。为了实现最大的兼容性，建议将广告数据大小限制在 31 字节的传统广告限制内。
如果通过本类设置的可变长度数据超出了支持的限制，具体行为将取决于底层蓝牙协议栈的实现。最典型的处理方式包括：
- 多余的数据可能会被截断或完全省略；
- 广播无法启动。
例如，在 Android 系统上，如果广播数据大于 31 字节，广播将失败。在 BlueZ DBus 后端中，广播长度限制以及超出限制时的行为取决于 BlueZ；例如，它可能支持扩展广播，也可能无法启动广播。
另请参阅 QLowEnergyAdvertisingParameters 和QLowEnergyController::startAdvertising()。
成员类型文档
enum QLowEnergyAdvertisingData::Discoverability
由通用访问配置文件（Generic Access Profile）定义的广告设备的可发现性。
| 常量 | 值 | 描述 |
|---|---|---|
QLowEnergyAdvertisingData::DiscoverabilityNone | 0 | 该广播设备不希望被扫描设备发现。 |
QLowEnergyAdvertisingData::DiscoverabilityLimited | 1 | 该广播设备希望以高优先级被扫描设备发现。请注意，此模式与白名单不兼容。当使用受限可发现性时，QLowEnergyAdvertisingParameters::filterPolicy() 的值始终被假定为QLowEnergyAdvertisingParameters::IgnoreWhiteList 。 |
QLowEnergyAdvertisingData::DiscoverabilityGeneral | 2 | 该广播设备希望被扫描设备发现。 |
成员函数文档
QLowEnergyAdvertisingData::QLowEnergyAdvertisingData()
创建该类的一个新对象。所有值均根据蓝牙低功耗（Bluetooth Low Energy）规范初始化为默认值。
QLowEnergyAdvertisingData::QLowEnergyAdvertisingData(const QLowEnergyAdvertisingData &other)
创建该类的一个新对象，该对象是other 的副本。
[noexcept] QLowEnergyAdvertisingData::~QLowEnergyAdvertisingData()
销毁此对象。
QLowEnergyAdvertisingData::Discoverability QLowEnergyAdvertisingData::discoverability() const
返回广告设备的可发现模式。默认值为DiscoverabilityNone 。
另请参阅 setDiscoverability()。
bool QLowEnergyAdvertisingData::includePowerLevel() const
返回是否将设备的发射功率级别包含在广播数据中。默认值为false 。
另请参阅 setIncludePowerLevel()。
[static] quint16 QLowEnergyAdvertisingData::invalidManufacturerId()
返回一个无效的制造商 ID。如果将此值设置为制造商 ID（默认即为此值），则广告数据中将不包含任何制造商数据。
QString QLowEnergyAdvertisingData::localName() const
返回要广播的本地设备的名称。
另请参阅 setLocalName()。
QByteArray QLowEnergyAdvertisingData::manufacturerData() const
返回制造商数据。默认值为一个空字节数组。
另请参阅 setManufacturerData()。
quint16 QLowEnergyAdvertisingData::manufacturerId() const
返回制造商标识符。默认值为QLowEnergyAdvertisingData::invalidManufacturerId()，这意味着数据不会被广播。
QByteArray QLowEnergyAdvertisingData::rawData() const
返回用户提供的待发布的原始数据。默认值为一个空字节数组。
另请参阅 setRawData()。
QList<QBluetoothUuid> QLowEnergyAdvertisingData::services() const
返回待发布的服务 UUID 列表。默认情况下，该列表为空。
另请参阅 setServices()。
void QLowEnergyAdvertisingData::setDiscoverability(QLowEnergyAdvertisingData::Discoverability mode)
将广告设备的可发现性类型设置为mode 。
注意：可发现性 信息只能出现在实际的广告数据包中。如果该对象充当扫描响应数据，调用此函数将不会对发送的扫描响应产生任何影响。
另请参阅 discoverability()。
void QLowEnergyAdvertisingData::setIncludePowerLevel(bool doInclude)
指定是否在广播数据中包含设备的发射功率级别。如果doInclude 的值为true ，则包含该数据；否则不包含。
另请参阅 includePowerLevel()。
void QLowEnergyAdvertisingData::setLocalName(const QString &name)
指定应将“name ”作为设备名称进行广播。如果全名无法容纳在广告数据包中，则会发送简写名称，具体操作遵循蓝牙低功耗（Bluetooth Low Energy）规范。
在 Android 系统上，本地名称无法更改。Android 始终使用设备名称。如果该本地名称不为空，Android 实现会将设备名称包含在广告数据包中；否则，广告数据包中将省略设备名称。
另请参阅 localName()。
void QLowEnergyAdvertisingData::setManufacturerData(quint16 id, const QByteArray &data)
设置制造商 ID 和数据。id 参数是由蓝牙特别兴趣小组 (Bluetooth SIG) 分配的公司标识符。data 参数是一个任意值。
注意：macOS 和 iOS 不支持广播制造商标识符或数据，因此在此类平台上，所提供的参数将被忽略。
另请参阅 manufacturerData()。
void QLowEnergyAdvertisingData::setRawData(const QByteArray &data)
将要发布到data 的数据设置为该值。如果该值不是空字节数组，则会原样作为发布数据发送，而该对象中的所有其他数据将被忽略。这可用于发送非标准数据。
注意：若 data 长度超过31字节，将被截断。确保data 格式正确是调用方的责任。
仅在Linux 蓝牙内核 API后端上支持设置原始广告数据。其他后端不允许将原始广告数据指定为全局字段。
另请参阅 rawData()。
void QLowEnergyAdvertisingData::setServices(const QList<QBluetoothUuid> &services)
指定应广播services 中列出的服务UUID。如果整个列表无法容纳于数据包中，则将按照蓝牙低功耗规范的规定发送不完整的列表。
另请参阅 services()。
[noexcept] void QLowEnergyAdvertisingData::swap(QLowEnergyAdvertisingData &other)
将此对象与other 互换。
QLowEnergyAdvertisingData &QLowEnergyAdvertisingData::operator=(const QLowEnergyAdvertisingData &other)
将该对象复制为other 的副本，并返回该对象的新值。
相关的非成员
bool operator!=(const QLowEnergyAdvertisingData &data1, const QLowEnergyAdvertisingData &data2)
如果 `data1 ` 和 `data2 ` 的公共状态不相同，则返回 `true `；否则返回 `false`。
bool operator==(const QLowEnergyAdvertisingData &data1, const QLowEnergyAdvertisingData &data2)
如果data1 和data2 的公共状态相等，则返回true ；否则返回false 。
© 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.
