Skip to content

D
Docs

OpenHarmony / Docs
大约 1 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs
未验证 提交 ac01967c 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!6161 补充DM功能描述和接口说明文档 

Merge pull request !6161 from 蒲辉/OpenHarmony-3.1-Release
上级 21439a53 9cac6e4a
隐藏空白更改
内联 并排
Showing with 454 addition and 22 deletion
zh-cn/application-dev/reference/apis/js-apis-device-manager.md
浏览文件 @ ac01967c
# 设备管理
本模块提供分布式设备管理能力。
系统应用可调用接口实现如下功能：
- 注册和解除注册设备上下线变化监听
- 发现周边不可信设备
- 认证和取消认证设备
- 查询可信设备列表
- 查询本地设备信息，包括设备名称，设备类型和设备标识
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> - 本模块接口为系统接口，三方应用不支持调用。
......@@ -38,19 +48,18 @@ createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager
});
```
## DeviceInfo
## DeviceStateChangeAction
表示设备状态变化的枚举。
设备信息。
**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
| 名称 | 默认值 | 说明 |
| -------- | -------- | -------- |
| ONLINE | 0 | 设备上线。 |
| READY | 1 | 设备就绪，设备信息同步已完成。 |
| OFFLINE | 2 | 设备下线。 |
| CHANGE | 3 | 设备信息更改。 |
| 名称 | 类型 | 必填 | 描述 |
| -------- | -------- | -------- | -------- |
| deviceId | string | 是 | 设备的唯一标识。 |
| deviceName | string | 是 | 设备名称。 |
| deviceType | [DeviceType](#deviceType) | 是 | 设备类型。 |
| networkId<sup>8+</sup> | string | 是 | 设备网络标识。 |
## DeviceType
......@@ -70,17 +79,109 @@ createDeviceManager(bundleName: string, callback: AsyncCallback&lt;DeviceManager
| UNKNOWN_TYPE | 0 | 未知设备 |
## DeviceInfo
## DeviceStateChangeAction
设备信息。
表示设备状态变化的枚举。
**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
| 名称 | 默认值 | 说明 |
| -------- | -------- | -------- |
| ONLINE | 0 | 设备上线。 |
| READY | 1 | 设备就绪，设备信息同步已完成。 |
| OFFLINE | 2 | 设备下线。 |
| CHANGE | 3 | 设备信息更改。 |
## SubscribeInfo
发现信息。
**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
| 名称 | 类型 | 必填 | 描述 |
| -------- | -------- | -------- | -------- |
| deviceId | number | 是 | 设备的唯一标识。 |
| deviceName | string | 是 | 设备名称。 |
| deviceType | number | 是 | 设备类型。 |
| subscribeId | number | 是 | 发现标识，用于标识不同的发现周期。 |
| mode | [DiscoverMode ](#discoverMode) | 否 | 发现模式。 |
| medium | [ExchangeMedium](#exchangeMedium) | 否 | 发现类型。 |
| freq | [ExchangeFreq](#exchangeFreq) | 否 | 发现频率。 |
| isSameAccount | boolean | 否 | 是否同账号。 |
| isWakeRemote | boolean | 否 | 是否唤醒设备。 |
| capability | [SubscribeCap](#subscribeCap) | 否 | 发现能力。 |
## DiscoverMode
表示发现模式的枚举。
**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
| 名称 | 默认值 | 说明 |
| -------- | -------- | -------- |
| DISCOVER_MODE_PASSIVE | 0x55 | 被动模式。 |
| DISCOVER_MODE_ACTIVE | 0xAA | 主动模式。 |
## ExchangeMedium
表示发现类型的枚举。
**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
| 名称 | 默认值 | 说明 |
| -------- | -------- | -------- |
| AUTO | 0 | 自动发现类型。 |
| BLE | 1 | 蓝牙发现类型。 |
| COAP | 2 | WiFi发现类型。 |
| USB | 3 | USB发现类型。 |
## ExchangeFreq
表示发现频率的枚举。
**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
| 名称 | 默认值 | 说明 |
| -------- | -------- | -------- |
| LOW | 0 | 低频率。 |
| MID | 1 | 中频率。 |
| HIGH | 2 | 高频率。 |
| SUPER_HIGH | 3 | 超高频率。 |
## SubscribeCap
表示发现能力的枚举。
**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
| 名称 | 默认值 | 说明 |
| -------- | -------- | -------- |
| SUBSCRIBE_CAPABILITY_DDMP | 0 | DDMP能力，后续会被废弃。 |
| SUBSCRIBE_CAPABILITY_OSD | 1 | OSD能力。 |
## AuthParam
认证参数。
**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
| 名称 | 类型 | 必填 | 描述 |
| -------- | -------- | -------- | -------- |
| authType | number | 是 | 认证类型。 |
| extraInfo | {[key:string] : any} | 否 | 认证参数可扩展字段。 |
## AuthInfo
认证信息。
**系统能力**：以下各项对应的系统能力均为SystemCapability.DistributedHardware.DeviceManager
| 名称 | 类型 | 必填 | 描述 |
| -------- | -------- | -------- | -------- |
| authType | number | 是 | 认证类型。 |
| token | number | 是 | 认证Token。 |
| extraInfo | {[key:string] : any} | 否 | 认证信息可扩展字段。 |
## DeviceManager
......@@ -97,7 +198,7 @@ release(): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 示例：
```
```js
dmInstance.release();
```
......@@ -116,11 +217,253 @@ getTrustedDeviceListSync(): Array&lt;DeviceInfo&gt;
| Array&lt;[DeviceInfo](#deviceinfo)&gt; | 返回可信设备列表。 |
- 示例：
```
```js
var deviceInfoList = dmInstance.getTrustedDeviceListSync();
```
### getTrustedDeviceList<sup>8+</sup>
getTrustedDeviceList(callback:AsyncCallback&lt;Array&lt;DeviceInfo&gt;&gt;): void
获取所有可信设备列表。使用callback异步回调。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;Array&lt;[DeviceInfo](#deviceinfo)&gt;&gt; | 是 | 获取所有可信设备列表的回调，返回设备信息。 |
- 示例：
```js
dmInstance.getTrustedDeviceList((err, data) => {
console.log("getTrustedDeviceList err: " + JSON.stringify(err));
console.log('get trusted device info: ' + JSON.stringify(data));
}
);
```
### getTrustedDeviceList<sup>8+</sup>
getTrustedDeviceList(): Promise&lt;Array&lt;DeviceInfo&gt;&gt;
获取所有可信设备列表。使用Promise异步回调。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 返回值：
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;Array&lt;[DeviceInfo](#deviceinfo)&gt;&gt; | Promise实例，用于获取异步返回结果。 |
- 示例：
```js
dmInstance.getTrustedDeviceList().then((data) => {
console.log('get trusted device info: ' + JSON.stringify(data));
}).catch((err) => {
console.log("getTrustedDeviceList err: " + JSON.stringify(err));
});
```
### getLocalDeviceInfoSync<sup>8+</sup>
getLocalDeviceInfoSync(): [DeviceInfo](#deviceinfo)
同步获取本地设备信息。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 返回值：
| 名称 | 说明 |
| -------- | -------- |
| Array&lt;[DeviceInfo](#deviceinfo)&gt; | 返回可信设备列表。 |
- 示例：
```js
var deviceInfo = dmInstance.getLocalDeviceInfoSync();
```
### getLocalDeviceInfo<sup>8+</sup>
getLocalDeviceInfo(callback:AsyncCallback&lt;DeviceInfo&gt;): void
获取本地设备信息。使用callback异步回调。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[DeviceInfo](#deviceinfo)&gt; | 是 | 获取本地设备信息。 |
- 示例：
```js
dmInstance.getLocalDeviceInfo((err, data) => {
console.log("getLocalDeviceInfo err: " + JSON.stringify(err));
console.log('get local device info: ' + JSON.stringify(data));
}
);
```
### getLocalDeviceInfo<sup>8+</sup>
getLocalDeviceInfo(): Promise&lt;DeviceInfo&gt;
获取本地设备信息。使用Promise异步回调。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 返回值：
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;[DeviceInfo](#deviceinfo)&gt; | Promise实例，用于获取异步返回结果。 |
- 示例：
```js
dmInstance.getLocalDeviceInfo().then((data) => {
console.log('get local device info: ' + JSON.stringify(data));
}).catch((err) => {
console.log("getLocalDeviceInfo err: " + JSON.stringify(err));
});
```
### startDeviceDiscovery
startDeviceDiscovery(subscribeInfo: SubscribeInfo): void
发现周边设备。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| subscribeInfo | [SubscribeInfo](#subscribeInfo) | 是 | 发现信息。 |
- 示例：
```js
//生成发现标识，随机数确保每次调用发现接口的标识不一致
var subscribeId = Math.floor(Math.random() * 10000 + 1000);
var subscribeInfo = {
"subscribeId": subscribeId,
"mode": 0xAA, //主动模式
"medium": 0, //自动发现类型，同时支持多种发现类型
"freq": 2, //高频率
"isSameAccount": false,
"isWakeRemote": false,
"capability": 1
};
dmInstance.startDeviceDiscovery(subscribeInfo); //当有设备发现时，通过deviceFound回调通知给应用程序
```
### stopDeviceDiscovery
stopDeviceDiscovery(subscribeId: number): void
停止发现周边设备。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| subscribeId | number | 是 | 发现标识。 |
- 示例：
```js
//入参需要和startDeviceDiscovery接口传入的subscribeId配对使用
dmInstance.stopDeviceDiscovery(subscribeId);
```
### authenticateDevice
authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: AsyncCallback<{deviceId: string, pinToken ?: number}>): void
认证设备。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| deviceInfo | [DeviceInfo](#deviceInfo) | 是 | 设备信息。 |
| authParam | [AuthParam](#authParam) | 是 | 认证参数。 |
| callback | AsyncCallback<{ deviceId: string, pinToken ?: number }> | 是 | 认证结果回调。 |
- 示例：
```js
//认证的设备信息，可以从发现的结果中获取
var deviceInfo ={
"deviceId": "XXXXXXXX",
"deviceName": "",
deviceType: 0x0E
};
let authParam = {
"authType": 1, //认证类型： 1 - 无账号PIN码认证
"extraInfo": {}
}
dmInstance.authenticateDevice(deviceInfo, authParam, (err, data) => {
if (err) {
console.info(TAG + "authenticateDevice err:" + JSON.stringify(err));
return;
}
console.info(TAG + "authenticateDevice result:" + JSON.stringify(data));
token = data.pinToken;
});
```
### unAuthenticateDevice<sup>8+</sup>
unAuthenticateDevice(deviceInfo: DeviceInfo): void
解除认证设备。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| deviceInfo | [DeviceInfo](#deviceInfo) | 是 | 设备信息。 |
- 示例：
```js
dmInstance.unAuthenticateDevice(deviceInfo);
```
### verifyAuthInfo
verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void
验证认证信息。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| authInfo | [AuthInfo](#authInfo) | 是 | 认证信息。 |
| authInfo | AsyncCallback<{ deviceId: string, level: number }> | 是 | 验证结果回调。 |
- 示例：
```js
let authInfo = {
"authType": 1,
"token": xxxxxx,
"extraInfo": {}
}
dmInstance.verifyAuthInfo(authInfo, (err, data) => {
if (err) {
console.info(TAG + "verifyAuthInfo err:" + JSON.stringify(err));
return;
}
console.info(TAG + "verifyAuthInfo result:" + JSON.stringify(data));
});
```
### on('deviceStateChange')
on(type: 'deviceStateChange', callback: Callback&lt;{ action: DeviceStateChangeAction, device: DeviceInfo }&gt;): void
......@@ -136,7 +479,7 @@ on(type: 'deviceStateChange', callback: Callback&lt;{ action: DeviceStateChange
| callback | Callback&lt;{&nbsp;action:&nbsp;[DeviceStateChangeAction](#devicestatechangeaction),&nbsp;device:&nbsp;[DeviceInfo](#deviceinfo)&nbsp;}&gt; | 是 | 指示要注册的设备状态回调，返回设备状态和设备信息。 |
- 示例：
```
```js
dmInstance.on('deviceStateChange', (data) => {
console.info("deviceStateChange on:" + JSON.stringify(data));
}
......@@ -146,7 +489,7 @@ on(type: 'deviceStateChange', callback: Callback&lt;{ action: DeviceStateChange
### off('deviceStateChange')
off(type: 'deviceStateChange', callback?: Call back&lt;{ action: DeviceStateChangeAction, device: DeviceInfo }&gt;): void
off(type: 'deviceStateChange', callback?: Callback&lt;{ action: DeviceStateChangeAction, device: DeviceInfo }&gt;): void
取消注册设备状态回调。
......@@ -159,7 +502,7 @@ off(type: 'deviceStateChange', callback?: Call back&lt;{ action: DeviceStateChan
| callback | Callback&lt;{&nbsp;action:&nbsp;[DeviceStateChangeAction](#devicestatechangeaction),&nbsp;device:&nbsp;[DeviceInfo](#deviceinfo)&nbsp;&nbsp;}&gt; | 是 | 指示要取消注册的设备状态回调，返回设备状态和设备信息。 |
- 示例：
```
```js
dmInstance.off('deviceStateChange', (data) => {
console.info('deviceStateChange' + JSON.stringify(data));
}
......@@ -167,6 +510,95 @@ off(type: 'deviceStateChange', callback?: Call back&lt;{ action: DeviceStateChan
```
### on('deviceFound')
on(type: 'deviceFound', callback: Callback&lt;{ subscribeId: number, device: DeviceInfo }&gt;): void
注册发现设备回调监听。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 注册设备发现回调，以便在发现周边设备时通知应用程序。 |
| callback | Callback&lt;{&nbsp;subscribeId: number, device: DeviceInfo&nbsp;}&gt; | 是 | 注册设备发现的回调方法。 |
- 示例：
```js
dmInstance.on('deviceFound', (data) => {
console.info("deviceFound:" + JSON.stringify(data));
}
);
```
### off('deviceFound')
off(type: 'deviceFound', callback?: Callback&lt;{ subscribeId: number, device: DeviceInfo }&gt;): void
取消注册设备发现回调。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 取消注册设备发现回调。 |
| callback | Callback&lt;{&nbsp;subscribeId: number, device: DeviceInfo&nbsp;}&gt; | 是 | 指示要取消注册的设备发现回调，返回设备状态和设备信息。 |
- 示例：
```js
dmInstance.off('deviceFound', (data) => {
console.info('deviceFound' + JSON.stringify(data));
}
);
```
### on('discoverFail')
on(type: 'discoverFail', callback: Callback&lt;{ subscribeId: number, reason: number }&gt;): void
注册设备发现失败回调监听。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 注册设备发现失败回调，以便在发现周边设备失败时通知应用程序。 |
| callback | Callback&lt;{&nbsp;subscribeId: number, reason: number&nbsp;}&gt; | 是 | 注册设备发现失败的回调方法。 |
- 示例：
```js
dmInstance.on('discoverFail', (data) => {
this.log("discoverFail on:" + JSON.stringify(data));
}
);
```
### off('discoverFail')
off(type: 'discoverFail', callback?: Callback&lt;{ subscribeId: number, reason: number }&gt;): void
取消注册设备发现失败回调。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 取消注册设备发现失败回调。 |
| callback | Callback&lt;{&nbsp;subscribeId: number, reason: number&nbsp;}&gt; | 是 | 指示要取消注册的设备发现失败回调。 |
- 示例：
```js
dmInstance.off('deviceFound', (data) => {
console.info('deviceFound' + JSON.stringify(data));
}
);
```
### on('serviceDie')
on(type: 'serviceDie', callback: () =&gt; void): void
......@@ -182,7 +614,7 @@ on(type: 'serviceDie', callback: () =&gt; void): void
| callback | ()&nbsp;=&gt;&nbsp;void | 是 | 注册serviceDie的回调方法。 |
- 示例：
```
```js
dmInstance.on("serviceDie", () => {
console.info("serviceDie on");
}
......@@ -205,9 +637,9 @@ off(type: 'serviceDie', callback?: () =&gt; void): void
| callback | ()&nbsp;=&gt;&nbsp;void | 否 | 取消注册serviceDie的回调方法。 |
- 示例：
```
```js
dmInstance.off("serviceDie", () => {
console.info("serviceDie off");
}
);
```
```
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或