JS 系统接口

接口

通用规则

同步

同步方法调用后必须等到方法结果返回后才能继续后续的行为，返回值可以是任意类型。

示例：

var info = app.getInfo();
console.log(JSON.stringify(info));

异步

异步方法调用整个过程不会阻碍调用者的工作。业务执行完成后会调用开发者提供的回调函数，异步接口支持的回调函数如表1所示。

表 1 异步接口支持的回调函数

回调函数	参数名	类型	返回值	说明
success	data	any	可选，返回值可以是任意类型。	在执行成功时触发。
fail	data	any	错误信息内容，一般是字符串，也可能是其他类型。	在执行失败时触发。
fail	code	number	错误代码，请参见“通用错误码”。	在执行失败时触发。
cancel	data	any	一般无内容。	在用户取消时触发。
complete	-	-	-	在执行完成时触发。

说明：

success、fail、cancel和complete四个回调函数是否支持请参考具体接口描述。

success、fail和cancel三个回调函数的触发是互斥的，即会且只会有一个回调函数被触发，触发任意一个都会再次调用complete回调。

示例：

device.getInfo({
    success: function(data) {
        console.log('Device information obtained successfully. Device brand:' + data.brand);
    },
    fail: function(data, code) {
        console.log('Failed to obtain device information. Error code:'+ code + '; Error information: ' + data);
    },
});

订阅接口不会立即返回结果，开发者要在参数中设置相应的回调函数，该回调函数会在完成时或者事件变化时进行回调；可以执行多次。

表 2 订阅接口支持的回调函数

回调函数	参数名	类型	返回值	说明
success	data	any	返回值可以是任意类型。	接口调用成功或事件变更时触发，可能会触发多次。
fail	data	any	错误信息内容，一般是字符串，也可能是其他类型。	在执行失败时触发。一旦触发该回调函数，success不会再次被调用，接口调用结束。
fail	code	number	错误代码，请参见“通用错误码”。	在执行失败时触发。一旦触发该回调函数，success不会再次被调用，接口调用结束。

通用错误码

如表1所示提供公共的错误码。其中，错误码200为系统通用错误码，所有系统未知异常发生时抛出，如框架申请内存空间失败等情况。

表 1 通用错误码

code	含义
200	通用错误。
202	参数错误。
300	I/O错误。

应用上下文

导入模块

import app from '@system.app';

app.getInfo

获取当前应用配置文件中声明的信息：getInfo()

返回值

表 1 AppResponse

参数名

类型

说明

appName

string

表示应用的名称。

versionName

string

表示应用的版本名称。

versionCode

number

表示应用的版本号。

示例

var info = app.getInfo();
console.log(JSON.stringify(info));

app.terminate

退出当前Ability：terminate(): void

示例：

 app.terminate();

日志打印

导入模块

无需导入。

console.debug

打印debug级别的日志信息：debug(message: string): void

参数

参数名

类型

必填

说明

message

string

是

表示要打印的文本信息。

console.log

打印log级别的日志信息：log(message: string): void

参数

参数名

类型

必填

说明

message

string

是

表示要打印的文本信息。

console.info

打印info级别的日志信息：info(message: string): void

参数

参数名

类型

必填

说明

message

string

是

表示要打印的文本信息。

console.warn

打印warn级别的日志信息：warn(message: string): void

参数

参数名

类型

必填

说明

message

string

是

表示要打印的文本信息。

console.error

打印error级别的日志信息：error(message: string): void

参数

参数名

类型

必填

说明

message

string

是

表示要打印的文本信息。

示例

var versionCode = 1;
console.info('Hello World. The current version code is ' + versionCode);

页面路由

导入模块

import router from '@system.router';

router.replace

用应用内的某个页面替换当前页面并销毁被替换的页面：replace(Object): void

参数

参数名

类型

必填

说明

uri

string

是

目标页面的uri，可以是以下的两种格式：

页面绝对路径，由配置文件中pages列表提供，例如：
- pages/index/index
- pages/detail/detail
特殊值，如果uri的值是“/”，则跳转到首页。

params

Object

否

跳转时要同时传递到目标页面的数据，跳转到目标页面后，参数可以在页面中直接使用，如this.data1（data1为跳转时params参数中的key值）。如果目标页面中已有该字段，则其值会被传入的字段值覆盖。

示例

// 在当前页面中
 export default {
     replacePage() {
         router.replace({
             uri: 'pages/detail/detail',
             params: {
                 data1: 'message',
             },
         });
     }
 }
 // 在detail页面中
 export default {
     data: {
         data1: 'default'
     },
     onInit() {
         console.info('showData1:' + this.data1)
     }
 }

应用配置

导入模块

import configuration from '@system.configuration';

configuration.getLocale

获取应用当前的语言和地区：getLocale()，默认与系统的语言和地区同步。

返回值

表 1 LocaleResponse

参数名

类型

说明

language

string

语言。例如：zh。

countryOrRegion

string

国家或地区。例如：CN。

dir

string

文字布局方向。取值范围：

ltr：从左到右；
rtl：从右到左。

示例

const localeInfo = configuration.getLocale();
console.info(localeInfo.language);

定时器

导入模块

无需导入。

权限列表

无

setTimeout

设置一个定时器，该定时器在定时器到期后执行一个函数：setTimeout(handler[,delay[,…args]]): number

参数

参数名	类型	必填	说明
handler	Function	是	定时器到期后执行函数。
delay	number	否	延迟的毫秒数，函数的调用会在该延迟之后发生。如果省略该参数，delay取默认值0，意味着“马上”执行，或尽快执行。
...args	Array<any>	否	附加参数，一旦定时器到期，它们会作为参数传递给handler。

返回值

类型

说明

number

timeout定时器的ID。

示例

var timeoutID = setTimeout(function() {
    console.log('delay 1s');
 }, 1000);

clearTimeout

clearTimeout(timeoutID: number): void

取消了先前通过调用setTimeout()建立的定时器。

参数

参数名

类型

必填

说明

timeoutID

number

是

要取消定时器的ID，是由setTimeout()返回的。

示例

var timeoutID = setTimeout(function() {
    console.log('do after 1s delay.');
 }, 1000);
clearTimeout(timeoutID);

setInterval

setInterval(handler[, delay[, ...args]]): number

重复调用一个函数，在每次调用之间具有固定的时间延迟。

参数

参数名	类型	必填	说明
handler	Function	是	要重复调用的函数。
delay	number	否	延迟的毫秒数（一秒等于1000毫秒），函数的调用会在该延迟之后发生。
...args	Array<any>	否	附加参数，一旦定时器到期，他们会作为参数传递给handler。

返回值

类型

说明

number

intervallID重复定时器的ID。

示例

var intervalID = setInterval(function() {
    console.log('do very 1s.');
 }, 1000);

clearInterval

clearInterval(intervalID: number): void

