Copyright (c) 2024 Shenzhen Kaihong Digital Industry Development Co., Ltd.

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

NearLink SLE NAPI 接口

简介

NearLink SLE JS 接口用于在应用侧通过 NAPI 调用 SLE 基础能力，当前接口定义位于：

sle/interface/js_interface/@ohos.sparklink.sle.d.ts

该接口提供以下能力：

• SLE 主机控制（使能/关闭、状态查询、本机地址与名称）
• 广播与扫描（开始/停止）
• 连接与配对（连接管理、配对管理、RSSI 读取）
• 状态事件订阅（SLE 状态变化、连接状态变化）

说明：本文档内容与 .d.ts 声明保持一致，仅描述当前已声明接口。

目录

/foundation/communication/communication_nearlink/sle/interface/js_interface
├── @ohos.sparklink.sle.d.ts      # NearLink SLE JS/NAPI 接口声明
└── README.md                     # 接口说明文档

接口说明

导入方式

import NearlinkSle from '@ohos.Nearlink.sle';

主要方法

类型	接口	功能说明
NearlinkSle	enableSle(): void	使能 SLE。
NearlinkSle	disableSle(): void	关闭 SLE。
NearlinkSle	getSleState(): SleDeviceState	获取本机 SLE 状态。
NearlinkSle	getLocalAddress(): SleDeviceAddress	获取本机地址。
NearlinkSle	setLocalName(name: string): void	设置本机名称。
NearlinkSle	getLocalName(): string	获取本机名称。
NearlinkSle	startAnnounce(): void	启动广播。
NearlinkSle	stopAnnounce(): void	停止广播。
NearlinkSle	startSeek(): void	启动扫描。
NearlinkSle	stopSeek(): void	停止扫描。
NearlinkSle	connect(address, callback) / connect(address): Promise<void>	连接指定设备。
NearlinkSle	disconnect(address, callback) / disconnect(address): Promise<void>	断开指定设备连接。
NearlinkSle	getConnectDevicesList(): Array<SleDeviceAddress>	获取已连接设备地址列表。
NearlinkSle	sendPairRequest(address, callback) / sendPairRequest(address): Promise<void>	向指定设备发起配对请求。
NearlinkSle	removePairedDevice(address, callback) / removePairedDevice(address): Promise<void>	删除指定已配对设备。
NearlinkSle	getPairedDevicesList(): Array<SleDeviceAddress>	获取已配对设备地址列表。
NearlinkSle	getRemotePairState(address): SlePairState	获取指定设备配对状态。
NearlinkSle	readRemoteRssi(address, callback) / readRemoteRssi(address): Promise<number>	读取指定设备 RSSI。

事件接口

类型	接口	功能说明
NearlinkSle	on('sleStateChange', callback)	订阅 SLE 状态变化事件。
NearlinkSle	off('sleStateChange', callback)	取消订阅 SLE 状态变化事件。
NearlinkSle	on('connectStateChange', callback)	订阅连接状态变化事件。
NearlinkSle	off('connectStateChange', callback)	取消订阅连接状态变化事件。

权限说明

权限	涉及接口
ohos.permission.SET_NEARLINK_SLE_STATE	enableSle、disableSle、setLocalName
ohos.permission.USE_NEARLINK_SLE	其余查询、广播、扫描、连接、配对、RSSI、事件订阅接口

错误码说明

根据 .d.ts 注释，接口可能抛出如下 BusinessError：

错误码	说明
201	权限不足（Permission denied）
801	能力不支持（Capability not supported）

数据类型说明

SleDeviceAddress

参数名	类型	说明
addrType	SleDevAddrType	地址类型。
addr	string	设备地址字符串。

SleDevAddrType

枚举值	说明
SLE_PUBLIC_ADDRESS_TYPE = 0	公有地址类型。
SLE_RANDOM_ADDRESS_TYPE = 6	随机地址类型。

SleDeviceState

枚举值	说明
SLE_STATE_ERROR = -1	错误状态。
SLE_STATE_ENABLED = 0	已使能。
SLE_STATE_ENABLING	使能中。
SLE_STATE_DISABLING	关闭中。
SLE_STATE_DISABLED	已关闭。

SlePairState

枚举值	说明
SLE_PAIR_ERROR_STATE = -1	错误状态。
SLE_PAIR_NONE_STATE = 0	未配对。
SLE_PAIR_PAIRING_STATE	配对中。
SLE_PAIR_PAIRED_STATE	已配对。

SleConnectState

枚举值	说明
SLE_CONNECT_ERROR_STATE = -1	错误状态。
SLE_CONNECT_IDLE_STATE = 0	空闲。
SLE_CONNECT_CONNECTED_STATE	已连接。
SLE_CONNECT_DISCONNECTED_STATE	已断开。
SLE_CONNECT_CONNECTING_STATE	连接中。
SLE_CONNECT_DISCONNECTING_STATE	断开中。

SleDisConnectReason

枚举值	说明
SLE_CONNECT_OR_DISCONNECT_SUCCESS = 0	连接/断开成功。
SLE_DISCONNECT_FOR_TIMEOUT = 1	超时断开。
SLE_DISCONNECT_FOR_REMOTE = 16	远端断开。
SLE_DISCONNECT_FOR_LOCAL = 17	本端断开。
SLE_DISCONNECT_FOR_UNKNOWN_REASON = 18	未知原因断开。
SLE_DISCONNECT_WITH_NONE = 255	无原因。

示例

import NearlinkSle from '@ohos.Nearlink.sle';

NearlinkSle.on('sleStateChange', (state) => {
  console.info(`SLE state changed: ${state}`);
});

NearlinkSle.on('connectStateChange', (address, connState, pairState, reason) => {
  console.info(`connect state=${connState}, pair=${pairState}, reason=${reason}, addr=${address.addr}`);
});

NearlinkSle.enableSle();

const state = NearlinkSle.getSleState();
console.info(`current sle state=${state}`);

const localAddr = NearlinkSle.getLocalAddress();
console.info(`local addr type=${localAddr.addrType}, addr=${localAddr.addr}`);

NearlinkSle.setLocalName('NearlinkDemo');
console.info(`local name=${NearlinkSle.getLocalName()}`);

NearlinkSle.startSeek();
NearlinkSle.startAnnounce();

const target = { addrType: NearlinkSle.SleDevAddrType.SLE_PUBLIC_ADDRESS_TYPE, addr: '00:11:22:33:44:55' };
NearlinkSle.connect(target).then(() => {
  console.info('connect success');
  return NearlinkSle.readRemoteRssi(target);
}).then((rssi) => {
  console.info(`remote rssi=${rssi}`);
  return NearlinkSle.disconnect(target);
}).catch((err) => {
  console.error(`nearlink error: ${JSON.stringify(err)}`);
}).finally(() => {
  NearlinkSle.stopAnnounce();
  NearlinkSle.stopSeek();
  NearlinkSle.disableSle();
});