目录
- 前言
- 广播与扫描概述
- 使用场景
- 相关接口汇总
- 实战使用步骤
- 结束语
前言
在HarmonyOS应用开发中，关于蓝牙相关的开发是非常重要的内容，而广播（Broadcast）机制是一种常见的通信方式，它允许应用发送或接收系统或应用级别的事件，还有就是扫描（Scan）功能则涉及到发现和连接周边设备，比如蓝牙设备。那么本文就来详细介绍如何在HarmonyOS应用中使用广播和扫描功能，包括技术选型、实现步骤和代码示例，方便大家查看使用。
广播与扫描概述
广播与扫描，主要提供了蓝牙设备的开启广播、关闭广播、开启扫描、关闭扫描方法，通过广播和扫描发现对端蓝牙设备，实现低功耗的通信。
先来介绍一下广播机制，其实广播在HarmonyOS中是一种异步事件传递机制，允许应用发送或接收事件，而无需知道事件的发送者。广播可以是系统级的，如电池低、屏幕关闭等，也可以是应用级的，如自定义事件。
再来介绍一下扫描功能，扫描功能在HarmonyOS中通常指发现周边设备，比如蓝牙、Wi-Fi设备等，这对于实现设备间的互联互通至关重要。
使用场景
在HarmonyOS开发中，广播与扫描都是结合使用的，而且也是非常常用且重要的功能，关于二者的主要场景，如下所示：
- 开启、关闭广播
开启、关闭扫描
相关接口汇总
再来了解一下在HarmonyOS开发中，广播与扫描相关的接口，具体如下所示：
接口名接口名 功能描述 startBLEScan() 发起BLE扫描流程。 stopBLEScan() 停止BLE扫描流程。 startAdvertising() 开始发送BLE广播。 disableAdvertising() 临时停止BLE广播。 enableAdvertising() 临时启动BLE广播。 stopAdvertising() 停止发送BLE广播。 on(type: 'advertisingStateChange') 订阅BLE广播状态。 off(type: 'advertisingStateChange') 取消订阅BLE广播状态。 on(type: 'BLEDeviceFind') 订阅BLE设备发现上报事件。 off(type: 'BLEDeviceFind') 取消订阅BLE设备发现上报事件。
实战使用步骤
关于实际开发中应用广播和扫描的使用，主要从开启、关闭广播和开启、关闭扫描两个模块来分享。
1、开启、关闭广播操作
开启、关闭广播的操作，主要从以下步骤进行操作：
1.import需要的ble模块。
2.开启设备的蓝牙。
3.需要SystemCapability.Communication.Bluetooth.Core系统能力。
4.开启广播，对端设备扫描该广播。
5.关闭广播。
根据上面这五步骤就可以进行开启、关闭广播的操作，接下来分享一个实际开发中使用的示例，具体如下所示：
import { ble } from '@kit.ConnectivityKit';
import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
const TAG: string = 'BleAdvertisingManager';
export class BleAdvertisingManager {
private advHandle: number = 0xFF; // default invalid value
// 1 订阅广播状态
public onAdvertisingStateChange() {
try {
ble.on('advertisingStateChange', (data: ble.AdvertisingStateChangeInfo) => {
});
} catch (err) {
}
}
// 2 首次启动广播
public async startAdvertising() {
// 2.1 设置广播发送的参数
let setting: ble.AdvertiseSetting = {
interval: 160,
txPower: 0,
connectable: true
};
// 2.2 构造广播数据
let manufactureValueBuffer = new Uint8Array(4);
manufactureValueBuffer[0] = 1;
manufactureValueBuffer[1] = 2;
manufactureValueBuffer[2] = 3;
manufactureValueBuffer[3] = 4;
let serviceValueBuffer = new Uint8Array(4);
serviceValueBuffer[0] = 5;
serviceValueBuffer[1] = 6;
serviceValueBuffer[2] = 7;
serviceValueBuffer[3] = 8;
let manufactureDataUnit: ble.ManufactureData = {
manufactureId: 4567,
manufactureValue: manufactureValueBuffer.buffer
};
let serviceDataUnit: ble.ServiceData = {
serviceUuid: "00001888-0000-1000-8000-00805f9b34fb",
serviceValue: serviceValueBuffer.buffer
};
let advData: ble.AdvertiseData = {
serviceUuids: ["00001888-0000-1000-8000-00805f9b34fb"],
manufactureData: [manufactureDataUnit],
serviceData: [serviceDataUnit],
includeDeviceName: false // 表示是否携带设备名，可选参数。注意带上设备名时广播包长度不能超出31个字节。
};
let advResponse: ble.AdvertiseData = {
serviceUuids: ["00001888-0000-1000-8000-00805f9b34fb"],
manufactureData: [manufactureDataUnit],
serviceData: [serviceDataUnit]
};
// 2.3 构造广播启动完整参数AdvertisingParams
let advertisingParams: ble.AdvertisingParams = {
advertisingSettings: setting,
advertisingData: advData,
advertisingResponse: advResponse,
duration: 0 // 可选参数，若大于0，则广播发送一段时间后，则会临时停止，可重新启动发送
}
// 2.4 首次启动广播，且获取所启动广播的标识ID
try {
this.onAdvertisingStateChange();
this.advHandle = await ble.startAdvertising(advertisingParams);
} catch (err) {
}
}
// 4 临时停止广播，该广播资源仍然存在
public async disableAdvertising() {
// 4.1 构造临时停止广播参数
let advertisingDisableParams: ble.AdvertisingDisableParams = {
advertisingId: this.advHandle // 使用首次启动广播时获取到的广播标识ID
}
// 4.2 临时停止
try {
await ble.disableAdvertising(advertisingDisableParams);
} catch (err) {
}
}
// 5 再次启动广播
public async enableAdvertising(enableDuration: number) {
// 5.1 构造临时启动广播参数
let advertisingEnableParams: ble.AdvertisingEnableParams = {
advertisingId: this.advHandle, // 使用首次启动广播时获取到的广播标识ID
duration: enableDuration
}
// 5.2 再次启动
try {
await ble.enableAdvertising(advertisingEnableParams);
} catch (err) {
}
}
// 6 完全关闭广播，释放广播资源
public async stopAdvertising() {
try {
await ble.stopAdvertising(this.advHandle);
ble.off('advertisingStateChange', (data: ble.AdvertisingStateChangeInfo) => {
});
} catch (err) {
}
}
}
let bleAdvertisingManager = new BleAdvertisingManager();
export default bleAdvertisingManager as BleAdvertisingManager;2、开启、关闭扫描操作
开启、关闭扫描的操作，主要从以下步骤进行操作：
1.import需要的ble模块。
2.开启设备的蓝牙。
3.需要SystemCapability.Communication.Bluetooth.Core系统能力。
4.对端设备开启广播。
5.本端设备开启扫描，获取扫描结果。
6.关闭扫描。
根据上面这六步骤就可以进行开启、关闭扫描的操作，接下来分享一个实际开发中使用的示例，具体如下所示：
import { ble } from '@kit.ConnectivityKit';
import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
const TAG: string = 'BleScanManager';
const BLE_ADV_TYPE_FLAG = 0x01;
const BLE_ADV_TYPE_16_BIT_SERVICE_UUIDS_INCOMPLETE = 0x02;
const BLE_ADV_TYPE_16_BIT_SERVICE_UUIDS_COMPLETE = 0x03;
const BLE_ADV_TYPE_32_BIT_SERVICE_UUIDS_INCOMPLETE = 0x04;
const BLE_ADV_TYPE_32_BIT_SERVICE_UUIDS_COMPLETE = 0x05;
const BLE_ADV_TYPE_128_BIT_SERVICE_UUIDS_INCOMPLETE = 0x06;
const BLE_ADV_TYPE_128_BIT_SERVICE_UUIDS_COMPLETE = 0x07;
const BLE_ADV_TYPE_LOCAL_NAME_SHORT = 0x08;
const BLE_ADV_TYPE_LOCAL_NAME_COMPLETE = 0x09;
const BLE_ADV_TYPE_TX_POWER_LEVEL = 0x0A;
const BLE_ADV_TYPE_16_BIT_SERVICE_SOLICITATION_UUIDS = 0x14;
const BLE_ADV_TYPE_128_BIT_SERVICE_SOLICITATION_UUIDS = 0x15;
const BLE_ADV_TYPE_32_BIT_SERVICE_SOLICITATION_UUIDS = 0x1F;
const BLE_ADV_TYPE_16_BIT_SERVICE_DATA = 0x16;
const BLE_ADV_TYPE_32_BIT_SERVICE_DATA = 0x20;
const BLE_ADV_TYPE_128_BIT_SERVICE_DATA = 0x21;
const BLE_ADV_TYPE_MANUFACTURER_SPECIFIC_DATA = 0xFF;
const BLUETOOTH_UUID_16_BIT_LENGTH = 2;
const BLUETOOTH_UUID_32_BIT_LENGTH = 4;
const BLUETOOTH_UUID_128_BIT_LENGTH = 16;
const BLUETOOTH_MANUFACTURE_ID_LENGTH = 2;
export class BleScanManager {
// 1 订阅扫描结果
public onScanResult() {
ble.on('BLEDeviceFind', (data: Array<ble.ScanResult>) => {
if (data.length > 0) {
this.parseScanResult(data[0].data);
}
});
}
private parseScanResult(data: ArrayBuffer) {
let advData = new Uint8Array(data);
if (advData.byteLength == 0) {
return;
}
let advFlags: number = -1;
let txPowerLevel: number = -1;
let localName: string = "";
let serviceUuids: string[] = [];
let serviceSolicitationUuids: string[] = [];
let serviceDatas: Record<string, Uint8Array> = {};
let manufactureSpecificDatas: Record<number, Uint8Array> = {};
let curPos = 0;
while (curPos < advData.byteLength) {
let length = advData[curPos++];
if (length == 0) {
break;
}
let advDataLength = length - 1;
let advDataType = advData[curPos++];
switch (advDataType) {
case BLE_ADV_TYPE_FLAG:
advFlags = advData[curPos];
break;
case BLE_ADV_TYPE_LOCAL_NAME_SHORT:
case BLE_ADV_TYPE_LOCAL_NAME_COMPLETE:
localName = advData.slice(curPos, curPos + advDataLength).toString();
break;
case BLE_ADV_TYPE_TX_POWER_LEVEL:
txPowerLevel = advData[curPos];
break;
case BLE_ADV_TYPE_16_BIT_SERVICE_UUIDS_INCOMPLETE:
case BLE_ADV_TYPE_16_BIT_SERVICE_UUIDS_COMPLETE:
this.parseServiceUuid(BLUETOOTH_UUID_16_BIT_LENGTH, curPos, advDataLength, advData, serviceUuids);
break;
case BLE_ADV_TYPE_32_BIT_SERVICE_UUIDS_INCOMPLETE:
case BLE_ADV_TYPE_32_BIT_SERVICE_UUIDS_COMPLETE:
this.parseServiceUuid(BLUETOOTH_UUID_32_BIT_LENGTH, curPos, advDataLength, advData, serviceUuids);
break;
case BLE_ADV_TYPE_128_BIT_SERVICE_UUIDS_INCOMPLETE:
case BLE_ADV_TYPE_128_BIT_SERVICE_UUIDS_COMPLETE:
this.parseServiceUuid(BLUETOOTH_UUID_128_BIT_LENGTH, curPos, advDataLength, advData, serviceUuids);
break;
case BLE_ADV_TYPE_16_BIT_SERVICE_SOLICITATION_UUIDS:
this.parseServiceSolicitationUuid(BLUETOOTH_UUID_16_BIT_LENGTH, curPos, advDataLength,
advData, serviceSolicitationUuids);
break;
case BLE_ADV_TYPE_32_BIT_SERVICE_SOLICITATION_UUIDS:
this.parseServiceSolicitationUuid(BLUETOOTH_UUID_32_BIT_LENGTH, curPos, advDataLength,
advData, serviceSolicitationUuids);
break;
case BLE_ADV_TYPE_128_BIT_SERVICE_SOLICITATION_UUIDS:
this.parseServiceSolicitationUuid(BLUETOOTH_UUID_128_BIT_LENGTH, curPos, advDataLength,
advData, serviceSolicitationUuids);
break;
case BLE_ADV_TYPE_16_BIT_SERVICE_DATA:
this.parseServiceData(BLUETOOTH_UUID_16_BIT_LENGTH, curPos, advDataLength, advData, serviceDatas);
break;
case BLE_ADV_TYPE_32_BIT_SERVICE_DATA:
this.parseServiceData(BLUETOOTH_UUID_32_BIT_LENGTH, curPos, advDataLength, advData, serviceDatas);
break;
case BLE_ADV_TYPE_128_BIT_SERVICE_DATA:
this.parseServiceData(BLUETOOTH_UUID_128_BIT_LENGTH, curPos, advDataLength, advData, serviceDatas);
break;
case BLE_ADV_TYPE_MANUFACTURER_SPECIFIC_DATA:
this.parseManufactureData(curPos, advDataLength, advData, manufactureSpecificDatas);
break;
default:
break;
}
curPos += advDataLength;
}
}
private parseServiceUuid(uuidLength: number, curPos: number, advDataLength: number,
advData: Uint8Array, serviceUuids: string[]) {
while (advDataLength > 0) {
let tmpData: Uint8Array = advData.slice(curPos, curPos + uuidLength);
serviceUuids.push(this.getUuidFromUint8Array(uuidLength, tmpData));
advDataLength -= uuidLength;
curPos += uuidLength;
}
}
private parseServiceSolicitationUuid(uuidLength: number, curPos: number, advDataLength: number,
advData: Uint8Array, serviceSolicitationUuids: string[]) {
while (advDataLength > 0) {
let tmpData: Uint8Array = advData.slice(curPos, curPos + uuidLength);
serviceSolicitationUuids.push(this.getUuidFromUint8Array(uuidLength, tmpData));
advDataLength -= uuidLength;
curPos += uuidLength;
}
}
private getUuidFromUint8Array(uuidLength: number, uuidData: Uint8Array): string {
let uuid = "";
let temp: string = "";
for (let i = uuidLength - 1; i > -1; i--) {
temp += uuidData[i].toString(16).padStart(2, "0");
}
switch (uuidLength) {
case BLUETOOTH_UUID_16_BIT_LENGTH:
uuid = `0000${temp}-0000-1000-8000-00805F9B34FB`;
break;
case BLUETOOTH_UUID_32_BIT_LENGTH:
uuid = `${temp}-0000-1000-8000-00805F9B34FB`;
break;
case BLUETOOTH_UUID_128_BIT_LENGTH:
uuid = `${temp.substring(0, 8)}-${temp.substring(8, 12)}-${temp.substring(12, 16)}-${temp.substring(16, 20)}-${temp.substring(20, 32)}`;
break;
default:
break;
}
return uuid;
}
private parseServiceData(uuidLength: number, curPos: number, advDataLength: number,
advData: Uint8Array, serviceDatas: Record<string, Uint8Array>) {
let tmpUuid: Uint8Array = advData.slice(curPos, curPos + uuidLength);
let tmpValue: Uint8Array = advData.slice(curPos + uuidLength, curPos + advDataLength);
serviceDatas[tmpUuid.toString()] = tmpValue;
}
private parseManufactureData(curPos: number, advDataLength: number,
advData: Uint8Array, manufactureSpecificDatas: Record<number, Uint8Array>) {
let manufactureId: number = (advData[curPos + 1] << 8) + advData[curPos];
let tmpValue: Uint8Array = advData.slice(curPos + BLUETOOTH_MANUFACTURE_ID_LENGTH, curPos + advDataLength);
manufactureSpecificDatas[manufactureId] = tmpValue;
}
// 2 开启扫描
public startScan() {
// 2.1 构造扫描过滤器，需要能够匹配预期的广播包内容
let manufactureId = 4567;
let manufactureData: Uint8Array = new Uint8Array([1, 2, 3, 4]);
let manufactureDataMask: Uint8Array = new Uint8Array([0xFF, 0xFF, 0xFF, 0xFF]);
let scanFilter: ble.ScanFilter = { // 根据业务实际情况定义过滤器
manufactureId: manufactureId,
manufactureData: manufactureData.buffer,
manufactureDataMask: manufactureDataMask.buffer
};
// 2.2 构造扫描参数
let scanOptions: ble.ScanOptions = {
interval: 0,
dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER,
matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE
}
try {
this.onScanResult(); // 订阅扫描结果
ble.startBLEScan([scanFilter], scanOptions);
} catch (err) {
}
}
// 3 关闭扫描
public stopScan() {
try {
ble.off('BLEDeviceFind', (data: Array<ble.ScanResult>) => { // 取消订阅扫描结果
});
ble.stopBLEScan();
} catch (err) {
}
}
}
let bleScanManager = new BleScanManager();
export default bleScanManager as BleScanManager;结束语
上面的详细介绍，可以看到广播和扫描功能是HarmonyOS开发中的重要工具，它们使得应用能够响应系统事件和发现周边设备，尤其是现在多设备场景下，广播和扫描功能的重要性不言而喻。通过本文的介绍，想必读者应该都了解了如何在HarmonyOS应用中实现广播和扫描功能。随着技术的不断发展，这些功能将会在HarmonyOS生态中扮演越来越重要的角色，给用户带来更加丰富和便捷的体验，让我们拭目以待吧！
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。