可取消先前通过 setInterval() 设置的重复定时任务。

参数

参数名

类型

必填

说明

intervalID

number

是

要取消的重复定时器的ID，是由 setInterval() 返回的。

示例

var intervalID = setInterval(function() {
    console.log('do very 1s.');
 }, 1000);
clearInterval(intervalID);

网络

导入模块

import http from '@ohos.net.http';

http.createHttp

创建一个HTTP请求，支持发起请求、中断请求。

返回值

表 1 HttpRequest

返回值名称

类型

说明

HttpRequest

Object

HTTP请求对象，支持request、requestInStream、on、off、destroy等方法。
示例
```
let httpRequest = http.createHttp();
```

httpRequest.request

向URL地址，发起HTTP请求，通过注册异步回调方法，处理响应结果。

参数

表 2 request

参数名称

类型

说明

url

string

请求地址。

HttpRequestOptions

Object

请求参数结构如下：

{ method: String,

header: String,

clientCert: String,

extraData: null, }

其中method支持GET、POST、PUT、DELETE等常用方法。

AsyncCallback

Function

参数responseCode，类型number：请求返回的响应码。

参数data，类型string|ArrayBuffer：请求返回的数据内容。

示例

let httpRequest = http.createHttp();
httpRequest.request(
    "http://www.foo.com/img/test.png",
    {
        method: "GET",
        header: null,
        clientCert: null,
        extraData: null,
    },
    (responseCode, data) => {
        console.info('Result CallBack');
        if (responseCode == 200) {
            console.info('Http request Success: responseCode: ' + JSON.stringify(responseCode));
            console.info('Http request Success: data: ' + JSON.stringify(data.result));
        } else {
            console.info('Http request Fail: responseCode: ' + JSON.stringify(responseCode));
            console.info('Http request Fail: data: ' + JSON.stringify(data.result));
        }
    }
);

示例代码

注意示例应用非商用应用，示例代码使用的网络地址、消息填充等仅用于接口功能验证，禁止用于商用应用。网络协议示例应用如下：

http接口测试示例应用：httptest
websocket接口测试示例应用：websockettest
network连接状态接口示例代码：map_sample/entry//samples/js_samples/map_sample/entry/src/main/js/MainAbility/pages/network/network.js

蓝牙ble

导入模块

import ble from '@ohos.bluetooth.ble';

ble.createGattClientDevice

createGattClientDevice(deviceId?: string): GattClientDevice

创建一个可使用的GattClientDevice实例。

系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

类型	说明
GattClientDevice	client端类，使用client端方法之前需要创建该类的实例进行操作。

示例：

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
if (device != undefined) {
    console.info("create success")
}

ble.createGattServer

createGattServer(): GattServer

创建GattServer实例，表示GATT连接中的server端。

系统能力：SystemCapability.Communication.Bluetooth.Core
返回值：

类型	说明
GattServer	server端类，使用server端方法之前需要创建该类的实例进行操作。

示例：

let server = ble.createGattServer();
if (server == undefined) {
    console.info("create server failed!")
}

ble.getConnectedBLEDevices

getConnectedBLEDevices(): Array<string>

获取和当前设备连接的BLE设备。当前接口暂不支持

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
返回值：

类型	说明
Array<string>	返回当前设备作为Server端时连接BLE设备地址集合。基于信息安全考虑，此处获取的设备地址为随机MAC地址。 - 配对成功后，该地址不会变更。 - 已配对设备取消配对后重新扫描或蓝牙服务下电时，该随机地址会变更。

示例：

let result = ble.getConnectedBLEDevices();

ble.startBLEScan

startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): number

发起BLE扫描流程。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
filters	Array<ScanFilter>	是	表示扫描结果过滤策略集合，符合过滤条件的设备发现会保留。如果不使用过滤的方式，该参数设置为null。
options	ScanOptions	否	表示扫描的参数配置，可选参数。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

function onReceiveEvent(data) {
    console.info('BLE scan device find result = '+ JSON.stringify(data));
}

ble.on("BLEDeviceFind", onReceiveEvent);
let scanFilter = {
        deviceId:"XX:XX:XX:XX:XX:XX",
        name:"test",
        serviceUuid:"00001888-0000-1000-8000-00805f9b34fb"
    };
let scanOptions = {
    interval: 500,
    dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER,
    matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE
}
let ret = ble.startBLEScan([scanFilter],scanOptions);

ble.stopBLEScan

stopBLEScan(): number

停止BLE扫描流程。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：
```
let ret = ble.stopBLEScan();
```

ble.startAdvertising（同步接口）

startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): number

开始发送BLE广播。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
setting	AdvertiseSetting	是	BLE广播的相关参数。
advData	AdvertiseData	是	BLE广播包内容。
advResponse	AdvertiseData	否	BLE回复扫描请求回复响应。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

let manufactureValueBuffer = new Uint8Array(4);
manufactureValueBuffer[0] = 1;
manufactureValueBuffer[1] = 2;
manufactureValueBuffer[2] = 3;
manufactureValueBuffer[3] = 4;

let serviceValueBuffer = new Uint8Array(4);
serviceValueBuffer[0] = 4;
serviceValueBuffer[1] = 6;
serviceValueBuffer[2] = 7;
serviceValueBuffer[3] = 8;
console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer));
console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer));

let setting = {
    interval:150,
    txPower:0,
    connectable:true
};
let manufactureDataUnit = {
    manufactureId:4567,
    manufactureValue:manufactureValueBuffer.buffer
};
let serviceDataUnit = {
    serviceUuid:"00001888-0000-1000-8000-00805f9b34fb",
    serviceValue:serviceValueBuffer.buffer
};
let advData = {
    serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"],
    manufactureData:[manufactureDataUnit],
    serviceData:[serviceDataUnit]
};
let advResponse = {
    serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"],
    manufactureData:[manufactureDataUnit],
    serviceData:[serviceDataUnit]
};
let ret = ble.startAdvertising(setting, advData ,advResponse);

ble.stopAdvertising（同步接口）

stopAdvertising(): number

停止发送BLE广播。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：
```
let ret = ble.stopAdvertising();
```

ble.startAdvertising（异步回调接口）

startAdvertising(advertisingParams: AdvertisingParams, callback: AsyncCallback<number, number>): void

开始发送BLE广播。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
advertisingParams	AdvertisingParams	是	启动BLE广播的相关参数。
callback	AsyncCallback<number, number>	是	错误码和广播ID标识，通过注册回调函数获取。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

let manufactureValueBuffer = new Uint8Array(4);
manufactureValueBuffer[0] = 1;
manufactureValueBuffer[1] = 2;
manufactureValueBuffer[2] = 3;
manufactureValueBuffer[3] = 4;

let serviceValueBuffer = new Uint8Array(4);
serviceValueBuffer[0] = 4;
serviceValueBuffer[1] = 6;
serviceValueBuffer[2] = 7;
serviceValueBuffer[3] = 8;
console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer));
console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer));

let setting = {
    interval:150,
    txPower:0,
    connectable:true,
};
let manufactureDataUnit = {
    manufactureId:4567,
    manufactureValue:manufactureValueBuffer.buffer
};
let serviceDataUnit = {
    serviceUuid:"00001888-0000-1000-8000-00805f9b34fb",
    serviceValue:serviceValueBuffer.buffer
};
let advData = {
    serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"],
    manufactureData:[manufactureDataUnit],
    serviceData:[serviceDataUnit]
};
let advResponse = {
    serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"],
    manufactureData:[manufactureDataUnit],
    serviceData:[serviceDataUnit]
};
let advertisingParams = {
    advertisingSettings: setting,
    advertisingData: advData,
    advertisingResponse: advResponse,
    duration: 0
}
let advHandle = 0xFF;
ble.startAdvertising(advertisingParams, (err, outAdvHandle) => {
    if (err) {
        return;
    } else {
        advHandle = outAdvHandle;
        console.info("advHandle: " + advHandle);
    }
});

ble.stopAdvertising（异步回调接口）

stopAdvertising(advertisingId: number, callback: AsyncCallback<number>): void

停止发送BLE广播。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
advertisingId	number	是	需要停止的广播ID标识。
callback	AsyncCallback<number>	是	回调函数。

错误码：

错误码ID	错误信息
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

let manufactureValueBuffer = new Uint8Array(4);
manufactureValueBuffer[0] = 1;
manufactureValueBuffer[1] = 2;
manufactureValueBuffer[2] = 3;
manufactureValueBuffer[3] = 4;

let serviceValueBuffer = new Uint8Array(4);
serviceValueBuffer[0] = 4;
serviceValueBuffer[1] = 6;
serviceValueBuffer[2] = 7;
serviceValueBuffer[3] = 8;
console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer));
console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer));

let setting = {
    interval:150,
    txPower:0,
    connectable:true
};
let manufactureDataUnit = {
    manufactureId:4567,
    manufactureValue:manufactureValueBuffer.buffer
};
let serviceDataUnit = {
    serviceUuid:"00001888-0000-1000-8000-00805f9b34fb",
    serviceValue:serviceValueBuffer.buffer
};
let advData = {
    serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"],
    manufactureData:[manufactureDataUnit],
    serviceData:[serviceDataUnit]
};
let advResponse = {
    serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"],
    manufactureData:[manufactureDataUnit],
    serviceData:[serviceDataUnit]
};
let advertisingParams = {
    advertisingSettings: setting,
    advertisingData: advData,
    advertisingResponse: advResponse,
    duration: 0
}
let advHandle = 0xFF;
ble.startAdvertising(advertisingParams, (err, outAdvHandle) => {
    if (err) {
        return;
    } else {
        advHandle = outAdvHandle;
        console.info("advHandle: " + advHandle);
    }
});

ble.stopAdvertising(advHandle, (err) => {
    if (err) {
        return;
    }
});

ble.on('advertisingStateChange')

on(type: 'advertisingStateChange', callback: Callback<AdvertisingStateChangeInfo>): number

订阅BLE广播状态。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"advertisingStateChange"字符串，表示广播状态事件。
callback	Callback<AdvertisingStateChangeInfo>	是	表示回调函数的入参，广播状态。回调函数由用户创建通过该接口注册。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900099	Operation failed.

示例：

function onReceiveEvent(data) {
    console.info('bluetooth advertising state = ' + JSON.stringify(data));
}

let ret = ble.on('advertisingStateChange', onReceiveEvent);

ble.off('advertisingStateChange')

off(type: 'advertisingStateChange', callback?: Callback<AdvertisingStateChangeInfo>): number

取消订阅BLE广播状态。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"advertisingStateChange"字符串，表示广播状态事件。
callback	Callback<AdvertisingStateChangeInfo>	否	表示取消订阅广播状态上报。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900099	Operation failed.

示例：

function onReceiveEvent(data) {
    console.info('bluetooth advertising state = ' + JSON.stringify(data));
}

let ret = ble.on('advertisingStateChange', onReceiveEvent);
ret = ble.off('advertisingStateChange', onReceiveEvent);

ble.on('BLEDeviceFind')

on(type: 'BLEDeviceFind', callback: Callback<Array<ScanResult>>): number

订阅BLE设备发现上报事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"BLEDeviceFind"字符串，表示BLE设备发现事件。
callback	Callback<Array<ScanResult>>	是	表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900099	Operation failed.

示例：

function onReceiveEvent(data) {
    console.info('bluetooth device find = '+ JSON.stringify(data));
}

let ret = ble.on('BLEDeviceFind', onReceiveEvent);

ble.off('BLEDeviceFind')

off(type: 'BLEDeviceFind', callback?: Callback<number, Array<ScanResult>>): number

取消订阅BLE设备发现上报事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"BLEDeviceFind"字符串，表示BLE设备发现事件。
callback	Callback<number, Array<ScanResult>>	否	表示取消订阅BLE设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900099	Operation failed.

示例：

function onReceiveEvent(code, data) {
    if (code != 0) {
        return
    }
    console.info('bluetooth device find = '+ JSON.stringify(data));
}

ble.on('BLEDeviceFind', onReceiveEvent);
ble.off('BLEDeviceFind', onReceiveEvent);

GattClientDevice

client端类，使用client端方法之前需要创建该类的实例进行操作，通过createGattClientDevice(deviceId: string)方法构造此实例。

Mtu

client协商远端蓝牙低功耗设备的最大传输单元(Maximum Transmission Unit, MTU)，系统默认值设置512，不支持修改

connect

connect(deviceId?: string): number

client端发起连接远端蓝牙低功耗设备。若未输入参数，则向未连接的第一个deviceID发起连接；若输入参数，则向指定远端发起连接。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let ret = device.connect();

disconnect

disconnect(deviceId?: string): number

client端断开与远端蓝牙低功耗设备的连接。若未输入参数，则断开客户端当前所有连接；若输入参数，则只断开deviceId对应的远端的连接。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let ret = device.connect();
ret = device.disconnect();

close

close():number

关闭客户端功能，注销client在协议栈的注册，调用该接口后GattClientDevice实例将不能再使用。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let ret = device.close();

getDeviceMtu

getDeviceMtu(deviceId: string, callback: AsyncCallback<number, number>): void

client获取与指示远端协商后的mtu。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	是	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
callback	AsyncCallback<number>	是	client读取与对端协商后的mtu值。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2901000	Read forbidden.
2900099	Operation failed.

示例：

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let ret = device.connect();
device.getDeviceMtu('XX:XX:XX:XX:XX:XX', (err, data)=> {
    console.info('get device mtu err ' + JSON.stringify(err));
    console.info('mtu: ' + JSON.stringify(data));
});

getDeviceName

getDeviceName(callback: AsyncCallback<number, string>, deviceId?: string): void

client获取指示远端的蓝牙低功耗设备名。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
callback	AsyncCallback<number, string>	是	client获取对端server设备名，通过注册回调函数获取。

错误码：

错误码ID	错误信息
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
2900001	Service stopped.
2900099	Operation failed.

示例：

let gattClient = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX");
gattClient.connect();
gattClient.getDeviceName((err, data)=> {
    console.info('device name err ' + JSON.stringify(err));
    console.info('device name' + JSON.stringify(data));
}, "XX:XX:XX:XX:XX:XX")

getServices

getServices(callback: AsyncCallback<number, Array<GattService>>, deviceId?: string): void

client端获取蓝牙低功耗设备的所有服务，即服务发现。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
callback	AsyncCallback<number, Array<GattService>>	是	client进行服务发现，通过注册回调函数获取。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
2900001	Service stopped.
2900099	Operation failed.

示例：

let getServices = (code, gattServices) => {
    if (code != 0) {
        console.info('bluetooth code is ' + code);
        return;
    }
    let services = gattServices;
    console.info('bluetooth services size is ', services.length);
    for (let i = 0; i < services.length; i++) {
        console.info('bluetooth serviceUuid is ' + services[i].serviceUuid);
    }
}

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.connect();
device.getServices(getServices, 'XX:XX:XX:XX:XX:XX');

readCharacteristicValue

readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<number, BLECharacteristic>, deviceId?: string): void

client端读取蓝牙低功耗设备特定服务的特征值。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
characteristic	BLECharacteristic	是	待读取的特征值。
callback	AsyncCallback<number, BLECharacteristic>	是	client读取特征值，通过注册回调函数获取。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2901000	Read forbidden.
2900099	Operation failed.

示例：

function readCcc(code, BLECharacteristic) {
  if (code != 0) {
      return;
  }
  console.info('bluetooth characteristic uuid: ' + BLECharacteristic.characteristicUuid);
  let value = new Uint8Array(BLECharacteristic.characteristicValue);
  console.info('bluetooth characteristic value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]);
}

let descriptors = [];
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
    characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
    descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB',
    descriptorValue: bufferDesc
};
descriptors[0] = descriptor;

let bufferCCC = new ArrayBuffer(8);
let cccV = new Uint8Array(bufferCCC);
cccV[0] = 1;
let characteristic = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
    characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
    characteristicValue: bufferCCC,
    descriptors:descriptors
};

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.readCharacteristicValue(characteristic, readCcc, 'XX:XX:XX:XX:XX:XX');

readDescriptorValue

readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<number, BLEDescriptor>, deviceId?: string): void

client端读取蓝牙低功耗设备特定的特征包含的描述符。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
descriptor	BLEDescriptor	是	待读取的描述符。
callback	AsyncCallback<number, BLEDescriptor>	是	client读取描述符，通过注册回调函数获取。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2901000	Read forbidden.
2900099	Operation failed.

示例：

function readDesc(code, BLEDescriptor) {
    if (code != 0) {
        return;
    }
    console.info('bluetooth descriptor uuid: ' + BLEDescriptor.descriptorUuid);
    let value = new Uint8Array(BLEDescriptor.descriptorValue);
    console.info('bluetooth descriptor value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]);
}

let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
    characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
    descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB',
    descriptorValue: bufferDesc
};

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.readDescriptorValue(descriptor, readDesc, 'XX:XX:XX:XX:XX:XX');

writeCharacteristicValue

writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<number>, deviceId?: string): void

client端向低功耗蓝牙设备写入特定的特征值。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
characteristic	BLECharacteristic	是	蓝牙设备特征对应的二进制值及其它参数。
writeType	GattWriteType	是	蓝牙设备特征的写入类型。
callback	AsyncCallback<number>	是	回调函数。当写入成功，number为0，否则为错误对象。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2901001	Write forbidden.
2900099	Operation failed.

示例：

let descriptors = [];
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
      characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
      descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB',
    descriptorValue: bufferDesc
};
descriptors[0] = descriptor;

let bufferCCC = new ArrayBuffer(8);
let cccV = new Uint8Array(bufferCCC);
cccV[0] = 1;
let characteristic = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
      characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
      characteristicValue: bufferCCC,
    descriptors: descriptors
};
function writeCharacteristicValueCallBack(code) {
    if (code != null) {
        return;
    }
    console.info('bluetooth writeCharacteristicValue success');
}

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE, writeCharacteristicValueCallBack, 'XX:XX:XX:XX:XX:XX');

writeDescriptorValue

writeDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<number>, deviceId?: string): void

client端向低功耗蓝牙设备特定的描述符写入二进制数据。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
descriptor	BLEDescriptor	是	蓝牙设备描述符的二进制值及其它参数。
callback	AsyncCallback<number>	是	回调函数。当写入成功，number为0，否则为错误对象。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2901001	Write forbidden.
2900099	Operation failed.

示例：

let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 22;
let descriptor = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
    characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
    descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB',
    descriptorValue: bufferDesc
};

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.writeDescriptorValue(descriptor, (err) => {
    if (err) {
        console.info('notifyCharacteristicChanged callback failed');
    } else {
        console.info('notifyCharacteristicChanged callback successful');
    }
}, 'XX:XX:XX:XX:XX:XX');

getRssiValue

getRssiValue(callback: AsyncCallback<number, number>, deviceId?: string): void

client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用connect接口连接成功后才能使用。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
callback	AsyncCallback<number, number>	是	返回信号强度。单位 dBm，通过注册回调函数获取。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900099	Operation failed.

示例：

let gattClient = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX");
gattClient.connect();
gattClient.getRssiValue((err, rssi)=> {
    console.info('rssi err ' + JSON.stringify(err));
    console.info('rssi value' + JSON.stringify(rssi));
}, 'XX:XX:XX:XX:XX:XX')

setCharacteristicChangeNotification

setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<number>, deviceId?: string): void

向服务端发送设置通知此特征值请求。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
characteristic	BLECharacteristic	是	蓝牙低功耗特征。
enable	boolean	是	启用接收notify设置为true，否则设置为false。
callback	AsyncCallback<number>	是	回调函数。当发送成功，number为0，否则为错误对象。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900099	Operation failed.

示例：

let descriptors = [];
let arrayBuffer = new ArrayBuffer(8);
let descV = new Uint8Array(arrayBuffer);
descV[0] = 0x01;
let descriptor = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
      characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
      descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB',
    descriptorValue: arrayBuffer
};
descriptors[0] = descriptor;
let arrayBufferC = new ArrayBuffer(8);
let cccV = new Uint8Array(bufferCCC);
cccV[0] = 1;
let characteristic = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
      characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
    characteristicValue: arrayBufferC,
    descriptors:descriptors
};

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.setCharacteristicChangeNotification(characteristic, true, (err) => {
    if (err) {
        console.info('notifyCharacteristicChanged callback failed');
    } else {
        console.info('notifyCharacteristicChanged callback successful');
    }
}, 'XX:XX:XX:XX:XX:XX');

setCharacteristicChangeIndication

setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<number>, deviceId?: string): void

向服务端发送设置通知此特征值请求，需要对端设备的回复。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	否	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
characteristic	BLECharacteristic	是	蓝牙低功耗特征。
enable	boolean	是	启用接收notify设置为true，否则设置为false。
callback	AsyncCallback<number>	是	回调函数。当发送成功，number为undefined，否则为错误对象。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900099	Operation failed.

示例：

let descriptors = [];
let arrayBuffer = new ArrayBuffer(8);
let descV = new Uint8Array(arrayBuffer);
descV[0] = 11;
let descriptor = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
      characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
      descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB',
    descriptorValue: arrayBuffer
};
descriptors[0] = descriptor;
let arrayBufferC = new ArrayBuffer(8);
let cccV = new Uint8Array(bufferCCC);
cccV[0] = 1;
let characteristic = {
    serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
      characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
    characteristicValue: arrayBufferC,
    descriptors:descriptors
};

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.setCharacteristicChangeIndication(characteristic, false, (err) => {
if (err) {
      console.info('notifyCharacteristicChanged callback failed');
} else {
      console.info('notifyCharacteristicChanged callback successful');
}
}, 'XX:XX:XX:XX:XX:XX');

on('BLECharacteristicChange')

on(type: 'BLECharacteristicChange', callback: Callback<number, string, BLECharacteristic>): void

订阅蓝牙低功耗设备的特征值变化事件。需要先调用setCharacteristicChangeNotification接口或setCharacteristicChangeIndication接口才能接收server端的通知。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"BLECharacteristicChange"字符串，表示特征值变化事件。
callback	Callback<number, string, BLECharacteristic>	是	表示蓝牙低功耗设备的特征值变化事件的回调函数。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

function CharacteristicChange(code, deviceId, characteristicChangeReq) {
    if (code != 0) {
        return
    }
    let serviceUuid = characteristicChangeReq.serviceUuid;
    let characteristicUuid = characteristicChangeReq.characteristicUuid;
    let value = new Uint8Array(characteristicChangeReq.characteristicValue);
}

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.on('BLECharacteristicChange', CharacteristicChange);

off('BLECharacteristicChange')

off(type: 'BLECharacteristicChange', callback?: Callback<number, string, BLECharacteristic>): void

取消订阅蓝牙低功耗设备的特征值变化事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"BLECharacteristicChange"字符串，表示特征值变化事件。
callback	Callback<number, string, BLECharacteristic>	否	表示取消订阅蓝牙低功耗设备的特征值变化事件。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.off('BLECharacteristicChange');

on('BLEConnectionStateChange')

on(type: 'BLEConnectionStateChange', callback: Callback<number, BLEConnectionChangeState>): void

client端订阅蓝牙低功耗设备的连接状态变化事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。
callback	Callback<number, BLEConnectionChangeState>	是	表示连接状态，已连接或断开。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

function ConnectStateChanged(code, deviceId, state) {
    if (code != 0) {
        return
    }
    console.info('bluetooth connect state changed');
    let connectState = state.state;
}

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.on('BLEConnectionStateChange', ConnectStateChanged);

off('BLEConnectionStateChange')

off(type: 'BLEConnectionStateChange', callback?: Callback<number, string, BLEConnectionChangeState>): void

取消订阅蓝牙低功耗设备的连接状态变化事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。
callback	Callback<number, string, BLEConnectionChangeState>	否	表示取消订阅蓝牙低功耗设备的连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.off('BLEConnectionStateChange');

GattServer

server端类，使用server端方法之前需要创建该类的实例进行操作，通过createGattServer()方法构造此实例。

addService

addService(service: GattService, callback: AsyncCallback<number, GattService>): void

server端添加服务。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
service	GattService	是	添加的服务。
callback	AsyncCallback<number, GattService>	是	回调函数。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

let server = ble.createGattServer();

let descriptors = [];
let arrayBuffer = new ArrayBuffer(2);
let descV = new Uint8Array(arrayBuffer);
descV[0] = 0x01;
descV[1] = 0x00;
let descriptor = {
    serviceUuid: '180f',
    characteristicUuid: '2a19',
    descriptorUuid: '2902',
    descriptorValue: arrayBuffer,
};
descriptors[0] = descriptor;
let arrayBufferC = new ArrayBuffer(1);
let cccV = new Uint8Array(arrayBufferC);
cccV[0] = 0x58;
let propertie = {
    write: true,
    writeNoResponse: true,
    read: true,
    notify: true,
    indicate: true,
};
let characteristic = {
    serviceUuid: '180f',
    characteristicUuid: '2a19',
    characteristicValue: arrayBufferC,
    descriptors: descriptors,
    properties: propertie,
};
let serviceIn = {
    serviceUuid: '180f',
    isPrimary: true,
    characteristics: [characteristic],
    includeServices : [],
};

server.addService(serviceIn, (err, resultService) => {
    if (err != 0) {
        console.info('addService callback failed');
    } else {
        console.log('Add service success: ' + JSON.stringify(resultService));
    }
});

removeService

removeService(serviceUuid: string，callback: AsyncCallback<number>): void

删除server端已添加的服务。当前暂不支持。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
serviceUuid	string	是	特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。
callback	AsyncCallback<number>	是	回调函数。当写入成功，number为0，否则为错误对象。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

let server = ble.createGattServer();
server.removeService(this.serviceHandle.serviceUuid, (err) => {
    if (err != 0) {
        console.error('Remove service failed: ' + err);
    } else {
        console.log('Remove service success');
    }
});

close

close(): number

销毁server端实例,注销server在协议栈的注册，调用该接口后GattServer实例将不能再使用。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900099	Operation failed.

示例：

let server = ble.createGattServer();
let ret = server.close();

notifyCharacteristicChanged

notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic, callback: AsyncCallback<number>): void

server端发送特征值变化通知或者指示给client端。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
deviceId	string	是	接收通知的client设备地址，例如："XX:XX:XX:XX:XX:XX"。
notifyCharacteristic	NotifyCharacteristic	是	蓝牙低功耗特征。
callback	AsyncCallback<number>	是	回调函数。当发送成功，number为0，否则为错误对象。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900099	Operation failed.

示例：

let server = ble.createGattServer();
let bufferDesc = new ArrayBuffer(1);
let uint8View = new Uint8Array(bufferDesc);
uint8View[0] = 0x12;
let notifyCharacteristic = {
    serviceUuid: '180f',
    characteristicUuid: '2a19',
    characteristicValue: bufferDesc,
    confirm: true // false = 通知, true = 指示
};
// 连接回调返回大端deviceid，传大端deviceid，对端设备的deviceid可能变化
server.notifyCharacteristicChanged("69:7f:17:6b:a0:f4", notifyCharacteristic, (err) => {
    if (err) {
        console.error('Send notification failed for device ' + ': ' + err);
    } else {
        console.log('Notification sent successfully to device:');
    }
});

on('characteristicRead')

on(type: 'characteristicRead', callback: Callback<CharacteristicReadRequest>): void

server端订阅client的特征值读请求事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"characteristicRead"字符串，表示特征值读请求事件。
callback	Callback<CharacteristicReadRequest>	是	表示收到client端发送的特征值读请求的回调函数。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();
function CharacteristicRead(CharacteristicReadReq) {
    console.log('CharacteristicRead success: ' + JSON.stringify(CharacteristicReadReq));
}
server.on('characteristicRead', CharacteristicRead);

off('characteristicRead')

off(type: 'characteristicRead', callback?: Callback<CharacteristicReadRequest>): void

server端取消订阅client的特征值读请求事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"characteristicRead"字符串，表示特征值读请求事件。
callback	Callback<CharacteristicReadRequest>	否	表示取消订阅特征值读请求事件。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();
server.off('characteristicRead');

on('characteristicWrite')

on(type: 'characteristicWrite', callback: Callback<CharacteristicWriteRequest>): void

server端订阅client的特征值写请求事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"characteristicWrite"字符串，表示特征值写请求事件。
callback	Callback<CharacteristicWriteRequest>	是	表示收到client的特征值写请求的回调函数。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();

function CharacteristicWrite(characteristicWriteReq) {
    console.info('CharacteristicWrite success: ' + JSON.stringify(characteristicWriteReq));
    // 读取ArrayBuffer内容
    const buffer = characteristicWriteReq.value;
    console.info('value length:'+ buffer.byteLength); // 先打印长度，确认是否有数据
    const uint8View = new Uint8Array(buffer);
    console.info('value content:'+ uint8View);
}
server.on('characteristicWrite', CharacteristicWrite);

off('characteristicWrite')

off(type: 'characteristicWrite', callback?: Callback<CharacteristicWriteRequest>): void

server端取消订阅client的特征值写请求事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"characteristicWrite"字符串，表示特征值写请求事件。
callback	Callback<CharacteristicWriteRequest>	否	表示取消订阅特征值写请求事件。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();
server.off('characteristicWrite');

on('descriptorRead')

on(type: 'descriptorRead', callback: Callback<DescriptorReadRequest>): void

server端订阅client的描述符读请求事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"descriptorRead"字符串，表示描述符读请求事件。
callback	Callback<DescriptorReadRequest>	是	表示收到client的描述符读请求的回调函数。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();

function DescriptorRead(descriptorReadReq) {
    console.log('DescriptorRead success: ' + JSON.stringify(descriptorReadReq));
}
server.on('descriptorRead', DescriptorRead);

off('descriptorRead')

off(type: 'descriptorRead', callback?: Callback<DescriptorReadRequest>): void

server端取消订阅client的描述符读请求事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"descriptorRead"字符串，表示描述符读请求事件。
callback	Callback<DescriptorReadRequest>	否	表示取消订阅描述符读请求事件。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();
server.off('descriptorRead');

on('descriptorWrite')

on(type: 'descriptorWrite', callback: Callback<DescriptorWriteRequest>): void

server端订阅client的描述符写请求事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"descriptorWrite"字符串，表示描述符写请求事件。
callback	Callback<DescriptorWriteRequest>	是	表示收到client的描述符写请求的回调函数。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();

function DescriptorWrite(descriptorWriteReq) {
    console.log('DescriptorWrite success: ' + JSON.stringify(descriptorWriteReq));
    // 读取ArrayBuffer内容
    const buffer = descriptorWriteReq.value;
    console.info('value length:'+ buffer.byteLength); // 先打印长度，确认是否有数据
    const uint8View = new Uint8Array(buffer);
    console.info('value content:'+ uint8View);
}
server.on('DescriptorWrite', DescriptorWrite);

off('descriptorWrite')

off(type: 'descriptorWrite', callback?: Callback<DescriptorWriteRequest>): void

server端取消订阅client的描述符写请求事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"descriptorWrite"字符串，表示描述符写请求事件。
callback	Callback<DescriptorWriteRequest>	否	表示取消订阅描述符写请求事件。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();
server.off('descriptorWrite');

on('connectionStateChange')

on(type: 'connectionStateChange', callback: Callback<number, BLEConnectionChangeState>): void

server端订阅GATT profile协议的连接状态变化事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"connectionStateChange"字符串，表示GATT profile连接状态发生变化的事件。
callback	Callback<number, BLEConnectionChangeState>	是	表示连接状态，已连接或断开。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();

function ConnectionStateChange(code, state) {
    if (code != 0) {
        console.error('ConnectionStateChange failed!');
        return
    }
    console.info('bluetooth connect state changed');
    let connectState = state.state;
    console.info('bluetooth connect state value:' + connectState);
}
server.on('connectionStateChange', ConnectionStateChange);

off('connectionStateChange')

off(type: 'connectionStateChange', callback?: Callback<number, BLEConnectionChangeState>): void

server端取消订阅GATT profile协议的连接状态变化事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"connectionStateChange"字符串，表示GATT profile协议的连接状态变化事件。
callback	Callback<number, BLEConnectionChangeState>	否	表示取消订阅GATT profile协议的连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();
server.off('connectionStateChange');

on('BLEMtuChange')

on(type: 'BLEMtuChange', callback: Callback<number>): void

server端订阅MTU（最大传输单元）大小变更事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"BLEMtuChange"字符串，表示MTU状态变化事件。
callback	Callback<number>	是	指定订阅的回调函数，会携带协商后的MTU大小。单位：Byte。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();

function BLEMtuChange(mtu) {
    console.log('BLEMtuChange success: ' + mtu);
}
server.on('BLEMtuChange', BLEMtuChange);

off('BLEMtuChange')

off(type: 'BLEMtuChange', callback?: Callback<number>): void

server端取消订阅MTU（最大传输单元）大小变更事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH
系统能力：SystemCapability.Communication.Bluetooth.Core
参数：

参数名	类型	必填	说明
type	string	是	填写"BLEMtuChange"字符串，表示MTU状态变化事件。
callback	Callback<number>	否	表示取消订阅MTU状态变化事件。不填该参数则取消订阅该type对应的所有回调。

错误码：

错误码ID	错误信息
0	success.
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

let server = ble.createGattServer();
server.off('BLEMtuChange');

GattService

描述service的接口参数定义。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
serviceUuid	string	是	是	特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。
isPrimary	boolean	是	是	如果是主服务设置为true，否则设置为false。
characteristics	Array<BLECharacteristic>	是	是	当前服务包含的特征列表。
includeServices	Array<GattService>	是	是	当前服务依赖的其它服务。

BLECharacteristic

描述characteristic的接口参数定义。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
serviceUuid	string	是	是	特征值所属的服务的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。
characteristicUuid	string	是	是	特征值UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。
characteristicValue	ArrayBuffer	是	是	特征值的数据内容。
descriptors	Array<BLEDescriptor>	是	是	特征值包含的描述符列表。
properties	GattProperties	是	是	特征值支持的属性。
characteristicValueHandle	number	是	是	特征值的唯一标识句柄。当server端BLE蓝牙设备提供了多个相同UUID特征值时，可以通过此句柄区分不同的特征值。

BLEDescriptor

描述descriptor的接口参数定义。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
serviceUuid	string	是	是	特征值所属的服务UUID。例如：00001888-0000-1000-8000-00805f9b34fb。
characteristicUuid	string	是	是	描述符所属的特征值UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。
descriptorUuid	string	是	是	描述符UUID。例如：00002902-0000-1000-8000-00805f9b34fb。
descriptorValue	ArrayBuffer	是	是	描述符的数据内容。
descriptorHandle	number	是	是	描述符的唯一标识句柄。当server端BLE蓝牙设备提供了多个相同UUID描述符时，可以通过此句柄区分不同的描述符。

BLEConnectionChangeState

描述Gatt profile连接状态。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
deviceId	string	是	否	表示远端设备地址。例如："XX:XX:XX:XX:XX:XX"。
state	ProfileConnectionState	是	是	表示BLE连接状态的枚举。

NotifyCharacteristic

描述notifyCharacteristicChanged的接口参数定义。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
serviceUuid	string	是	是	特征值所属的服务的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。
characteristicUuid	string	是	是	特征值UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。
characteristicValue	ArrayBuffer	是	是	特征值的数据内容。
confirm	boolean	是	是	true表示发送的是指示，需要client端回复确认。false表示发送的是通知，不需要client端回复确认。

CharacteristicReadRequest

描述server端订阅client端读特征值请求事件后，接收到的事件参数结构。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
deviceId	string	是	否	client端蓝牙设备地址。例如："XX:XX:XX:XX:XX:XX"。
transId	number	是	否	client端读请求的标识符，server端回复时需填写相同的transId。
characteristicUuid	string	是	否	client端需要读取的特征值UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。
serviceUuid	string	是	否	特征值所属的服务UUID。例如：00001888-0000-1000-8000-00805f9b34fb。

CharacteristicWriteRequest

描述server端订阅client端写特征值请求事件后，接收到的事件参数结构。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
deviceId	string	是	否	client端蓝牙设备地址。例如："XX:XX:XX:XX:XX:XX"。
transId	number	是	否	client端读请求的标识符，server端回复时需填写相同的transId。
needRsp	boolean	是	否	是否需要回复client端。true表示需要回复，false表示不需要回复。
value	ArrayBuffer	是	否	client端需要给特征值写入的数据。
characteristicUuid	string	是	否	client端需要写入的特征值UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。
serviceUuid	string	是	否	特征值所属的服务UUID。例如：00001888-0000-1000-8000-00805f9b34fb。

DescriptorReadRequest

描述server端订阅client端读描述符请求事件后，接收到的事件参数结构。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
deviceId	string	是	否	client端蓝牙设备地址。例如："XX:XX:XX:XX:XX:XX"。
transId	number	是	否	client端读请求的标识符，server端回复时需填写相同的transId。
descriptorUuid	string	是	否	client端需要读取的描述符UUID。例如：00002902-0000-1000-8000-00805f9b34fb。
characteristicUuid	string	是	否	描述符所属的特征值UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。
serviceUuid	string	是	否	特征值所属的服务UUID。例如：00001888-0000-1000-8000-00805f9b34fb。

DescriptorWriteRequest

描述server端订阅client端写描述符请求事件后，接收到的事件参数结构。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
deviceId	string	是	否	client端蓝牙设备地址。例如："XX:XX:XX:XX:XX:XX"。
transId	number	是	否	client端读请求的标识符，server端回复时需填写相同的transId。
needRsp	boolean	是	否	是否需要回复client端。true表示需要回复，false表示不需要回复。
value	ArrayBuffer	是	否	client端需要给描述符写入的数据。
descriptorUuid	string	是	否	client端需要写入的描述符UUID。例如：00002902-0000-1000-8000-00805f9b34fb。
characteristicUuid	string	是	否	描述符所属的特征值UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。
serviceUuid	string	是	否	特征值所属的服务UUID。例如：00001888-0000-1000-8000-00805f9b34fb。

ScanResult

扫描结果上报数据。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明
deviceId	string	是	否	表示扫描到的设备地址。例如："XX:XX:XX:XX:XX:XX"。基于信息安全考虑，此处获取的设备地址为随机MAC地址。 - 配对成功后，该地址不会变更。 - 已配对设备取消配对后重新扫描或蓝牙服务下电时，该随机地址会变更。
rssi	number	是	否	表示扫描到的设备的rssi值。
data	ArrayBuffer	是	否	表示扫描到的设备发送的广播包。
deviceName	string	是	否	表示扫描到的设备名称。
connectable	boolean	是	否	表示扫描到的设备是否可连接。true表示可连接，false表示不可连接。

AdvertiseSetting

描述蓝牙低功耗设备发送广播的参数。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	必填	说明
interval	number	是	是	否	表示广播间隔。最小值设置32个slot表示20ms，最大值设置16777215个slot，默认值设置为1600个slot表示1s。(传统广播模式下最大值为16384个slot表示10.24s)
txPower	number	是	是	否	表示发送功率。最小值设置-127，最大值设置1，默认值设置-7，单位dbm。推荐值：高档(1)，中档(-7)，低档(-15)。
connectable	boolean	是	是	否	表示是否是可连接广播。默认值设置为true，表示可连接。false表示不可连接。

AdvertiseData

描述BLE广播数据包的内容，广播包数据长度为31个字节。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	必填	说明
serviceUuids	Array<string>	是	是	是	表示要广播的服务 UUID 列表。
manufactureData	Array<ManufactureData>	是	是	是	表示要广播的广播的制造商信息列表。
serviceData	Array<ServiceData>	是	是	是	表示要广播的服务数据列表。
includeDeviceName	boolean	是	是	否	表示是否携带设备名，可选参数。 true表示携带，false或未设置此参数表示不携带。注意：带上设备名时广播包长度不能超出31个字节。

AdvertisingParams

描述首次启动广播设置的参数。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	必填	说明
advertisingSettings	AdvertiseSetting	是	是	是	表示发送广播的相关参数。
advertisingData	AdvertiseData	是	是	是	表示广播的数据包内容。
advertisingResponse	AdvertiseData	是	是	否	表示回复扫描请求的响应内容。
duration	number	是	是	否	表示发送广播持续的时间。单位为10ms，有效范围为1(10ms)~65535(655350ms)。如果未指定此参数或者将其设置为0，则会连续发送广播。

AdvertisingStateChangeInfo

描述广播启动、停止等状态信息。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	必填	说明
advertisingId	number	是	是	是	表示广播ID标识。
state	AdvertisingState	是	是	是	表示广播状态。

ScanFilter

扫描过滤参数。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	必填	说明
deviceId	string	否	表示过滤的BLE设备地址。例如："XX:XX:XX:XX:XX:XX"。
name	string	否	表示过滤的BLE设备名。
serviceUuid	string	否	表示过滤包含该UUID服务的设备。例如：00001888-0000-1000-8000-00805f9b34fb。
serviceUuidMask	string	否	表示过滤包含该UUID服务掩码的设备。例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。
serviceSolicitationUuid	string	否	表示过滤包含该UUID服务请求的设备。例如：00001888-0000-1000-8000-00805F9B34FB。
serviceSolicitationUuidMask	string	否	表示过滤包含该UUID服务请求掩码的设备。例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。
serviceData	ArrayBuffer	否	表示过滤包含该服务相关数据的设备。例如：[0x90,0x00,0xF1,0xF2]。
serviceDataMask	ArrayBuffer	否	表示过滤包含该服务相关数据掩码的设备。例如：[0xFF,0xFF,0xFF,0xFF]。
manufactureId	number	否	表示过滤包含该制造商ID的设备。例如：0x0006。
manufactureData	ArrayBuffer	否	表示过滤包含该制造商相关数据的设备。例如：[0x1F,0x2F,0x3F]。
manufactureDataMask	ArrayBuffer	否	表示过滤包含该制造商相关数据掩码的设备。例如：[0xFF,0xFF,0xFF]。

ManufactureData

描述BLE广播数据包的内容。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	必填	说明
manufactureId	number	是	是	是	表示制造商的ID，由蓝牙SIG分配。
manufactureValue	ArrayBuffer	是	是	是	表示制造商发送的制造商数据。

ServiceData

描述广播包中服务数据内容。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	说明	必填
serviceUuid	string	是	是	表示服务的UUID。	是
serviceValue	ArrayBuffer	是	是	表示服务数据。	是

ScanOptions

扫描的配置参数。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	可读	可写	必填	说明
interval	number	是	是	否	表示扫描结果上报延迟时间，默认值为0。
dutyMode	ScanDuty	是	是	否	表示扫描模式，默认值为SCAN_MODE_LOW_POWER。
matchMode	MatchMode	是	是	否	表示硬件的过滤匹配模式，默认值为MATCH_MODE_AGGRESSIVE。
phyType	PhyType	是	是	否	表示扫描中使用的PHY类型。
reportMode	ScanReportMode	是	是	否	表示扫描结果数据上报模式。

GattProperties

描述gatt characteristic的属性。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	必填	说明
write	boolean	否	表示该特征支持写操作，true表示需要对端设备的回复。
writeNoResponse	boolean	否	true表示该特征支持写操作，无需对端设备回复。
read	boolean	否	true表示该特征支持读操作。
notify	boolean	否	true表示该特征可通知对端设备。
indicate	boolean	否	true表示该特征可通知对端设备，需要对端设备的回复。

ProfileConnectionState

枚举，蓝牙设备的profile连接状态。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	值	说明
STATE_DISCONNECTED	0	断连
STATE_CONNECTING	1	连接中
STATE_CONNECTED	2	已连接
STATE_DISCONNECTING	3	断连中

GattWriteType

枚举，表示gatt写入类型。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	值	说明
WRITE	1	表示写入特征值，需要对端设备的回复。
WRITE_NO_RESPONSE	2	表示写入特征值，不需要对端设备的回复。

ScanDuty

枚举，扫描模式。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	值	说明
SCAN_MODE_LOW_POWER	0	表示低功耗模式，默认值。
SCAN_MODE_BALANCED	1	表示均衡模式。
SCAN_MODE_LOW_LATENCY	2	表示低延迟模式。

AdvertisingState

枚举，广播状态。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	值	说明
STARTED	1	表示首次启动广播后的状态。
ENABLED	2	表示临时启动广播后的状态。
DISABLED	3	表示临时停止广播后的状态。
STOPPED	4	表示完全停止广播后的状态。

MatchMode

枚举，硬件过滤匹配模式。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	值	说明
MATCH_MODE_AGGRESSIVE	1	表示硬件上报扫描结果门限较低，比如扫描到的功率较低或者一段时间扫描到的次数较少也触发上报，默认值。
MATCH_MODE_STICKY	2	表示硬件上报扫描结果门限较高，更高的功率门限以及扫描到多次才会上报。

PhyType

枚举，扫描中使用的PHY类型。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	值	说明
PHY_LE_1M	1	表示扫描中使用1M PHY。
PHY_LE_ALL_SUPPORTED	255	表示扫描中使用蓝牙协议支持的PHY模式。

ScanReportMode

枚举，扫描结果数据上报模式。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	值	说明
NORMAL	1	表示常规扫描上报模式。

扩展接口

在 ohos_module_config.h 中定义模块名称及初始化模块入口。

const Module OHOS_MODULES[] = {
#ifdef FEATURE_MODULE_AUDIO
    {"audio", InitAudioModule},
#endif // FEATURE_MODULE_AUDIO
}

模块定义。

// AudioModule.h
class AudioModule final : public MemoryHeap {
public:
    // 模块结束时释放资源
    static void OnTerminate();
    // 自定义方法
    static JSIValue Play();
    static JSIValue Pause();
    static JSIValue SrcSetter();
    ...
}
// 模块初始化入口
void InitAudioModule(JSIValue exports);

// AudioModule.cpp
void InitAudioModule(JSIValue exports)
{
    InitAdioPlayer();
    // 绑定模块终止方法
    JSI::SetOnTerminate(exports, AudioModule::OnTerminate);
    // 绑定方法到js
    JSI::SetModuleAPI(exports, "play", AudioModule::Play);
    JSI::SetModuleAPI(exports, "pause", AudioModule::Pause);
    JSI::SetModuleAPI(exports, "stop", AudioModule::Stop);
    ...
    // 绑定属性到js
    AudioModule::DefineProperty(exports, "src", AudioModule::SrcGetter, AudioModule::SrcSetter);
    ...
}

在Deveco Studio中使用。

// index.js
import player from '@system.audio'
player.src = "test.mp3";
player.play();

参数名	类型	说明
appName	string	表示应用的名称。
versionName	string	表示应用的版本名称。
versionCode	number	表示应用的版本号。