Skip to content

D
Docs

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

通知 161
Star 293
Fork 28
D
Docs
提交 5eb8abc0 编写于 作者: Z zhutianyi
浏览文件
操作

merge flex 

Signed-off-by: Nzhutianyi <zhutianyi2@huawei.com>
上级 5ee1e894 963b82b8
隐藏空白更改
内联 并排
Showing with 12053 addition and 7112 deletion
CODEOWNERS
浏览文件 @ 5eb8abc0
......@@ -180,6 +180,7 @@ zh-cn/application-dev/reference/js-service-widget-ui/ @HelloCrease
zh-cn/application-dev/website.md @zengyawen
zh-cn/application-dev/faqs/ @zengyawen
zh-cn/application-dev/file-management/ @qinxiaowang
zh-cn/application-dev/application-test/ @HelloCrease
zh-cn/application-dev/reference/apis/js-apis-DataUriUtils.md @RayShih
zh-cn/application-dev/reference/apis/js-apis-ability-errorCode.md @RayShih
......@@ -225,7 +226,7 @@ zh-cn/application-dev/reference/apis/js-apis-application-shellCmdResult.md @RayS
zh-cn/application-dev/reference/apis/js-apis-commonEvent.md @RayShih
zh-cn/application-dev/reference/apis/js-apis-emitter.md @RayShih
zh-cn/application-dev/reference/apis/js-apis-notification.md @RayShih
zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md @RayShih
zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md @HelloCrease
zh-cn/application-dev/reference/apis/js-apis-eventhub.md @RayShih
zh-cn/application-dev/reference/apis/js-apis-Bundle.md @RayShih
zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md @RayShih
......@@ -445,3 +446,5 @@ zh-cn/application-dev/reference/apis/js-apis-net-policy.md @zengyawen
zh-cn/application-dev/reference/apis/js-apis-net-sharing.md @zengyawen
zh-cn/application-dev/reference/apis/js-apis-net-statistics.md @zengyawen
zh-cn/application-dev/reference/apis/js-apis-tlsSocket.md @zengyawen
zh-cn/application-dev/reference/apis/js-apis-reminderAgentManager.md @HelloCrease
zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md @zengyawen
en/application-dev/ability/context-userguide.md
浏览文件 @ 5eb8abc0
......@@ -235,13 +235,13 @@ export default class MainAbility extends Ability {
For details, see [FormExtensionContext](../reference/apis/js-apis-formextensioncontext.md).
### Obtaining the Context on an eTS Page
### Obtaining the Context on an ArkTS Page
In the stage model, in the `onWindowStageCreate` lifecycle of an ability, you can call `SetUIContent` of `WindowStage` to load an eTS page. In some scenarios, you need to obtain the context on the page to call related APIs.
In the stage model, in the `onWindowStageCreate` lifecycle of an ability, you can call `SetUIContent` of `WindowStage` to load an ArkTS page. In some scenarios, you need to obtain the context on the page to call related APIs.
**How to Obtain**
Use the API described in the table below to obtain the context associated with an eTS page.
Use the API described in the table below to obtain the context associated with an ArkTS page.
| API | Description |
| :------------------------------------ | :--------------------------- |
......
en/application-dev/napi/napi-guidelines.md
浏览文件 @ 5eb8abc0
......@@ -17,11 +17,11 @@ You can `import` the native .so that contains the JS processing logic. For examp
### .so Naming Rules
Each module has a .so file. For example, if the module name is `hello`, name the .so file **libhello.so**. The `nm_modname` field in `napi_module` must be `hello`, which is the same as the module name. The sample code for importing the .so file is `import hello from 'libhello.so'`.
Each module has a .so file. For example, if the module name is `hello`, name the .so file `libhello.so`. The `nm_modname` field in `napi_module` must be `hello`, which is the same as the module name. The sample code for importing the .so file is `import hello from 'libhello.so'`.
### JS Objects and Threads
The Ark engine prevents NAPIs from being called to operate JS objects in non-JS threads. Otherwise, the application will crash.
The Ark engine prevents NAPIs from being called to operate JS objects in non-JS threads. Otherwise, the application will crash. Observe the following rules:
* The NAPIs can be used only in JS threads.
* **env** is bound to a thread and cannot be used across threads. The JS object created by a NAPI can be used only in the thread, in which the object is created, that is, the JS object is bound to the **env** of the thread.
......@@ -640,8 +640,3 @@ export default {
}
}
```
## Samples
The following samples are provided for native API development:
- [`NativeAPI`: NativeAPI (eTS) (API8)](https://gitee.com/openharmony/app_samples/tree/master/Native/NativeAPI)
- [First Native C++ Application (eTS) (API9)](https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/NativeTemplateDemo)
- [Native Component (eTS) (API9) ](https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/XComponent)
zh-cn/application-dev/ability/ability-brief.md
浏览文件 @ 5eb8abc0
......@@ -32,4 +32,4 @@ Stage模型的设计，主要是为了开发者更加方便地开发出分布式
## 相关实例
针对Ability开发，有以下相关实例可供参考：
- [Page内和Page间导航跳转（eTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Ability/PageAbility)
\ No newline at end of file
- [Page内和Page间导航跳转（ArkTS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Ability/PageAbility)
\ No newline at end of file
zh-cn/application-dev/ability/context-userguide.md
浏览文件 @ 5eb8abc0
......@@ -235,13 +235,13 @@ export default class MainAbility extends Ability {
​ [FormExtensionContext](../reference/apis/js-apis-formextensioncontext.md)
### 在eTS页面中访问Context
### 在ArkTS页面中访问Context
Stage模型下，在Ability的`onWindowStageCreate`生命周期中，可以通过WindowStage的`SetUIContent`方法加载一个eTS页面。在一些场景中，需要在页面内获取Context调用相关API。
Stage模型下，在Ability的`onWindowStageCreate`生命周期中，可以通过WindowStage的`SetUIContent`方法加载一个ArkTS页面。在一些场景中，需要在页面内获取Context调用相关API。
**获取方法**
在eTS页面中通过以下全局方法获取当前页面关联的Context。
在ArkTS页面中通过以下全局方法获取当前页面关联的Context。
| 接口名 | 描述 |
| :------------------------------------ | :--------------------------- |
......
zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md
浏览文件 @ 5eb8abc0
......@@ -5,6 +5,8 @@
设备使用信息统计，包括app usage/notification usage/system usage等使用统计。例如应用使用信息统计，用于保存和查询应用使用详情（app usage）、事件日志数据（event log）、应用分组（bundle group）情况。
部件缓存的应用记录（使用历史统计和使用事件记录）会在事件上报后30分钟内刷新到数据库持久化保存。
根据设备的使用信息统计接口，开发者可以开发出健康管理类应用来实现个人设备健康使用功能，并向用户展示其个人设备的使用记录。
## 接口说明
注册相关接口包导入：
```js
......@@ -56,7 +58,6 @@ import stats from '@ohos.bundleState';
```js
import stats from '@ohos.bundleState'
// 异步方法promise方式
stats.queryBundleActiveStates(0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryBundleActiveStates promise success.');
for (let i = 0; i < res.length; i++) {
......@@ -66,19 +67,6 @@ import stats from '@ohos.bundleState';
}).catch(err => {
console.log('BUNDLE_ACTIVE queryBundleActiveStates promise failed, because: ' + err.code);
});
// 异步方法callback方式
stats.queryBundleActiveStates(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleActiveStates callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryBundleActiveStates callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleActiveStates callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleActiveStates callback result ' + JSON.stringify(res[i]));
}
}
});
```
3. 通过指定起始和结束时间查询应用使用时长统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。
......@@ -86,7 +74,6 @@ import stats from '@ohos.bundleState';
```js
import stats from '@ohos.bundleState'
// 异步方法promise方式
stats.queryBundleStateInfos(0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryBundleStateInfos promise success.');
let i = 1;
......@@ -98,21 +85,6 @@ import stats from '@ohos.bundleState';
}).catch(err => {
console.log('BUNDLE_ACTIVE queryBundleStateInfos promise failed, because: ' + err.code);
});
// 异步方法callback方式
stats.queryBundleStateInfos(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleStateInfos callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryBundleStateInfos callback success.');
let i = 1;
for(let key in res){
console.log('BUNDLE_ACTIVE queryBundleStateInfos callback number : ' + i);
console.log('BUNDLE_ACTIVE queryBundleStateInfos callback result ' + JSON.stringify(res[key]));
i++;
}
}
});
```
4. 通过指定起始和结束时间查询当前应用的事件集合，config.json中不需要配置权限。
......@@ -120,7 +92,6 @@ import stats from '@ohos.bundleState';
```js
import stats from '@ohos.bundleState'
// 异步方法promise方式
stats.queryCurrentBundleActiveStates(0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise success.');
for (let i = 0; i < res.length; i++) {
......@@ -130,19 +101,6 @@ import stats from '@ohos.bundleState';
}).catch(err => {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise failed, because: ' + err.code);
});
// 异步方法callback方式
stats.queryCurrentBundleActiveStates(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback result ' + JSON.stringify(res[i]));
}
}
});
```
5. 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。
......@@ -150,7 +108,6 @@ import stats from '@ohos.bundleState';
```js
import stats from '@ohos.bundleState'
// 异步方法promise方式
stats.queryBundleStateInfoByInterval(0, 0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise success.');
for (let i = 0; i < res.length; i++) {
......@@ -161,18 +118,6 @@ import stats from '@ohos.bundleState';
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise failed, because: ' + err.code);
});
// 异步方法callback方式
stats.queryBundleStateInfoByInterval(0, 0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback result ' + JSON.stringify(res[i]));
}
}
});
```
6. 查询（无参）当前调用者应用的使用优先级群组，config.json中不需要配置权限。
......@@ -180,43 +125,24 @@ import stats from '@ohos.bundleState';
```js
import stats from '@ohos.bundleState'
// promise方式
stats.queryAppUsagePriorityGroup().then(res => {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch(err => {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise failed. because: ' + err.code);
});
// callback方式
stats.queryAppUsagePriorityGroup((err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
```
7. 判断指定Bundle Name的应用当前是否是空闲状态，config.json中不需要配置权限，三方应用只能查询自身的空闲状态。
7. 判断指定Bundle Name的应用当前是否是空闲状态，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO，三方应用只能查询自身的空闲状态。
```js
import stats from '@ohos.bundleState'
// 异步方法promise方式
stats.isIdleState("com.ohos.camera").then(res => {
console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res));
}).catch(err => {
console.log('BUNDLE_ACTIVE isIdleState promise failed, because: ' + err.code);
});
// 异步方法callback方式
stats.isIdleState("com.ohos.camera", (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res));
}
});
```
8. 查询FA使用记录。返回数量最大不超过maxNum设置的值，若不传入maxNum参数，则默认maxNum为1000。config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。
......@@ -245,32 +171,6 @@ import stats from '@ohos.bundleState';
}).catch( err=> {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code);
});
// 异步方法callback方式
stats.getRecentlyUsedModules(1000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i]));
}
}
});
// 无maNum参数异步方法callback方式
stats.getRecentlyUsedModules((err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i]));
}
}
});
```
9. 通过指定起始和结束时间查询所有应用的通知次数，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。
......@@ -278,23 +178,12 @@ import stats from '@ohos.bundleState';
```js
import stats from '@ohos.bundleState'
// 异步方法promise方式
stats.queryAppNotificationNumber(0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise success.');
console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise result ' + JSON.stringify(res));
}).catch(err => {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise failed, because: ' + err.code);
});
// 异步方法callback方式
stats.queryAppNotificationNumber(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback success.');
console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback result ' + JSON.stringify(res));
}
});
```
10. 通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。
......@@ -309,16 +198,6 @@ import stats from '@ohos.bundleState';
}).catch(err => {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise failed, because: ' + err.code);
});
// 异步方法callback方式
stats.queryBundleActiveEventStates(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback success.');
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback result ' + JSON.stringify(res));
}
});
```
11. 查询（无参）当前调用者应用的使用优先级群组，config.json中不需要配置权限。查询（有参）指定应用的使用优先级群组，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。
......@@ -333,14 +212,6 @@ import stats from '@ohos.bundleState';
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise failed. because: ' + err.code);
});
// 无bundleName异步方法callback方式
stats.queryAppUsagePriorityGroup((err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
let bundleName = "com.ohos.camera";
// 有bundleName异步promise方式
stats.queryAppUsagePriorityGroup(bundleName).then(res => {
......@@ -348,15 +219,6 @@ import stats from '@ohos.bundleState';
}).catch(err => {
console.log('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code);
});
// 有bundleName异步方法callback方式
stats.queryAppUsagePriorityGroup(bundleName, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
```
11. 给应用名是bundleName的应用分组设置成newGroup，返回设置结果是否成功
......@@ -364,20 +226,11 @@ import stats from '@ohos.bundleState';
```javascript
import stats from '@ohos.bundleState'
// 异步方法promise
stats.setBundleGroup(this.bundleName, this.newGroup).then(() => {
console.log('BUNDLE_ACTIVE SetBundleGroup promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE SetBundleGroup promise failed. because: ' + err.code);
});
// 异步方法callback
stats.setBundleGroup(this.bundleName, this.newGroup, (err) => {
if (err) {
console.log('BUNDLE_ACTIVE SetBundleGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE SetBundleGroup callback succeeded.');
}
});
```
12. 注册应用分组变化监听回调，返回注册是否成功，当应用分组发生变化时，会给所有已注册的监听者返回回调信息
......@@ -399,22 +252,6 @@ import stats from '@ohos.bundleState';
}).catch(err => {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise failed. because: ' + err.code);
});
// 异步方法callback形式
let onBundleGroupChanged = (err,res) => {
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.');
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s oldGroup is : ' + res.oldGroup);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s newGroup is : ' + res.newGroup);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s changeReason is : ' + res.newGroup);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s userId is : ' + res.userId);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s bundleName is : ' + res.bundleName);
};
stats.registerGroupCallBack(onBundleGroupChanged, (err) => {
if (err) {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback success.');
}
});
```
13. 解除应用分组监听回调
......@@ -428,15 +265,8 @@ import stats from '@ohos.bundleState';
}).catch(err => {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise failed. because: ' + err.code);
});
// callback
stats.unRegisterGroupCallBack((err) => {
if (err) {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback success.');
}
});
```
## 相关实例
针对设备使用信息统计，有以下相关实例可供参考：
- [`DeviceUsageStatistics`：设备使用信息统计（ArkTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/DeviceUsageStatistics)
......
zh-cn/application-dev/device/usb-guidelines.md
浏览文件 @ 5eb8abc0
......@@ -4,7 +4,7 @@
## 场景介绍
Host模式下，可以获取到已经连接的设备列表，并根据需要打开和关闭设备、控制设备权限、进行数据传输等。
Host模式下，可以获取到已经连接的USB设备列表，并根据需要打开和关闭设备、控制设备权限、进行数据传输等。
## 接口说明
......@@ -19,6 +19,7 @@ USB类开放能力如下，具体请查阅[API参考文档](../reference/apis/js
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| hasRight(deviceName: string): boolean | 如果“使用者”（如各种App或系统）有权访问设备则返回true；无权访问设备则返回false。 |
| requestRight(deviceName: string): Promise&lt;boolean&gt; | 请求给定软件包的临时权限以访问设备。 |
| removeRight(deviceName: string): boolean | 移除软件包对设备的访问权限。|
| connectDevice(device: USBDevice): Readonly&lt;USBDevicePipe&gt; | 根据`getDevices()`返回的设备信息打开USB设备。 |
| getDevices(): Array&lt;Readonly&lt;USBDevice&gt;&gt; | 返回USB设备列表。 |
| setConfiguration(pipe: USBDevicePipe, config: USBConfig): number | 设置设备的配置。 |
......
zh-cn/application-dev/reference/Readme-CN.md
浏览文件 @ 5eb8abc0
# 开发参考
- [Syscap列表](syscap-list.md)
- [组件参考（基于eTS的声明式开发范式）](arkui-ts/Readme-CN.md)
- [组件参考（基于ArkTS的声明式开发范式）](arkui-ts/Readme-CN.md)
- [组件参考（兼容JS的类Web开发范式）](arkui-js/Readme-CN.md)
- [JS服务卡片UI组件参考](js-service-widget-ui/Readme-CN.md)
- [接口参考（JS及TS API）](apis/Readme-CN.md)
......
zh-cn/application-dev/reference/apis/Readme-CN.md
浏览文件 @ 5eb8abc0
......@@ -87,8 +87,9 @@
- bundle/[ModuleInfo (ModuleInfo)](js-apis-bundle-ModuleInfo.md)
- bundle/[PermissionDef (PermissionDef)](js-apis-bundle-PermissionDef.md)
- bundle/[RemoteAbilityInfo (RemoteAbilityInfo)](js-apis-bundle-remoteAbilityInfo.md)
- bundle/[ShortcutInfo (ShortcutInfo)](js-apis-bundle-ShortcutInfo.md)
- bundle/[ShortcutInfo<sup>(deprecated)</sup> (ShortcutInfo)](js-apis-bundle-ShortcutInfo.md)
- bundle/[PackInfo (PackInfo)](js-apis-bundle-PackInfo.md)
- bundleManager/[ShortcutInfo (ShortcutInfo)](js-apis-bundleManager-shortcutInfo.md)
- UI界面
- [@ohos.animator (动画)](js-apis-animator.md)
- [@ohos.curves (插值计算)](js-apis-curve.md)
......
zh-cn/application-dev/reference/apis/js-apis-accessibility-GesturePath.md 0 → 100644
浏览文件 @ 5eb8abc0
# 手势路径
GesturePath表示手势路径信息。
本模块用于创建辅助功能注入手势所需的手势路径信息。
>![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
>
>本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块
```ts
import GesturePath from "@ohos.accessibility.GesturePath";
```
## GesturePath
表示手势路径信息。
**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core
### 属性
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| ------------ | ---------------------------------------- | ---- | ---- | ------ |
| points | Array&lt;[GesturePoint](js-apis-accessibility-GesturePoint.md#gesturepoint)&gt; | 是 | 是 | 手势触摸点。 |
| durationTime | number | 是 | 是 | 手势总耗时, 单位为毫秒。 |
### constructor
constructor(durationTime: number);
构造函数。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| durationTime | number | 是 | 手势总耗时,单位为毫秒。 |
**示例：**
```typescript
let durationTime = 20;
let gesturePath = new GesturePath(durationTime);
```
zh-cn/application-dev/reference/apis/js-apis-accessibility-GesturePoint.md 0 → 100644
浏览文件 @ 5eb8abc0
# 手势触摸点
GesturePoint表示手势触摸点。
本模块用于创建辅助功能注入手势所需的手势路径的触摸点信息。
>![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
>
>本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块
```ts
import GesturePoint from "@ohos.accessibility.GesturePoint";
```
## GesturePoint
表示手势触摸点。
**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core
### 属性
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| --------- | ------ | ---- | ---- | ------- |
| positionX | number | 是 | 是 | 触摸点X坐标。 |
| positionY | number | 是 | 是 | 触摸点Y坐标。 |
### constructor
constructor(positionX: number, positionY: number);
构造函数。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| positionX | number | 是 | 触摸点X坐标。 |
| positionY | number | 是 | 触摸点Y坐标。 |
**示例：**
```typescript
let positionX = 1;
let positionY = 2;
let gesturePoint = new GesturePoint(positionX, positionY);
```
zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md
浏览文件 @ 5eb8abc0
# AccessibilityExtensionContext
# 辅助功能扩展上下文
AccessibilityExtensionContext是AccessibilityExtensionAbility上下文环境，继承自ExtensionContext。
AccessibilityExtensionContext模块提供扩展的上下文的能力，包括允许配置辅助应用关注信息类型、查询节点信息、手势注入等。
辅助功能扩展上下文模块提供辅助功能扩展的上下文环境的能力，包括允许配置辅助应用关注信息类型、查询节点信息、手势注入等。
> **说明：**
>
......@@ -17,7 +17,7 @@ AccessibilityExtensionContext模块提供扩展的上下文的能力，包括允
import AccessibilityExtensionAbility from '@ohos.application.AccessibilityExtensionAbility'
class MainAbility extends AccessibilityExtensionAbility {
onConnect(): void {
console.log("AxExtensionAbility onConnect");
console.log('AxExtensionAbility onConnect');
let axContext = this.context;
}
}
......@@ -77,7 +77,7 @@ class MainAbility extends AccessibilityExtensionAbility {
setTargetBundleName(targetNames: Array\<string>): Promise\<void>;
设置关注的事件类型。
设置关注的目标包名，使用Promise异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
......@@ -91,19 +91,52 @@ setTargetBundleName(targetNames: Array\<string>): Promise\<void>;
| 类型 | 说明 |
| ---------------------- | --------------------- |
| Promise&lt;boolean&gt; | Promise对象。返回当前设置是否成功。 |
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例：**
```ts
this.context.setTargetBundleName(['com.ohos.mms']);
let targetNames = ['com.ohos.xyz'];
this.context.setTargetBundleName().then(() => {
console.info('set target bundle names success');
}).catch((err) => {
console.error('failed to set target bundle names because ' + JSON.stringify(err));
});
```
## AccessibilityExtensionContext.setTargetBundleName
setTargetBundleName(targetNames: Array\<string>, callback: AsyncCallback\<void>): void;
设置关注的目标包名，使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ------------------- | ---- | -------- |
| targetNames | Array&lt;string&gt; | 是 | 关注的目标包名。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数，如果设置关注的目标包名失败，则AsyncCallback中err有数据返回。 |
**示例：**
```ts
let targetNames = ['com.ohos.xyz'];
this.context.setTargetBundleName().then((err, data) => {
if (err) {
console.error('failed to set target bundle names because ' + JSON.stringify(err));
return;
}
console.info('set target bundle names success');
});
```
## AccessibilityExtensionContext.getFocusElement
getFocusElement(isAccessibilityFocus?: boolean): Promise\<AccessibilityElement>;
获取焦点元素。
获取焦点元素, 使用Promise异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
......@@ -117,77 +150,296 @@ getFocusElement(isAccessibilityFocus?: boolean): Promise\<AccessibilityElement>;
| 类型 | 说明 |
| ----------------------------------- | ---------------------- |
| Promise&lt;AccessibilityElement&gt; | Promise对象。返回当前对应的焦点元素。 |
| Promise&lt;AccessibilityElement&gt; | Promise对象，返回当前对应的焦点元素。 |
**示例：**
```ts
this.context.getFocusElement().then(focusElement => {
console.log("AxExtensionAbility getFocusElement success");
})
let focusElement;
this.context.getFocusElement().then((data) => {
focusElement = data;
console.log('get focus element success');
}).catch((err) => {
console.error('failed to get focus element because ' + JSON.stringify(err));
});
```
## AccessibilityExtensionContext.getFocusElement
getFocusElement(callback: AsyncCallback\<AccessibilityElement>): void;
获取焦点元素, 使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;AccessibilityElement&gt; | 是 | 回调函数，返回当前对应的焦点元素。 |
**示例：**
```ts
let focusElement;
this.context.getFocusElement().then((err, data) => {
if (err) {
console.error('failed to get focus element because ' + JSON.stringify(err));
return;
}
focusElement = data;
console.info('get focus element success');
});
```
## AccessibilityExtensionContext.getFocusElement
getFocusElement(isAccessibilityFocus: boolean, callback: AsyncCallback\<AccessibilityElement>): void;
获取焦点元素, 使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------------------- | ------- | ---- | ------------------- |
| isAccessibilityFocus | boolean | 是 | 获取的是否是无障碍焦点元素。 |
| callback | AsyncCallback&lt;AccessibilityElement&gt; | 是 | 回调函数，返回当前对应的焦点元素。 |
**示例：**
```ts
let isAccessibilityFocus = true;
this.context.getFocusElement(isAccessibilityFocus).then((err, data) => {
if (err) {
console.error('failed to get focus element because ' + JSON.stringify(err));
return;
}
focusElement = data;
console.info('get focus element success');
});
```
## AccessibilityExtensionContext.getWindowRootElement
getWindowRootElement(windowId?: number): Promise\<AccessibilityElement>;
获取窗口的根节点元素。
获取指定窗口的根节点元素, 使用Promise异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | ------ | ---- | --------------------------- |
| windowId | number | 否 | 指定获取根节点元素的窗口，未指定则从当前活跃窗口获取。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------------------- | ------- | ---- | ------------------- |
| windowId | number | 否 | 指定窗口的编号，未指定则从当前活跃窗口获取。 |
**返回值：**
| 类型 | 说明 |
| ----------------------------------- | ----------------------- |
| Promise&lt;AccessibilityElement&gt; | Promise对象。返回当前对应的根节点元素。 |
| 类型 | 说明 |
| ----------------------------------- | ---------------------- |
| Promise&lt;AccessibilityElement&gt; | Promise对象，返回指定屏幕的所有窗口。 |
**示例：**
```ts
let rootElement;
this.context.getWindowRootElement().then((data) => {
rootElement = data;
console.log('get root element of the window success');
}).catch((err) => {
console.error('failed to get root element of the window because ' + JSON.stringify(err));
});
```
## AccessibilityExtensionContext.getWindowRootElement
getWindowRootElement(callback: AsyncCallback\<AccessibilityElement>): void;
获取指定窗口的根节点元素, 使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;AccessibilityElement&gt; | 是 | 回调函数，返回指定窗口的根节点元素。 |
**示例：**
```ts
let rootElement;
this.context.getWindowRootElement().then((err, data) => {
if (err) {
console.error('failed to get root element of the window because ' + JSON.stringify(err));
return;
}
rootElement = data;
console.info('get root element of the window success');
});
```
## AccessibilityExtensionContext.getWindowRootElement
getWindowRootElement(windowId: number, callback: AsyncCallback\<AccessibilityElement>): void;
获取指定屏幕中的所有窗口, 使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------------------- | ------- | ---- | ------------------- |
| windowId | number | 是 | 指定窗口的编号，未指定则从当前活跃窗口获取。 |
| callback | AsyncCallback&lt;AccessibilityElement&gt; | 是 | 回调函数，返回指定窗口的根节点元素。 |
**示例：**
```ts
this.context.getWindowRootElement().then(rootElement => {
console.log("AxExtensionAbility getWindowRootElement success");
})
let displayId = 10;
let rootElement;
this.context.getWindowRootElement(displayId).then((err, data) => {
if (err) {
console.error('failed to get root element of the window because ' + JSON.stringify(err));
return;
}
rootElement = data;
console.info('get root element of the window success');
});
```
## AccessibilityExtensionContext.getWindows
getWindows(displayId?: number): Promise<Array\<AccessibilityElement>>;
getWindows(displayId?: number): Promise\<Array\<AccessibilityElement>>;
获取用户可见的窗口列表。
获取指定屏幕中的所有窗口, 使用Promise异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| --------- | ------ | ---- | ------------------------- |
| displayId | number | 否 | 指定获取窗口信息的屏幕，未指定则从默认主屏幕获取。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------------------- | ------- | ---- | ------------------- |
| displayId | number | 否 | 指定的屏幕编号，未指定则从默认主屏幕获取。 |
**返回值：**
| 类型 | 说明 |
| ---------------------------------------- | ------------------------ |
| Promise&lt;Array&lt;AccessibilityElement&gt;&gt; | Promise对象。返回当前对应的窗口列表信息。 |
| 类型 | 说明 |
| ----------------------------------- | ---------------------- |
| Promise&lt;Array&lt;AccessibilityElement&gt;&gt; | Promise对象，返回指定屏幕的所有窗口。 |
**示例：**
```ts
this.context.getWindows().then(windows => {
console.log("AxExtensionAbility getWindows success");
})
let windows;
this.context.getWindows().then((data) => {
windows = data;
console.log('get windows success');
}).catch((err) => {
console.error('failed to get windows because ' + JSON.stringify(err));
});
```
## AccessibilityExtensionContext.getWindows
getWindows(callback: AsyncCallback\<Array\<AccessibilityElement>>): void;
获取指定屏幕中的所有窗口, 使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;Array&lt;AccessibilityElement&gt;&gt; | 是 | 回调函数，返回指定屏幕的所有窗口。 |
**示例：**
```ts
let windows;
this.context.getWindows().then((err, data) => {
if (err) {
console.error('failed to get windows because ' + JSON.stringify(err));
return;
}
windows = data;
console.info('get windows success');
});
```
## AccessibilityExtensionContext.getWindows
getWindows(displayId: number, callback: AsyncCallback\<Array\<AccessibilityElement>>): void;
获取指定屏幕中的所有窗口, 使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------------------- | ------- | ---- | ------------------- |
| displayId | number | 是 | 指定的屏幕编号，未指定则从默认主屏幕获取。 |
| callback | AsyncCallback&lt;Array&lt;AccessibilityElement&gt;&gt; | 是 | 回调函数，返回指定屏幕的所有窗口。 |
**示例：**
```ts
let displayId = 10;
let windows;
this.context.getWindows(displayId).then((err, data) => {
if (err) {
console.error('failed to get windows because ' + JSON.stringify(err));
return;
}
windows = data;
console.info('get windows success');
});
```
## AccessibilityExtensionContext.injectGesture
injectGesture(gesturePath: GesturePath): Promise\<void>;
注入手势，使用Promise异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| gesturePath | [GesturePath](js-apis-accessibility-GesturePath.md#gesturepath) | 是 | 表示手势的路径信息。 |
**返回值：**
| 类型 | 说明 |
| ----------------------------------- | ---------------------- |
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例：**
```ts
import { GesturePath } from "../@ohos.accessibility.GesturePath";
let gesturePath = new GesturePath(100);
for (let i = 0; i < 10; i++) {
let gesturePoint = new GesturePosition(100, i * 200);
gesturePath.positions.push(gesturePoint);
}
this.context.gestureInject(gesturePath, () => {
console.info('inject gesture success');
}).catch((err) => {
console.error('failed to inject gesture because ' + JSON.stringify(err));
});
```
## AccessibilityExtensionContext.injectGesture
injectGesture(gesturePath: GesturePath, callback: AsyncCallback\<void>): void
注入手势。
注入手势，使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
......@@ -195,8 +447,8 @@ injectGesture(gesturePath: GesturePath, callback: AsyncCallback\<void>): void
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| gesturePath | [GesturePath](js-apis-application-AccessibilityExtensionAbility.md#GesturePath) | 是 | 表示手势的路径信息。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 表示注入手势执行结果的回调。 |
| gesturePath | [GesturePath](js-apis-accessibility-GesturePath.md#gesturepath) | 是 | 表示手势的路径信息。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数，表示注入手势执行结果的回调。 |
**示例：**
......@@ -206,15 +458,25 @@ for (let i = 0; i < 10; i++) {
let gesturePoint = new GesturePosition(100, i * 200);
gesturePath.positions.push(gesturePoint);
}
this.context.gestureInject(gesturePath, (result) => {
console.info('gestureInject result: ' + result);
})
this.context.gestureInject(gesturePath, (err, data) => {
if (err) {
console.error('failed to inject gesture because ' + JSON.stringify(err));
return;
}
console.info('inject gesture success');
});
```
## AccessibilityElement.attributeNames
## AccessibilityElement<sup>9</sup>
无障碍节点元素。
**系统能力**：以下各项对应的系统能力均为SystemCapability.BarrierFree.Accessibility.Core
## attributeNames
attributeNames\<T extends keyof ElementAttributeValues>(): Promise\<Array\<T>>;
获取节点元素的所有属性名称。
获取节点元素的所有属性名称，使用Promise异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
......@@ -222,28 +484,61 @@ attributeNames\<T extends keyof ElementAttributeValues>(): Promise\<Array\<T>>;
| 类型 | 说明 |
| ---------------------------------------- | ------------------------ |
| Promise&lt;Array&lt;T&gt;&gt; | Promise对象。返回获取元素所有属性名称的调用结果。 |
| Promise&lt;Array&lt;T&gt;&gt; | Promise对象，返回节点元素的所有属性名称。 |
**示例：**
```ts
let accessibilityElement;
let attributeNames;
try {
accessibilityElement.attributeNames().then((values) => {
console.log("get attribute names success");
accessibilityElement.attributeNames().then((data) => {
console.log('get attribute names success');
attributeNames = data;
}).catch((err) => {
console.log("get attribute names err: " + JSON.stringify(err));
console.log('get attribute names err: ' + JSON.stringify(err));
});
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
console.log('An unexpected error occurred. Error:' + e);
}
```
## attributeNames
attributeNames\<T extends keyof ElementAttributeValues>(callback: AsyncCallback\<Array\<T>>): void;
获取节点元素的所有属性名称，使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| callback | AsyncCallback&lt;Array&lt;T&gt;&gt; | 是 | 回调函数，返回节点元素的所有属性名称。 |
**示例：**
```ts
let accessibilityElement;
let attributeNames;
try {
accessibilityElement.attributeNames().then((err, data) => {
if (err) {
console.error('failed to get attribute names because ' + JSON.stringify(err));
return;
}
attributeNames = data;
console.info('get attribute names success');
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## AccessibilityElement.attributeValue
attributeValue\<T extends keyof ElementAttributeValues>(attributeName: T): Promise\<ElementAttributeValues[T]>;
根据属性名称获取属性值。
根据属性名称获取属性值，使用Promise异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
......@@ -257,29 +552,65 @@ attributeValue\<T extends keyof ElementAttributeValues>(attributeName: T): Promi
| 类型 | 说明 |
| ---------------------------------------- | ------------------------ |
| Promise&lt;Array&lt;ElementAttributeValues[T]&gt;&gt; | Promise对象。返回根据属性名称获取属性值的调用结果。 |
| Promise&lt;ElementAttributeValues[T]&gt; | Promise对象，返回根据节点属性名称获取的属性值。 |
**示例：**
```ts
let accessibilityElement;
let attributeValue;
try {
let attributeName = 'name';
accessibilityElement.attributeValue(attributeName).then((value) => {
console.log("get attribute value by name success");
accessibilityElement.attributeValue(attributeName).then((data) => {
console.log('get attribute value by name success');
attribtueValue = data;
}).catch((err) => {
console.log("get attribute value by name err: " + JSON.stringify(err));
console.log('get attribute value by name err: ' + JSON.stringify(err));
});
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
console.log('An unexpected error occurred. Error:' + e);
}
```
## AccessibilityElement.attributeValue
attributeValue\<T extends keyof ElementAttributeValues>(attributeName: T,
callback: AsyncCallback\<ElementAttributeValues[T]>): void;
根据属性名称获取属性值，使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| attributeName | T | 是 | 表示属性的名称。 |
| callback | AsyncCallback&lt;ElementAttributeValues[T]&gt; | 是 | 回调函数，返回根据节点属性名称获取的属性值。 |
**示例：**
## AccessibilityElement.actionNames
```ts
let accessibilityElement;
let attributeValue;
try {
let attributeName = 'name';
accessibilityElement.attributeValue(attributeName).then((err, data) => {
if (err) {
console.error('failed to get attribute value because ' + JSON.stringify(err));
return;
}
attributeValue = data;
console.info('get attribute value success');
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## actionNames
actionNames(): Promise\<Array\<string>>;
获取节点元素支持的所有操作名称。
获取节点元素支持的所有操作名称，使用Promise异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
......@@ -287,28 +618,61 @@ actionNames(): Promise\<Array\<string>>;
| 类型 | 说明 |
| ---------------------------------------- | ------------------------ |
| Promise&lt;Array&lt;string&gt;&gt; | Promise对象。返回获取节点元素支持的所有操作名称的调用结果。 |
| Promise&lt;Array&lt;string&gt;&gt; | Promise对象，返回节点元素支持的所有操作名称。 |
**示例：**
```ts
let accessibilityElement;
let actionNames;
try {
accessibilityElement.actionNames().then((values) => {
console.log("get action names success");
accessibilityElement.actionNames().then((data) => {
console.log('get action names success');
actionNames = data;
}).catch((err) => {
console.log("get action names err: " + JSON.stringify(err));
console.log('get action names err: ' + JSON.stringify(err));
});
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
console.log('An unexpected error occurred. Error:' + e);
}
```
## actionNames
## AccessibilityElement.performAction
actionNames(callback: AsyncCallback\<Array\<string>>): void;
获取节点元素支持的所有操作名称，使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| callback | AsyncCallback&lt;Array&lt;string&gt;&gt; | 是 | 回调函数，返回节点元素支持的所有操作名称。 |
**示例：**
```ts
let accessibilityElement;
let actionNames;
try {
accessibilityElement.actionNames().then((err, data) => {
if (err) {
console.error('failed to get action names because ' + JSON.stringify(err));
return;
}
actionNames = data;
console.info('get action names success');
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## performAction
performAction(actionName: string, parameters?: object): Promise\<boolean>;
根据操作名称执行某个操作。
根据操作名称执行某个操作，使用Promise异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
......@@ -323,29 +687,139 @@ performAction(actionName: string, parameters?: object): Promise\<boolean>;
| 类型 | 说明 |
| ---------------------------------------- | ------------------------ |
| Promise&lt;Array&lt;boolean&gt;&gt; | Promise对象。返回获取元素所有属性名的调用结果。 |
| Promise&lt;boolean&gt; | Promise对象，返回执行指定操作后的回调结果，true为执行成功，false为执行失败。 |
**示例：**
```ts
let accessibilityElement;
let performActionRes;
try {
accessibilityElement.performAction('action').then((result) => {
console.info('perform action result: ' + result);
accessibilityElement.performAction('action').then((data) => {
console.info('perform action success');
performActionRes = data;
}).catch((err) => {
console.log("perform action err: " + JSON.stringify(err));
console.log('failed to perform action because ' + JSON.stringify(err));
});
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
console.log('An unexpected error occurred. Error:' + e);
}
```
## performAction
performAction(actionName: string, callback: AsyncCallback\<boolean>): void;
根据操作名称执行某个操作，使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
## AccessibilityElement.findElement
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| actionName | string | 是 | 表示属性的名称。 |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数，返回执行指定操作后的回调结果，true为执行成功，false为执行失败。 |
**示例：**
```ts
let accessibilityElement;
let performActionRes;
try {
accessibilityElement.performAction('action').then((err, data) => {
if (err) {
console.error('failed to perform action because ' + JSON.stringify(err));
return;
}
performActionRes = data;
console.info('perform action success');
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## performAction
performAction(actionName: string, parameters: object, callback: AsyncCallback\<boolean>): void;
根据操作名称执行某个操作，使用callback异步回调。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| actionName | string | 是 | 表示属性的名称。 |
| parameters | object | 是 | 表示执行操作时所需要的参数。 |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数，返回执行指定操作后的回调结果，true为执行成功，false为执行失败。 |
**示例：**
```ts
let accessibilityElement;
let actionName = 'action';
let parameters = {
'setText': 'test text'
};
let performActionRes;
try {
accessibilityElement.performAction(actionName, parameters).then((err, data) => {
if (err) {
console.error('failed to perform action because ' + JSON.stringify(err));
return;
}
performActionRes = data;
console.info('perform action success');
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## findElement('content')
findElement(type: 'content', condition: string): Promise\<Array\<AccessibilityElement>>;
查询节点元素的指定内容。
根据节点内容查询所有节点元素。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| type | string | 是 | 固定为'content', 表示查找的类型为节点元素内容。 |
| condition | string | 是 | 表示查找的条件。 |
**返回值：**
| 类型 | 说明 |
| ---------------------------------------- | ------------------------ |
| Promise&lt;Array&lt;AccessibilityElement&gt;&gt; | Promise对象，返回满足指定查询关键字的所有节点元素。 |
**示例：**
```ts
let accessibilityElement;
let type = 'content';
let condition = 'keyword';
let elements;
try {
accessibilityElement.findElement(type, condition).then((data) => {
elements = data;
console.log('find element success');
}).catch((err) => {
console.log('failed to find element because ' + JSON.stringify(err));
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## findElement('content')
findElement(type: 'content', condition: string, callback: AsyncCallback\<Array\<AccessibilityElement>>): void;
根据节点内容查询所有节点元素。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
......@@ -355,25 +829,175 @@ findElement(type: 'content', condition: string): Promise\<Array\<AccessibilityEl
| ----------- | ---------------------------------------- | ---- | -------------- |
| type | string | 是 | 固定为'content',表示查找的类型为节点元素内容。 |
| condition | string | 是 | 表示查找的条件。 |
| callback | AsyncCallback&lt;Array&lt;AccessibilityElement&gt;&gt; | 是 | 回调函数，返回满足指定查询关键字的所有节点元素。 |
**示例：**
```ts
let accessibilityElement;
let type = 'content';
let condition = 'keyword';
let elements;
try {
accessibilityElement.findElement(type, condition).then((err, data) => {
if (err) {
console.error('failed to find element because ' + JSON.stringify(err));
return;
}
elements = data;
console.info('find element success');
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## findElement('focusType')
findElement(type: 'focusType', condition: FocusType): Promise\<AccessibilityElement>;
根据焦点元素类型查询节点元素。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| type | string | 是 | 固定为'focusType', 表示查询的类型为节点的焦点元素类型。 |
| condition | [FocusType](#focustype) | 是 | 表示查询焦点元素的类型。 |
**返回值：**
| 类型 | 说明 |
| ---------------------------------------- | ------------------------ |
| Promise&lt;Array&lt;T&gt;&gt; | Promise对象。返回获取元素所有属性名的调用结果。 |
| Promise&lt;AccessibilityElement&gt; | Promise对象，返回满足指定查询焦点元素类型的节点元素。 |
**示例：**
```ts
let accessibilityElement;
let type = 'focusType';
let condition = 'normal';
let elements;
try {
let condition = 'keyword';
accessibilityElement.findElement('content', condition).then((values) => {
console.log("find element success");
accessibilityElement.findElement(type, condition).then((data) => {
elements = data;
console.log('find element success');
}).catch((err) => {
console.log("find element err: " + JSON.stringify(err));
console.log('failed to find element because ' + JSON.stringify(err));
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## findElement('focusType')
findElement(type: 'focusType', condition: FocusType, callback: AsyncCallback\<AccessibilityElement>): void;
根据焦点元素类型查询节点元素。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| type | string | 是 | 固定为'focusType', 表示查询的类型为节点的焦点元素类型。 |
| condition | [FocusType](#focustype) | 是 | 表示查询焦点元素的类型。 |
| callback | AsyncCallback&lt;AccessibilityElement&gt; | 是 | 回调函数，返回满足指定查询焦点元素类型的节点元素。 |
**示例：**
```ts
let accessibilityElement;
let type = 'focusType';
let condition = 'normal';
let elements;
try {
accessibilityElement.findElement(type, condition).then((err, data) => {
if (err) {
console.error('failed to find element because ' + JSON.stringify(err));
return;
}
elements = data;
console.info('find element success');
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## findElement('focusDirection')
findElement(type: 'focusDirection', condition: FocusDirection): Promise\<AccessibilityElement>;
根据下一焦点元素方向查询节点元素。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| type | string | 是 | 固定为'focusDirection', 表示查询的类型为节点的下一焦点元素方向。 |
| condition | [FocusDirection](#focusdirection) | 是 | 表示查询下一焦点元素的方向。 |
**返回值：**
| 类型 | 说明 |
| ---------------------------------------- | ------------------------ |
| Promise&lt;AccessibilityElement&gt; | Promise对象，返回满足指定查询下一焦点元素方向的节点元素。 |
**示例：**
```ts
let accessibilityElement;
let type = 'focusDirection';
let condition = 'up';
let elements;
try {
accessibilityElement.findElement(type, condition).then((data) => {
elements = data;
console.log('find element success');
}).catch((err) => {
console.log('failed to find element because ' + JSON.stringify(err));
});
} catch (e) {
console.log('An unexpected error occurred. Error:' + e);
}
```
## findElement('focusDirection')
findElement(type: 'focusDirection', condition: FocusDirection, callback: AsyncCallback\<AccessibilityElement>): void;
根据下一焦点元素方向查询所有节点元素。
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ----------- | ---------------------------------------- | ---- | -------------- |
| type | string | 是 | 固定为'focusDirection', 表示查询的类型为节点的下一焦点元素方向。 |
| condition | [FocusDirection](#focusdirection) | 是 | 表示下一查询焦点元素的方向。 |
| callback | AsyncCallback&lt;AccessibilityElement&gt; | 是 | 回调函数，返回满足指定查询下一焦点元素方向的节点元素。 |
**示例：**
```ts
let accessibilityElement;
let type = 'focusDirection';
let condition = 'up';
let elements;
try {
accessibilityElement.findElement(type, condition).then((err, data) => {
if (err) {
console.error('failed to find element because ' + JSON.stringify(err));
return;
}
elements = data;
console.info('find element success');
});
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
console.log('An unexpected error occurred. Error:' + e);
}
```
zh-cn/application-dev/reference/apis/js-apis-accessibility.md
浏览文件 @ 5eb8abc0
......@@ -144,7 +144,7 @@ import accessibility from '@ohos.accessibility';
## CaptionsManager<sup>8+</sup>
字幕配置。
字幕配置管理，在调用CaptionsManager的方法前，需要先通过 [accessibility.getCaptionsManager()](#accessibilitygetcaptionsmanager8)获取 captionsManager实例。
**系统能力**：以下各项对应的系统能力均为SystemCapability.BarrierFree.Accessibility.Hearing
......@@ -155,90 +155,92 @@ import accessibility from '@ohos.accessibility';
| enabled | boolean | 是 | 否 | 表示是否启用字幕配置。 |
| style | [CaptionsStyle](#captionsstyle8) | 是 | 否 | 表示字幕风格。 |
下列 API 示例中都需要使用 [accessibility.getCaptionsManager()](#accessibilitygetcaptionsmanager8) 获取 captionsManager 实例，再通过此实例调用对应的方法。
### on('enableChange')
on(type: 'enableChange', callback: Callback&lt;boolean&gt;): void;
注册字幕配置启用的监听函数。
监听字幕配置启用状态变化事件。
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 监听字幕配置启用状态。 |
| callback | Callback&lt;boolean&gt; | 是 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 监听的事件名，固定为‘enableChange’，即字幕配置启用状态变化事件。 |
| callback | Callback&lt;boolean&gt; | 是 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 |
- **示例：**
**示例：**
```typescript
let captionsManager = accessibility.getCaptionsManager();
let captionsManager = accessibility.getCaptionsManager();
captionsManager.on('enableChange',(data) => {
console.info('success data:subscribeStateObserver : ' + JSON.stringify(data))
})
});
```
### on('styleChange')
on(type: 'styleChange', callback: Callback&lt;CaptionsStyle&gt;): void;
注册字幕风格变化的监听函数。
监听字幕风格变化事件。
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 监听字幕风格变化。 |
| callback | Callback&lt;[CaptionsStyle](#captionsstyle8)&gt; | 是 | 回调函数，在字幕风格变化时通过此函数进行通知。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 监听的事件名，固定为‘styleChange’，即字幕风格变化事件。 |
| callback | Callback&lt;[CaptionsStyle](#captionsstyle8)&gt; | 是 | 回调函数，在字幕风格变化时通过此函数进行通知。 |
- **示例：**
**示例：**
```typescript
let captionsManager = accessibility.getCaptionsManager();
let captionsManager = accessibility.getCaptionsManager();
captionsManager.on('styleChange',(data) => {
console.info('success data:subscribeStateObserver : ' + JSON.stringify(data))
})
});
```
### off('enableChange')
off(type: 'enableChange', callback?: Callback&lt;boolean&gt;): void;
移除字幕配置启用的监听函数。
取消监听字幕配置启用状态变化事件。
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 监听字幕配置启用状态。 |
| callback | Callback&lt;boolean&gt; | 否 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 取消监听的事件名，固定为‘enableChange’，即字幕配置启用状态变化事件。 |
| callback | Callback&lt;boolean&gt; | 否 | 回调函数，在字幕配置启用状态变化时将状态通过此函数进行通知。 |
- **示例：**
**示例：**
```typescript
let captionsManager = accessibility.getCaptionsManager();
captionsManager.off('enableChange')
let captionsManager = accessibility.getCaptionsManager();
captionsManager.off('enableChange',(data) => {
console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data))
});
```
### off('styleChange')
off(type: 'styleChange', callback?: Callback&lt;CaptionsStyle&gt;): void;
移除字幕风格变化的监听函数。
取消字幕风格变化监听事件。
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 字幕风格变化。 |
| callback | Callback&lt;[CaptionsStyle](#captionsstyle8)&gt; | 否 | 回调函数，在字幕风格变化时通过此函数进行通知。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 取消监听的事件名，固定为‘styleChange’，即字幕风格变化事件。 |
| callback | Callback&lt;[CaptionsStyle](#captionsstyle8)&gt; | 否 | 回调函数，在字幕风格变化时通过此函数进行通知。 |
- **示例：**
**示例：**
```typescript
let captionsManager = accessibility.getCaptionsManager();
captionsManager.off('styleChange')
let captionsManager = accessibility.getCaptionsManager();
captionsManager.off('styleChange',(data) => {
console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data))
});
```
## EventInfo
......@@ -274,16 +276,20 @@ constructor(jsonObject)
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| jsonObject | string | 是 | 创建对象所需要的 JSON 格式字符串。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| jsonObject | string | 是 | 创建对象所需要的 JSON 格式字符串。 |
- **示例：**
**示例：**
```typescript
let eventInfo = new accessibility.EventInfo({"type":"click","bundleName":"com.example.MyApplication","triggerAction":"click"})
let eventInfo = new accessibility.EventInfo({
"type":"click",
"bundleName":"com.example.MyApplication",
"triggerAction":"click"
});
```
## EventType
......@@ -338,306 +344,348 @@ constructor(jsonObject)
getAbilityLists(abilityType: AbilityType, stateType: AbilityState): Promise&lt;Array&lt;AccessibilityAbilityInfo&gt;&gt;
查询辅助应用列表。
查询辅助应用列表，使用Promise异步回调。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 |
| stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 |
| stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 |
- **返回值：**
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;Array&lt;[AccessibilityAbilityInfo](#accessibilityabilityinfo)&gt;&gt; | 返回辅助应用信息列表。 |
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;Array&lt;[AccessibilityAbilityInfo](#accessibilityabilityinfo)&gt;&gt; | Promise对象，返回辅助应用信息列表。 |
- **示例：**
**示例：**
```typescript
accessibility.getAbilityLists("spoken", "enable")
.then((data) => {
console.info('success data:getAbilityList1 : ' + JSON.stringify(data));
for (let item of data) {
console.info(item.id);
console.info(item.name);
console.info(item.description);
console.info(item.bundleName);
}
}).catch((error) => {
console.error('failed to getAbilityList1 because ' + JSON.stringify(error));
})
```
```typescript
accessibility.getAbilityLists("spoken", "enable").then((data) => {
console.info('success data:getAbilityList1 : ' + JSON.stringify(data));
for (let item of data) {
console.info(item.id);
console.info(item.name);
console.info(item.description);
console.info(item.bundleName);
}
}).catch((err) => {
console.error('failed to getAbilityList1 because ' + JSON.stringify(err));
});
```
## accessibility.getAbilityLists
getAbilityLists(abilityType: AbilityType, stateType: AbilityState,callback: AsyncCallback&lt;Array&lt;AccessibilityAbilityInfo&gt;&gt;): void
查询辅助应用列表。
查询辅助应用列表，使用callback异步回调。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 |
| stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 |
| callback | AsyncCallback&lt;Array&lt;[AccessibilityAbilityInfo](#accessibilityabilityinfo)&gt;&gt; | 是 | 回调函数，返回辅助应用信息列表。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 |
| stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 |
| callback | AsyncCallback&lt;Array&lt;[AccessibilityAbilityInfo](#accessibilityabilityinfo)&gt;&gt; | 是 | 回调函数，返回辅助应用信息列表。 |
- **示例：**
**示例：**
```typescript
accessibility.getAbilityLists("visual", "enable", (err, data) => {
if (err) {
console.error('failed to getAbilityList2 because ' + JSON.stringify(err));
return;
}
console.info('success data:getAbilityList2 : ' + JSON.stringify(data));
for (let item of data) {
console.info(item.id);
console.info(item.name);
console.info(item.description);
console.info(item.bundleName);
}
})
```typescript
accessibility.getAbilityLists("visual", "enable", (err, data) => {
if (err) {
console.error('failed to getAbilityList2 because ' + JSON.stringify(err));
return;
}
console.info('success data:getAbilityList2 : ' + JSON.stringify(data));
for (let item of data) {
console.info(item.id);
console.info(item.name);
console.info(item.description);
console.info(item.bundleName);
}
});
```
## accessibility.getCaptionsManager<sup>8+</sup>
getCaptionsManager(): CaptionsManager
获取无障碍字幕配置。
获取无障碍字幕配置管理实例。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Hearing
- **返回值：**
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| [CaptionsManager](#captionsmanager8) | 无障碍字幕配置管理。 |
| 类型 | 说明 |
| -------- | -------- |
| [CaptionsManager](#captionsmanager8) | 无障碍字幕配置管理。 |
- **示例：**
**示例：**
```typescript
let captionsManager = accessibility.getCaptionsManager()
```
```typescript
let captionsManager = accessibility.getCaptionsManager();
```
## accessibility.on('accessibilityStateChange' | 'touchGuideStateChange')
## accessibility.on('accessibilityStateChange')
on(type: 'accessibilityStateChange' | 'touchGuideStateChange', callback: Callback&lt;boolean&gt;): void
on(type: 'accessibilityStateChange', callback: Callback&lt;boolean&gt;): void
启用辅助应用和触摸浏览功能的状态变化监听。
监听辅助应用启用状态变化事件。
**系统能力**：以下各项对应的系统能力有所不同，详见下表。
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 监听的事件类型。<br/>-&nbsp;type 为'accessibilityStateChange'时表示监听类型为辅助功能启用状态变化监听；<br/>**系统能力**：SystemCapability.BarrierFree.Accessibility.Core<br/>-&nbsp;type 为'touchGuideStateChange'时表示监听类型为触摸浏览启用状态变化监听。<br/>**系统能力**：SystemCapability.BarrierFree.Accessibility.Vision |
| callback | Callback&lt;boolean&gt; | 是 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 监听的事件名，固定为‘accessibilityStateChange’，即辅助应用启用状态变化事件。 |
| callback | Callback&lt;boolean&gt; | 是 | 回调函数，在辅助应用启用状态变化时将状态通过此函数进行通知。 |
- **示例：**
**示例：**
```typescript
accessibility.on('accessibilityStateChange',(data) => {
console.info('success data:subscribeStateObserver : ' + JSON.stringify(data))
})
```
```typescript
accessibility.on('accessibilityStateChange',(data) => {
console.info('success data:subscribeStateObserver : ' + JSON.stringify(data))
});
```
## accessibility.off('accessibilityStateChange' | 'touchGuideStateChange')
## accessibility.on('touchGuideStateChange')
off(type: ‘accessibilityStateChange ’ | ‘touchGuideStateChange’, callback?: Callback&lt;boolean&gt;): void
on(type: 'touchGuideStateChange', callback: Callback&lt;boolean&gt;): void
关闭辅助应用和触摸浏览功能的状态变化监听。
监听触摸浏览功能启用状态变化事件。
**系统能力**：以下各项对应的系统能力有所不同，详见下表。
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 否 | 监听的事件类型。<br/>-&nbsp;type 为'accessibilityStateChange'时表示监听类型为辅助功能启用状态变化监听；<br/>**系统能力**：SystemCapability.BarrierFree.Accessibility.Core<br/>-&nbsp;type 为'touchGuideStateChange'时表示监听类型为触摸浏览启用状态变化监听。<br/>**系统能力**：SystemCapability.BarrierFree.Accessibility.Vision |
| callback | Callback&lt;boolean&gt; | 否 | 要取消的监听回调函数。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 监听的事件名，固定为‘touchGuideStateChange’，即触摸浏览启用状态变化事件。 |
| callback | Callback&lt;boolean&gt; | 是 | 回调函数，在触摸浏览启用状态变化时将状态通过此函数进行通知。 |
- **示例：**
**示例：**
```typescript
accessibility.off('accessibilityStateChange',(data) => {
console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data))
})
```
```typescript
accessibility.on('touchGuideStateChange',(data) => {
console.info('success data:subscribeStateObserver : ' + JSON.stringify(data))
});
```
## accessibility.off('accessibilityStateChange')
off(type: 'accessibilityStateChange', callback?: Callback&lt;boolean&gt;): void
取消监听辅助应用启用状态变化事件。
**系统能力**：以下各项对应的系统能力有所不同，详见下表。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 否 | 取消监听的事件名，固定为‘accessibilityStateChange’，即辅助应用启用状态变化事件。 |
| callback | Callback&lt;boolean&gt; | 否 | 回调函数，在辅助应用启用状态变化时将状态通过此函数进行通知。 |
**示例：**
```typescript
accessibility.off('accessibilityStateChange',(data) => {
console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data))
});
```
## accessibility.off('touchGuideStateChange')
off(type: 'touchGuideStateChange', callback?: Callback&lt;boolean&gt;): void
取消监听触摸浏览启用状态变化事件。
**系统能力**：以下各项对应的系统能力有所不同，详见下表。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 否 | 取消监听的事件名，固定为‘touchGuideStateChange’，即触摸浏览启用状态变化事件。 |
| callback | Callback&lt;boolean&gt; | 否 | 回调函数，在触摸浏览启用状态变化时将状态通过此函数进行通知。 |
**示例：**
```typescript
accessibility.off('touchGuideStateChange',(data) => {
console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data))
});
```
## accessibility.isOpenAccessibility
isOpenAccessibility(): Promise&lt;boolean&gt;
判断是否启用了辅助功能。
判断是否启用了辅助功能, 使用Promise异步回调。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
- **返回值：**
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;boolean&gt; | 如果辅助功能已启用，则返回 true；否则返回 false。 |
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise对象，如果辅助功能已启用，则返回 true；否则返回 false。 |
- **示例：**
**示例：**
```typescript
accessibility.isOpenAccessibility()
.then((data) => {
console.info('success data:isOpenAccessibility : ' + JSON.stringify(data))
}).catch((error) => {
console.error('failed to isOpenAccessibility because ' + JSON.stringify(error));
})
```
```typescript
accessibility.isOpenAccessibility().then((data) => {
console.info('success data:isOpenAccessibility : ' + JSON.stringify(data))
}).catch((err) => {
console.error('failed to isOpenAccessibility because ' + JSON.stringify(err));
});
```
## accessibility.isOpenAccessibility
isOpenAccessibility(callback: AsyncCallback&lt;boolean&gt;): void
判断是否启用了辅助功能。
判断是否启用了辅助功能，使用callback异步回调。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数，如果辅助功能已启用，则返回 true；否则返回 false。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数，如果辅助功能已启用，则返回 true；否则返回 false。 |
- **示例：**
**示例：**
```typescript
accessibility.isOpenAccessibility((err, data) => {
if (err) {
console.error('failed to isOpenAccessibility because ' + JSON.stringify(err));
return;
}
console.info('success data:isOpenAccessibility : ' + JSON.stringify(data))
})
```
```typescript
accessibility.isOpenAccessibility((err, data) => {
if (err) {
console.error('failed to isOpenAccessibility because ' + JSON.stringify(err));
return;
}
console.info('success data:isOpenAccessibility : ' + JSON.stringify(data))
});
```
## accessibility.isOpenTouchGuide
isOpenTouchGuide(): Promise&lt;boolean&gt;
判断触摸浏览模式是否开启。
判断触摸浏览模式是否开启, 使用Promise异步回调。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Vision
- **返回值：**
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;boolean&gt; | 如果触摸浏览模式已开启，则返回 true；否则返回 false。 |
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise对象，如果触摸浏览模式已开启，则返回 true；否则返回 false。 |
- **示例：**
**示例：**
```typescript
accessibility.isOpenTouchGuide()
.then((data) => {
console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data))
}).catch((error) => {
console.error('failed to isOpenTouchGuide because ' + JSON.stringify(error));
})
```
```typescript
accessibility.isOpenTouchGuide().then((data) => {
console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data))
}).catch((err) => {
console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err));
});
```
## accessibility.isOpenTouchGuide
isOpenTouchGuide(callback: AsyncCallback&lt;boolean&gt;): void
判断触摸浏览模式是否开启。
判断触摸浏览模式是否开启, 使用callback异步回调。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Vision
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数，如果触摸浏览模式已开启，则返回 true；否则返回 false。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数，如果触摸浏览模式已开启，则返回 true；否则返回 false。 |
- **示例：**
**示例：**
```typescript
accessibility.isOpenTouchGuide((err, data) => {
if (err) {
console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err));
return;
}
console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data))
})
```typescript
accessibility.isOpenTouchGuide((err, data) => {
if (err) {
console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err));
return;
}
console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data))
});
```
## accessibility.sendEvent
sendEvent(event: EventInfo): Promise&lt;void&gt;
发送无障碍事件。
发送无障碍事件, 使用Promise异步回调。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| event | [EventInfo](#eventinfo) | 是 | 无障碍事件对象。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| event | [EventInfo](#eventinfo) | 是 | 无障碍事件对象。 |
- **返回值：**
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | 以 Promise 形式返回结果，如果发送无障碍事件成功，则 data 有数据返回；如果发送无障碍事件失败，则 err 有数据返回。 |
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
- **示例：**
**示例：**
```typescript
let eventInfo : accessibility.EventInfo = {
type: 'focus',
bundleName: 'bundle',
triggerAction: 'focus'
}
accessibility.sendEvent(eventInfo)
.then((data) => {
console.info('success data:sendEvent : ' + JSON.stringify(data))
}).catch((error) => {
console.error('failed to sendEvent because ' + JSON.stringify(error));
})
```
```typescript
let eventInfo = new accessibility.EventInfo({
"type":"click",
"bundleName":"com.example.MyApplication",
"triggerAction":"click"
});
accessibility.sendEvent(eventInfo).then(() => {
console.info('send event success');
}).catch((err) => {
console.error('failed to sendEvent because ' + JSON.stringify(err));
});
```
## accessibility.sendEvent
sendEvent(event: EventInfo, callback: AsyncCallback&lt;void&gt;): void
发送无障碍事件。
发送无障碍事件, 使用callback异步回调。
**系统能力**：SystemCapability.BarrierFree.Accessibility.Core
- **参数：**
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| event | [EventInfo](#eventinfo) | 是 | 辅助事件对象。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数，如果发送无障碍事件成功，则 AsyncCallback 中 data 有数据返回；如果发送无障碍事件失败，则 AsyncCallback 中 err 有数据返回。 |
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| event | [EventInfo](#eventinfo) | 是 | 辅助事件对象。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数，如果发送无障碍事件失败，则 AsyncCallback中err有数据返回。 |
- **示例：**
**示例：**
```typescript
let eventInfo : accessibility.EventInfo = {
type: 'focus',
bundleName: 'bundle',
triggerAction: 'focus'
}
accessibility.sendEvent(eventInfo,(err, data) => {
if (err) {
console.error('failed to sendEvent because ' + JSON.stringify(err));
return;
}
console.info('success data:sendEvent : ' + JSON.stringify(data))
})
```typescript
let eventInfo = new accessibility.EventInfo({
"type":"click",
"bundleName":"com.example.MyApplication",
"triggerAction":"click"
});
accessibility.sendEvent(eventInfo, (err, data) => {
if (err) {
console.error('failed to sendEvent because ' + JSON.stringify(err));
return;
}
console.info('sendEvent success');
});
```
zh-cn/application-dev/reference/apis/js-apis-appAccount.md
浏览文件 @ 5eb8abc0
因为 它太大了无法显示 source diff 。你可以改为 查看blob。
zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md
浏览文件 @ 5eb8abc0
......@@ -2,7 +2,7 @@
**AccessibilityExtensionAbility**基于ExtensionAbility框架，提供辅助功能业务的能力。
>**说明：**
>![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
>
>本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。
>
......@@ -32,36 +32,10 @@ import AccessibilityExtensionAbility from '@ohos.application.AccessibilityExtens
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| --------- | ---------------------------------------- | ---- | ---- | ---------- |
| eventType | [EventType](js-apis-accessibility.md#EventType) \| [WindowUpdateType](js-apis-accessibility.md#WindowUpdateType) \| [TouchGuideType](touchguidetype) \| [GestureType](gesturetype) \| [PageUpdateType](pageupdatetype) | 是 | 否 | 具体事件类型。 |
| eventType | [EventType](js-apis-accessibility.md#EventType) \| [WindowUpdateType](js-apis-accessibility.md#WindowUpdateType) \| [TouchGuideType](#touchguidetype) \| [GestureType](#gesturetype) \| [PageUpdateType](#pageupdatetype) | 是 | 否 | 具体事件类型。 |
| target | AccessibilityElement | 是 | 否 | 发生事件的目标组件。 |
| timeStamp | number | 是 | 否 | 事件时间戳。 |
## GesturePath
表示手势路径信息。
**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core
### 属性
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| ------------ | ---------------------------------------- | ---- | ---- | ------ |
| points | Array&lt;[GesturePoint](gesturepoint)&gt; | 是 | 是 | 手势。 |
| durationTime | number | 是 | 是 | 手势总耗时。 |
## GesturePoint
表示手势触摸点。
**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core
### 属性
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| --------- | ------ | ---- | ---- | ------- |
| positionX | number | 是 | 是 | 触摸点X坐标。 |
| positionY | number | 是 | 是 | 触摸点Y坐标。 |
## GestureType
手势事件类型。
......@@ -117,16 +91,12 @@ onConnect(): void;
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
无
**示例：**
```ts
onConnect(): void {
console.log("AxExtensionAbility onConnect");
}
};
```
## AccessibilityExtensionAbility.onDisconnect
......@@ -137,16 +107,12 @@ onDisconnect(): void;
**系统能力：** SystemCapability.BarrierFree.Accessibility.Core
**参数：**
无
**示例：**
```ts
onDisconnect(): void {
console.log("AxExtensionAbility onDisconnect");
}
};
```
## AccessibilityExtensionAbility.onAccessibilityEvent
......@@ -171,7 +137,7 @@ onAccessibilityEvent(event: AccessibilityEvent): void {
if (event.eventType == 'click') {
console.log("AxExtensionAbility onAccessibilityEvent: click");
}
}
};
```
## AccessibilityExtensionAbility.onKeyEvent
......@@ -198,5 +164,5 @@ onKeyEvent(keyEvent: inputEventClient.KeyEvent): boolean {
return true;
}
return false;
}
};
```
zh-cn/application-dev/reference/apis/js-apis-bundle-ShortcutInfo.md
浏览文件 @ 5eb8abc0
# ShortcutInfo
# ShortcutInfo<sup>(deprecated)<sup>
> 从API version 9开始不再维护，建议使用[ShortcutInfo](js-apis-bundleManager-shortcutInfo.md)替代
> **说明：**
>
......@@ -12,9 +12,9 @@
## ShortcutWant
## ShortcutWant<sup>(deprecated)<sup>
快捷方式所指向的目标信息。
> 从API version 9开始不再维护，建议使用[ShortcutWant](js-apis-bundleManager-shortcutInfo.md)替代
**系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework
......@@ -26,9 +26,10 @@
| targetModule<sup>9+</sup> | string | 是 | 否 | 快捷方式的目标模块 |
| targetClass | string | 是 | 否 | 快捷方式所需的目标类 |
## ShortcutInfo
## ShortcutInfo<sup>(deprecated)<sup>
> 从API version 9开始不再维护，建议使用[ShortcutInfo](js-apis-bundleManager-shortcutInfo.md)替代。
快捷方式属性信息。
**系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework
......
zh-cn/application-dev/reference/apis/js-apis-bundleManager-shortcutInfo.md 0 → 100644
浏览文件 @ 5eb8abc0
# ShortcutInfo
应用配置文件中定义的快捷方式信息，FA模型配置在[config.json](../../quick-start/package-structure.md)文件中进行配置，Stage模型配置参考[shortcuts对象内部结构](../../quick-start/stage-structure.md#shortcuts对象内部结构)
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
本模块接口为系统接口。
## ShortcutWant
**系统能力:** SystemCapability.BundleManager.BundleFramework.Launcher
**系统接口：** 此接口为系统接口。
| 名称 | 类型 | 可读 | 可写 | 说明 |
| ------------------------- | ------ | ---- | ---- | -------------------- |
| targetBundle | string | 是 | 否 | 快捷方式的目标bundleName |
| targetModule | string | 是 | 否 | 快捷方式的目标moduleName |
| targetAbility | string | 是 | 否 | 快捷方式所需的目标abilityName |
## ShortcutInfo
**系统能力:** SystemCapability.BundleManager.BundleFramework.Launcher
**系统接口：** 此接口为系统接口。
| 名称 | 类型 | 可读 | 可写 | 说明 |
| ----------------------- | ------------------------------------------ | ---- | ---- | ---------------------------- |
| id | string | 是 | 否 | 快捷方式所属应用程序的Id |
| bundleName | string | 是 | 否 | 包含快捷方式的包名称 |
| moduleName | string | 是 | 否 | 快捷方式的模块名 |
| hostAbility | string | 是 | 否 | 快捷方式的本地Ability名称 |
| icon | string | 是 | 否 | 快捷方式的图标 |
| iconId | number | 是 | 否 | 快捷方式的图标Id |
| label | string | 是 | 否 | 快捷方式的标签 |
| labelId | number | 是 | 否 | 快捷方式的标签Id |
| wants | Array\<[ShortcutWant](#shortcutwant)> | 是 | 否 | 快捷方式所需要的信息 |
zh-cn/application-dev/reference/apis/js-apis-device-manager.md
浏览文件 @ 5eb8abc0
......@@ -35,13 +35,24 @@ createDeviceManager(bundleName: string, callback: AsyncCallback&lt;DeviceManager
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ---------------------------------------- | ---- | ------------------------------------ |
| bundleName | string | 是 | 指示应用程序的包名。 |
| callback | AsyncCallback&lt;[DeviceManager](#devicemanager)&gt; | 是 | DeviceManager实例创建时调用的回调，返回设备管理器对象实例。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
| 11600102 | Failed to obtain the service. |
**示例：**
```js
try {
deviceManager.createDeviceManager("ohos.samples.jshelloworld", (err, data) => {
......@@ -209,7 +220,6 @@ createDeviceManager(bundleName: string, callback: AsyncCallback&lt;DeviceManager
设备管理实例，用于获取可信设备和本地设备的相关信息。在调用DeviceManager的方法前，需要先通过createDeviceManager构建一个DeviceManager实例dmInstance。
### release
release(): void
......@@ -218,7 +228,16 @@ release(): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
```js
try {
dmInstance.release();
......@@ -227,7 +246,6 @@ release(): void
}
```
### getTrustedDeviceListSync
getTrustedDeviceListSync(): Array&lt;DeviceInfo&gt;
......@@ -236,12 +254,22 @@ getTrustedDeviceListSync(): Array&lt;DeviceInfo&gt;
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 返回值：
**返回值：**
| 名称 | 说明 |
| -------------------------------------- | --------- |
| Array&lt;[DeviceInfo](#deviceinfo)&gt; | 返回可信设备列表。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
```js
try {
var deviceInfoList = dmInstance.getTrustedDeviceListSync();
......@@ -250,7 +278,6 @@ getTrustedDeviceListSync(): Array&lt;DeviceInfo&gt;
}
```
### getTrustedDeviceList<sup>8+</sup>
getTrustedDeviceList(callback:AsyncCallback&lt;Array&lt;DeviceInfo&gt;&gt;): void
......@@ -259,12 +286,22 @@ getTrustedDeviceList(callback:AsyncCallback&lt;Array&lt;DeviceInfo&gt;&gt;): voi
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | --------------------- |
| callback | AsyncCallback&lt;Array&lt;[DeviceInfo](#deviceinfo)&gt;&gt; | 是 | 获取所有可信设备列表的回调，返回设备信息。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
```js
try {
dmInstance.getTrustedDeviceList((err, data) => {
......@@ -287,22 +324,28 @@ getTrustedDeviceList(): Promise&lt;Array&lt;DeviceInfo&gt;&gt;
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 返回值：
**返回值：**
| 类型 | 说明 |
| ---------------------------------------- | --------------------- |
| Promise&lt;Array&lt;[DeviceInfo](#deviceinfo)&gt;&gt; | Promise实例，用于获取异步返回结果。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
```js
try {
dmInstance.getTrustedDeviceList().then((data) => {
console.log('get trusted device info: ' + JSON.stringify(data));
}).catch((err) => {
console.error("getTrustedDeviceList errCode:" + err.code + ",errMessage:" + err.message);
});
} catch (err) {
dmInstance.getTrustedDeviceList().then((data) => {
console.log('get trusted device info: ' + JSON.stringify(data));
}).catch((err) => {
console.error("getTrustedDeviceList errCode:" + err.code + ",errMessage:" + err.message);
}
});
```
### getLocalDeviceInfoSync<sup>8+</sup>
......@@ -313,12 +356,22 @@ getLocalDeviceInfoSync(): [DeviceInfo](#deviceinfo)
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 返回值：
| 名称 | 说明 |
| -------------------------------------- | --------- |
| Array&lt;[DeviceInfo](#deviceinfo)&gt; | 返回本地设备列表。 |
**返回值：**
| 名称 | 说明 |
| ------------------------- | ---------------- |
| [DeviceInfo](#deviceinfo) | 返回本地设备列表。 |
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
- 示例：
```js
try {
var deviceInfo = dmInstance.getLocalDeviceInfoSync();
......@@ -327,7 +380,6 @@ getLocalDeviceInfoSync(): [DeviceInfo](#deviceinfo)
}
```
### getLocalDeviceInfo<sup>8+</sup>
getLocalDeviceInfo(callback:AsyncCallback&lt;DeviceInfo&gt;): void
......@@ -336,12 +388,22 @@ getLocalDeviceInfo(callback:AsyncCallback&lt;DeviceInfo&gt;): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | --------- |
| callback | AsyncCallback&lt;[DeviceInfo](#deviceinfo)&gt; | 是 | 获取本地设备信息。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
```js
try {
dmInstance.getLocalDeviceInfo((err, data) => {
......@@ -364,22 +426,28 @@ getLocalDeviceInfo(): Promise&lt;DeviceInfo&gt;
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 返回值：
**返回值：**
| 类型 | 说明 |
| ---------------------------------------- | --------------------- |
| Promise&lt;[DeviceInfo](#deviceinfo)&gt; | Promise实例，用于获取异步返回结果。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------------------------- |
| 11600101| Failed to execute the function. |
**示例：**
```js
try {
dmInstance.getLocalDeviceInfo().then((data) => {
console.log('get local device info: ' + JSON.stringify(data));
}).catch((err) => {
console.error("getLocalDeviceInfo errCode:" + err.code + ",errMessage:" + err.message);
});
} catch (err) {
dmInstance.getLocalDeviceInfo().then((data) => {
console.log('get local device info: ' + JSON.stringify(data));
}).catch((err) => {
console.error("getLocalDeviceInfo errCode:" + err.code + ",errMessage:" + err.message);
}
});
```
### startDeviceDiscovery8+</sup>
......@@ -390,12 +458,23 @@ startDeviceDiscovery(subscribeInfo: SubscribeInfo): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| ------------- | ------------------------------- | ---- | ----- |
| subscribeInfo | [SubscribeInfo](#subscribeinfo) | 是 | 发现信息。 |
| subscribeInfo | [SubscribeInfo](#subscribeinfo) | 是 | 发现信息。|
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
| 11600104 | Discovery invalid. |
**示例：**
- 示例：
```js
// 生成发现标识，随机数确保每次调用发现接口的标识不一致
var subscribeId = Math.floor(Math.random() * 10000 + 1000);
......@@ -423,13 +502,24 @@ startDeviceDiscovery(subscribeInfo: SubscribeInfo, filterOptions?: string): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
| 名称 | 参数类型 | 必填 | 说明 |
| ------------- | ------------------------------- | ---- | ----- |
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| ------------- | ------------------------------- | ---- | ----- |
| subscribeInfo | [SubscribeInfo](#subscribeinfo) | 是 | 发现信息。 |
| filterOptions | string | 否 | 发现设备过滤信息。|
| filterOptions | string | 否 | 发现设备过滤信息。|
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
| 11600104 | Discovery invalid. |
**示例：**
- 示例：
```js
// 生成发现标识，随机数确保每次调用发现接口的标识不一致
var subscribeId = Math.floor(Math.random() * 10000 + 1000);
......@@ -457,7 +547,7 @@ startDeviceDiscovery(subscribeInfo: SubscribeInfo, filterOptions?: string): void
console.error("startDeviceDiscovery errCode:" + err.code + ",errMessage:" + err.message);
}
```
### stopDeviceDiscovery
stopDeviceDiscovery(subscribeId: number): void
......@@ -466,12 +556,22 @@ stopDeviceDiscovery(subscribeId: number): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| ----------- | ------ | ---- | ----- |
| subscribeId | number | 是 | 发现标识。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
```js
// 入参需要和startDeviceDiscovery接口传入的subscribeId配对使用
try {
......@@ -489,12 +589,23 @@ publishDeviceDiscovery(publishInfo: PublishInfo): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| ------------- | ------------------------------- | ---- | ----- |
| publishInfo | [PublishInfo](#publishinfo) | 是 | 发布设备发现信息。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
| 11600105 | Publish invalid. |
**示例：**
```js
// 生成发布标识，随机数确保每次调用发布接口的标识不一致
var publishId = Math.floor(Math.random() * 10000 + 1000);
......@@ -519,12 +630,22 @@ unPublishDeviceDiscovery(publishId: number): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| ----------- | -------- | ---- | ----- |
| publishId | number | 是 | 发布标识。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
```js
// 入参需要和publishDeviceDiscovery接口传入的publishId配对使用
try {
......@@ -542,14 +663,25 @@ authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: Async
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| ---------- | ---------------------------------------- | ---- | ------- |
| deviceInfo | [DeviceInfo](#deviceinfo) | 是 | 设备信息。 |
| authParam | [AuthParam](#authparam) | 是 | 认证参数。 |
| callback | AsyncCallback<{ deviceId: string, pinToken ?: number }> | 是 | 认证结果回调。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
| 11600103 | Authentication invalid. |
**示例：**
```js
// 认证的设备信息，可以从发现的结果中获取
var deviceInfo ={
......@@ -567,8 +699,8 @@ authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: Async
console.error("authenticateDevice errCode:" + err.code + ",errMessage:" + err.message);
return;
}
console.info(TAG + "authenticateDevice result:" + JSON.stringify(data));
token = data.pinToken;
console.info("authenticateDevice result:" + JSON.stringify(data));
let token = data.pinToken;
});
} catch (err) {
console.error("authenticateDevice errCode:" + err.code + ",errMessage:" + err.message);
......@@ -583,12 +715,22 @@ unAuthenticateDevice(deviceInfo: DeviceInfo): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| ---------- | ------------------------- | ---- | ----- |
| deviceInfo | [DeviceInfo](#deviceinfo) | 是 | 设备信息。 |
- 示例：
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
```js
try {
dmInstance.unAuthenticateDevice(deviceInfo);
......@@ -597,7 +739,6 @@ unAuthenticateDevice(deviceInfo: DeviceInfo): void
}
```
### verifyAuthInfo
verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void
......@@ -606,13 +747,23 @@ verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, le
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | ------- |
| authInfo | [AuthInfo](#authinfo) | 是 | 认证信息。 |
| authInfo | AsyncCallback<{ deviceId: string, level: number }> | 是 | 验证结果回调。 |
| callback | AsyncCallback<{ deviceId: string, level: number }> | 是 | 验证结果回调。 |
**错误码：**
以下的错误码的详细介绍请参见[设备管理错误码](../errorcodes/errorcode-device-manager.md)
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------------------------- |
| 11600101 | Failed to execute the function. |
**示例：**
- 示例：
```js
let authInfo = {
"authType": 1,
......@@ -625,13 +776,104 @@ verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, le
console.error("verifyAuthInfo errCode:" + err.code + ",errMessage:" + err.message);
return;
}
console.info(TAG + "verifyAuthInfo result:" + JSON.stringify(data));
console.info("verifyAuthInfo result:" + JSON.stringify(data));
});
} catch (err) {
console.error("verifyAuthInfo errCode:" + err.code + ",errMessage:" + err.message);
}
```
### setUserOperation9+</sup>
setUserOperation(operateAction: number, params: string): void;
设置用户ui操作行为。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| ------------- | --------------- | ---- | ------------------- |
| operateAction | number | 是 | 用户操作动作。 |
| params | string | 是 | 表示用户的输入参数。 |
**示例：**
```js
try {
/*
operateAction = 0 - 允许授权
operateAction = 1 - 取消授权
operateAction = 2 - 授权框用户操作超时
operateAction = 3 - 取消pin码框展示
operateAction = 4 - 取消pin码输入框展示
operateAction = 5 - pin码输入框确定操作
*/
let operation = 0;
this.dmInstance.setUserOperation(operation, "extra")
} catch (err) {
console.error("setUserOperation errCode:" + err.code + ",errMessage:" + err.message);
}
```
### on('uiStateChange')9+</sup>
on(type: 'uiStateChange', callback: Callback<{ param: string}>): void;
ui状态变更回调。
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ------------------------------------ | ---- | ------------------------------ |
| type | string | 是 | 注册的设备管理器 ui 状态回调，以便在状态改变时通知应用。 |
| callback | Callback&lt;{&nbsp;param: string}&gt; | 是 | 指示要注册的设备管理器 ui 状态回调，返回ui状态。 |
**示例：**
```js
try {
dmInstance.on('uiStateChange', (data) => {
console.log("uiStateChange executed, dialog closed" + JSON.stringify(data))
var tmpStr = JSON.parse(data.param)
this.isShow = tmpStr.verifyFailed
console.log("uiStateChange executed, dialog closed" + this.isShow)
if (!this.isShow) {
this.destruction()
}
});
} catch (err) {
console.error("uiStateChange errCode:" + err.code + ",errMessage:" + err.message);
}
```
### off('uiStateChange')9+</sup>
off(type: 'uiStateChange', callback?: Callback<{ param: string}>): void;
取消ui状态变更回调
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ------------------------------------- | ---- | ------------------------------ |
| type | string | 是 | 取消注册的设备管理器 ui 状态回调。 |
| callback | Callback&lt;{&nbsp;param: string}&gt; | 是 | 指示要取消注册的设备管理器 ui 状态，返回UI状态。 |
**示例：**
```js
try {
dmInstance.off('uiStateChange');
} catch (err) {
console.error("uiStateChange errCode:" + err.code + ",errMessage:" + err.message);
}
```
### on('deviceStateChange')
......@@ -641,13 +883,15 @@ on(type: 'deviceStateChange', callback: Callback&lt;{ action: DeviceStateChange
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | ------------------------------ |
| type | string | 是 | 注册设备状态回调，固定为deviceStateChange。 |
| callback | Callback&lt;{&nbsp;action:&nbsp;[DeviceStateChangeAction](#devicestatechangeaction),&nbsp;device:&nbsp;[DeviceInfo](#deviceinfo)&nbsp;}&gt; | 是 | 指示要注册的设备状态回调，返回设备状态和设备信息。 |
- 示例：
**示例：**
```js
try {
dmInstance.on('deviceStateChange', (data) => {
......@@ -658,7 +902,6 @@ on(type: 'deviceStateChange', callback: Callback&lt;{ action: DeviceStateChange
}
```
### off('deviceStateChange')
off(type: 'deviceStateChange', callback?: Callback&lt;{ action: DeviceStateChangeAction, device: DeviceInfo }&gt;): void
......@@ -667,13 +910,15 @@ off(type: 'deviceStateChange', callback?: Callback&lt;{ action: DeviceStateChang
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | --------------------------- |
| type | string | 是 | 根据应用程序的包名取消注册设备状态回调。 |
| callback | Callback&lt;{&nbsp;action:&nbsp;[DeviceStateChangeAction](#devicestatechangeaction),&nbsp;device:&nbsp;[DeviceInfo](#deviceinfo)&nbsp;&nbsp;}&gt; | 是 | 指示要取消注册的设备状态回调，返回设备状态和设备信息。 |
- 示例：
**示例：**
```js
try {
dmInstance.off('deviceStateChange', (data) => {
......@@ -684,7 +929,6 @@ off(type: 'deviceStateChange', callback?: Callback&lt;{ action: DeviceStateChang
}
```
### on('deviceFound')
on(type: 'deviceFound', callback: Callback&lt;{ subscribeId: number, device: DeviceInfo }&gt;): void
......@@ -693,13 +937,15 @@ on(type: 'deviceFound', callback: Callback&lt;{ subscribeId: number, device: Dev
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | -------------------------- |
| type | string | 是 | 注册设备发现回调，以便在发现周边设备时通知应用程序。 |
| callback | Callback&lt;{&nbsp;subscribeId: number, device: DeviceInfo&nbsp;}&gt; | 是 | 注册设备发现的回调方法。 |
- 示例：
**示例：**
```js
try {
dmInstance.on('deviceFound', (data) => {
......@@ -718,13 +964,15 @@ off(type: 'deviceFound', callback?: Callback&lt;{ subscribeId: number, device: D
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | --------------------------- |
| type | string | 是 | 取消注册设备发现回调。 |
| callback | Callback&lt;{&nbsp;subscribeId: number, device: [DeviceInfo](#deviceinfo)&nbsp;}&gt; | 是 | 指示要取消注册的设备发现回调，返回设备状态和设备信息。 |
- 示例：
**示例：**
```js
try {
dmInstance.off('deviceFound', (data) => {
......@@ -743,13 +991,15 @@ on(type: 'discoverFail', callback: Callback&lt;{ subscribeId: number, reason: nu
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | ------------------------------ |
| type | string | 是 | 注册设备发现失败回调，以便在发现周边设备失败时通知应用程序。 |
| callback | Callback&lt;{&nbsp;subscribeId: number, reason: number&nbsp;}&gt; | 是 | 注册设备发现失败的回调方法。 |
- 示例：
**示例：**
```js
try {
dmInstance.on('discoverFail', (data) => {
......@@ -768,13 +1018,15 @@ off(type: 'discoverFail', callback?: Callback&lt;{ subscribeId: number, reason:
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | ----------------- |
| type | string | 是 | 取消注册设备发现失败回调。 |
| callback | Callback&lt;{&nbsp;subscribeId: number, reason: number&nbsp;}&gt; | 是 | 指示要取消注册的设备发现失败回调。 |
- 示例：
**示例：**
```js
try {
dmInstance.off('discoverFail', (data) => {
......@@ -793,13 +1045,16 @@ on(type: 'publishSuccess', callback: Callback&lt;{ publishId: number }&gt;): voi
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | -------------------------- |
| type | string | 是 | 注册发布设备成功回调，以便将发布成功时通知应用程序。 |
| callback | Callback&lt;{ publishId: number }&gt; | 是 | 注册设备发布成功的回调方法。 |
- 示例：
**示例：**
```js
try {
dmInstance.on('publishSuccess', (data) => {
......@@ -818,13 +1073,15 @@ off(type: 'publishSuccess', callback?: Callback&lt;{ publishId: number }&gt;): v
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | --------------------------- |
| type | string | 是 | 取消注册设备发布成功回调。 |
| callback | Callback&lt;{ publishId: number }&gt; | 是 | 指示要取消注册的设备发布成功回调。 |
- 示例：
**示例：**
```js
try {
dmInstance.off('publishSuccess', (data) => {
......@@ -843,13 +1100,15 @@ on(type: 'publishFail', callback: Callback&lt;{ publishId: number, reason: numbe
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ----------------------------------------------------- | ---- | ------------------------------ |
| type | string | 是 | 注册设备发布失败回调，以便在发布设备失败时通知应用程序。 |
| callback | Callback&lt;{ publishId: number, reason: number }&gt; | 是 | 注册设备发布失败的回调方法。 |
- 示例：
**示例：**
```js
try {
dmInstance.on('publishFail', (data) => {
......@@ -868,13 +1127,15 @@ off(type: 'publishFail', callback?: Callback&lt;{ publishId: number, reason: num
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ----------------------------------------------------- | ---- | ----------------- |
| type | string | 是 | 取消注册设备发布失败回调。 |
| callback | Callback&lt;{ publishId: number, reason: number }&gt; | 是 | 指示要取消注册设备发布失败回调。 |
- 示例：
**示例：**
```js
try {
dmInstance.off('publishFail', (data) => {
......@@ -893,13 +1154,15 @@ on(type: 'serviceDie', callback: () =&gt; void): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ----------------------- | ---- | ---------------------------------------- |
| type | string | 是 | 注册serviceDie回调，以便在devicemanager服务异常终止时通知应用程序。 |
| callback | ()&nbsp;=&gt;&nbsp;void | 是 | 注册serviceDie的回调方法。 |
- 示例：
**示例：**
```js
try {
dmInstance.on("serviceDie", () => {
......@@ -910,7 +1173,6 @@ on(type: 'serviceDie', callback: () =&gt; void): void
}
```
### off('serviceDie')
off(type: 'serviceDie', callback?: () =&gt; void): void
......@@ -919,13 +1181,15 @@ off(type: 'serviceDie', callback?: () =&gt; void): void
**系统能力**：SystemCapability.DistributedHardware.DeviceManager
- 参数：
**参数：**
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | ----------------------- | ---- | ---------------------------------------- |
| type | string | 是 | 取消注册serviceDie回调，以便在devicemanager服务异常终止时通知应用程序。 |
| callback | ()&nbsp;=&gt;&nbsp;void | 否 | 取消注册serviceDie的回调方法。 |
- 示例：
**示例：**
```js
try {
dmInstance.off("serviceDie", () => {
......
zh-cn/application-dev/reference/apis/js-apis-distributed-account.md
浏览文件 @ 5eb8abc0
......@@ -7,7 +7,7 @@
## 导入模块
```js
import account_distributedAccount from '@ohos.account.distributedAccount';
```
......@@ -40,7 +40,7 @@ getDistributedAccountAbility(): DistributedAccountAbility
getOsAccountDistributedInfo(callback: AsyncCallback&lt;DistributedInfo&gt;): void
获取分布式帐号信息，使用callback回调异步返回结果。
获取分布式帐号信息，使用callback异步回调。
**系统能力：** SystemCapability.Account.OsAccount
......@@ -50,7 +50,15 @@ getOsAccountDistributedInfo(callback: AsyncCallback&lt;DistributedInfo&gt;): voi
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[DistributedInfo](#distributedinfo)&gt; | 是 | 获取分布式帐号信息的回调。 |
| callback | AsyncCallback&lt;[DistributedInfo](#distributedinfo)&gt; | 是 | 回调参数。当获取分布式帐号信息成功，err为undefined，data为获取到的分布式帐号信息对象；否则为错误对象。 |
**错误码：**
| 错误码ID | 错误信息|
| ------- | -------|
| 201 | permission denied. |
| 401 | the parameter check failed. |
| 12300001 | system service exception. |
**示例：**
```js
......@@ -70,7 +78,7 @@ getOsAccountDistributedInfo(callback: AsyncCallback&lt;DistributedInfo&gt;): voi
getOsAccountDistributedInfo(): Promise&lt;DistributedInfo&gt;
获取分布式帐号信息，使用Promise方式异步返回结果。
获取分布式帐号信息。使用Promise异步回调。
**系统能力：** SystemCapability.Account.OsAccount
......@@ -80,7 +88,15 @@ getOsAccountDistributedInfo(): Promise&lt;DistributedInfo&gt;
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;[DistributedInfo](#distributedinfo)&gt; | Promise实例，用于获取异步返回结果。 |
| Promise&lt;[DistributedInfo](#distributedinfo)&gt; | Promise对象。返回分布式帐号信息对象。 |
**错误码：**
| 错误码ID | 错误信息|
| ------- | -------|
| 201 | permission denied. |
| 401 | the parameter check failed. |
| 12300001 | system service exception. |
**示例：**
```js
......@@ -100,7 +116,7 @@ getOsAccountDistributedInfo(): Promise&lt;DistributedInfo&gt;
queryOsAccountDistributedInfo(callback: AsyncCallback&lt;DistributedInfo&gt;): void
获取分布式帐号信息，使用callback回调异步返回结果。
获取分布式帐号信息。使用callback异步回调。
> **说明：** 从API version 9开始废弃，建议使用[getOsAccountDistributedInfo](#getosaccountdistributedinfo9)
>
> 从 API version 7开始支持。
......@@ -113,7 +129,7 @@ queryOsAccountDistributedInfo(callback: AsyncCallback&lt;DistributedInfo&gt;): v
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[DistributedInfo](#distributedinfo)&gt; | 是 | 获取分布式帐号信息的回调。 |
| callback | AsyncCallback&lt;[DistributedInfo](#distributedinfo)&gt; | 是 | 回调函数。当获取分布式帐号信息成功，err为undefined，data为获取到的分布式帐号信息对象；否则为错误对象。 |
**示例：**
```js
......@@ -129,7 +145,7 @@ queryOsAccountDistributedInfo(callback: AsyncCallback&lt;DistributedInfo&gt;): v
queryOsAccountDistributedInfo(): Promise&lt;DistributedInfo&gt;
获取分布式帐号信息，使用Promise方式异步返回结果。
获取分布式帐号信息。使用Promise异步回调。
> **说明：** 从API version 9开始废弃，建议使用[getOsAccountDistributedInfo](#getosaccountdistributedinfo9-1)
>
> 从 API version 7开始支持。
......@@ -142,7 +158,7 @@ queryOsAccountDistributedInfo(): Promise&lt;DistributedInfo&gt;
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;[DistributedInfo](#distributedinfo)&gt; | Promise实例，用于获取异步返回结果。 |
| Promise&lt;[DistributedInfo](#distributedinfo)&gt; | Promise对象。返回分布式帐号信息对象。 |
**示例：**
```js
......@@ -159,7 +175,7 @@ queryOsAccountDistributedInfo(): Promise&lt;DistributedInfo&gt;
setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback&lt;void&gt;): void
更新分布式帐号信息，使用callback回调异步返回结果。
更新分布式帐号信息。使用callback异步回调。
**系统能力：** SystemCapability.Account.OsAccount
......@@ -170,7 +186,16 @@ setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallbac
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐号信息。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 更新分布式帐号信息的回调。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当更新分布式帐号信息成功时，err为undefined，否则为错误对象。 |
**错误码：**
| 错误码ID | 错误信息|
| ------- | -------|
| 201 | permission denied. |
| 401 | the parameter check failed. |
| 12300001 | system service exception. |
| 12300002 | invalid accountInfo. |
**示例：**
```js
......@@ -189,7 +214,7 @@ setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallbac
setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise&lt;void&gt;
更新分布式帐号信息，使用Promise方式异步返回结果。
更新分布式帐号信息。使用Promise异步回调。
**系统能力：** SystemCapability.Account.OsAccount
......@@ -205,7 +230,16 @@ setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise&lt;void&gt;
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | Promise实例，用于获取异步返回结果。 |
| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
**错误码：**
| 错误码ID | 错误信息|
| ------- | -------|
| 201 | permission denied. |
| 401 | the parameter check failed. |
| 12300001 | system service exception. |
| 12300002 | invalid accountInfo. |
**示例：**
```js
......@@ -225,7 +259,7 @@ setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise&lt;void&gt;
updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback&lt;void&gt;): void
更新分布式帐号信息，使用callback回调异步返回结果。
更新分布式帐号信息。使用callback异步回调。
> **说明：** 从API version 9开始废弃，建议使用[setOsAccountDistributedInfo](#setosaccountdistributedinfo9)
>
> 从 API version 7开始支持。
......@@ -239,7 +273,7 @@ updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCall
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐号信息。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 更新分布式帐号信息的回调。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当更新分布式帐号信息成功时，err为undefined，否则为错误对象。 |
**示例：**
```js
......@@ -254,7 +288,7 @@ updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCall
updateOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise&lt;void&gt;
更新分布式帐号信息，使用Promise方式异步返回结果。
更新分布式帐号信息。使用Promise异步回调。
> **说明：** 从API version 9开始废弃，建议使用[setOsAccountDistributedInfo](#setosaccountdistributedinfo9-1)
>
> 从 API version 7开始支持。
......@@ -272,7 +306,7 @@ updateOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise&lt;void&gt
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | Promise实例，用于获取异步返回结果。 |
| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
**示例：**
```js
......
zh-cn/application-dev/reference/apis/js-apis-distributedMissionManager.md
浏览文件 @ 5eb8abc0
......@@ -48,7 +48,7 @@ registerMissionListener(parameter: MissionDeviceInfo, options: MissionCallback,
console.log('NotifyNetDisconnect state ' + JSON.stringify(state));
}
var parameter = {
deviceId: remoteDeviceId
deviceId: ""
};
var options = {
notifyMissionsChanged: NotifyMissionsChanged,
......@@ -104,7 +104,7 @@ registerMissionListener(parameter: MissionDeviceInfo, options: MissionCallback):
console.log('NotifyNetDisconnect state ' + JSON.stringify(state));
}
var parameter = {
deviceId: remoteDeviceId
deviceId: ""
};
var options = {
notifyMissionsChanged: NotifyMissionsChanged,
......@@ -145,7 +145,7 @@ unRegisterMissionListener(parameter: MissionDeviceInfo, callback: AsyncCallback&
```ts
var parameter = {
deviceId: remoteDeviceId
deviceId: ""
};
try {
distributedMissionManager.unRegisterMissionListener(parameter, (error) => {
......@@ -186,7 +186,7 @@ unRegisterMissionListener(parameter: MissionDeviceInfo): Promise&lt;void&gt;
```ts
var parameter = {
deviceId: remoteDeviceId
deviceId: ""
};
try {
distributedMissionManager.unRegisterMissionListener(parameter)
......@@ -221,7 +221,7 @@ startSyncRemoteMissions(parameter: MissionParameter, callback: AsyncCallback&lt;
```ts
var parameter = {
deviceId: remoteDeviceId,
deviceId: "",
fixConflict: false,
tag: 0
};
......@@ -263,7 +263,7 @@ startSyncRemoteMissions(parameter: MissionParameter): Promise&lt;void&gt;
```ts
var parameter = {
deviceId: remoteDeviceId,
deviceId: "",
fixConflict: false,
tag: 0
};
......@@ -300,7 +300,7 @@ stopSyncRemoteMissions(parameter: MissionDeviceInfo, callback: AsyncCallback&lt;
```ts
var parameter = {
deviceId: remoteDeviceId
deviceId: ""
};
try {
distributedMissionManager.stopSyncRemoteMissions(parameter, (error) => {
......@@ -340,7 +340,7 @@ stopSyncRemoteMissions(parameter: MissionDeviceInfo): Promise&lt;void&gt;
```ts
var parameter = {
deviceId: remoteDeviceId
deviceId: ""
};
try {
distributedMissionManager.stopSyncRemoteMissions(parameter)
......@@ -376,10 +376,10 @@ continueMission(parameter: ContinueDeviceInfo, options: ContinueCallback, callba
```ts
var parameter = {
srcDeviceId: localDeviceId,
dstDeviceId: remoteDeviceId,
missionId: remoteMissionId,
wantParams: {"key": "value"}
srcDeviceId: "",
dstDeviceId: "",
missionId: 1,
wantParam: {"key": "value"}
};
function OnContinueDone(resultCode) {
console.log('OnContinueDone resultCode: ' + JSON.stringify(resultCode));
......@@ -426,10 +426,10 @@ continueMission(parameter: ContinueDeviceInfo, options: ContinueCallback): Promi
```ts
var parameter = {
srcDeviceId: localDeviceId,
dstDeviceId: remoteDeviceId,
missionId: remoteMissionId,
wantParams: {"key": "value"}
srcDeviceId: "",
dstDeviceId: "",
missionId: 1,
wantParam: {"key": "value"}
};
function OnContinueDone(resultCode) {
console.log('OnContinueDone resultCode: ' + JSON.stringify(resultCode));
......@@ -501,8 +501,8 @@ continueMission(parameter: ContinueDeviceInfo, options: ContinueCallback): Promi
| -------- | ------ | ---- | ---- | ------- |
| srcDeviceId | string | 是 | 是 | 表示任务迁移源设备ID。 |
| dstDeviceId | string | 是 | 是 | 表示任务迁移目标设备ID。 |
| missionId | string | 是 | 是 | 表示任务ID。 |
| wantParams | {[key: string]: any} | 是 | 是 | 表示扩展参数。 |
| missionId | number | 是 | 是 | 表示任务ID。 |
| wantParam | {[key: string]: any} | 是 | 是 | 表示扩展参数。 |
## ContinueCallback
......
zh-cn/application-dev/reference/apis/js-apis-hiappevent.md
浏览文件 @ 5eb8abc0
......@@ -3,7 +3,7 @@
本模块提供了应用事件打点能力，包括对打点数据的落盘，以及对打点功能的管理配置。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> - 本模块接口从API version 9开始废弃，建议使用新接口[@ohos.hiviewdfx.hiAppEvent](js-apis-hiviewdfx-hiappevent)替代。
> - 本模块接口从API version 9开始废弃，建议使用新接口[@ohos.hiviewdfx.hiAppEvent](js-apis-hiviewdfx-hiappevent.md)替代。
> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
......
zh-cn/application-dev/reference/apis/js-apis-hichecker.md
浏览文件 @ 5eb8abc0
......@@ -26,11 +26,103 @@ import hichecker from '@ohos.hichecker';
| RULE_THREAD_CHECK_SLOW_PROCESS | bigint | 检测规则，检测是否有耗时函数被调用。 |
| RULE_CHECK_ABILITY_CONNECTION_LEAK | bigint | 检测规则，检测是否发生ability泄露。 |
## hichecker.addCheckRule<sup>9+</sup>
## hichecker.addRule
addCheckRule(rule: bigint): void
添加一条或多条规则到系统，系统根据添加的规则进行检测或反馈。
**系统能力：** SystemCapability.HiviewDFX.HiChecker
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| rule | bigint | 是 | 需要添加的规则。 |
**示例：**
```js
try {
// 添加一条规则
hichecker.addCheckRule(hichecker.RULE_CAUTION_PRINT_LOG);}
// 添加多条规则
hichecker.addCheckRule(
hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH);
catch (err) {
console.error(`code: ${err.code}, message: ${err.message}`);
}
```
## hichecker.removeCheckRule<sup>9+</sup>
removeCheckRule(rule: bigint): void
删除一条或多条规则，删除的规则后续将不再生效。
**系统能力：** SystemCapability.HiviewDFX.HiChecker
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| rule | bigint | 是 | 需要删除的规则。 |
**示例：**
```js
try {
// 删除一条规则
hichecker.removeCheckRule(hichecker.RULE_CAUTION_PRINT_LOG);
// 删除多条规则
hichecker.removeCheckRule(
hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH);
catch (err) {
console.error(`code: ${err.code}, message: ${err.message}`);
}
```
## hichecker.containsCheckRule<sup>9+</sup>
containsCheckRule(rule: bigint): boolean
当前已添加的规则集中是否包含了某一个特定的规则，如果传入的规则级别为线程级别，则仅在当前线程中进行查询。
**系统能力：** SystemCapability.HiviewDFX.HiChecker
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| rule | bigint | 是 | 需要查询的规则。 |
**返回值：**
| 类型 | 说明 |
| ------- | ---------------------------------------------------------- |
| boolean | 查询结果，true&nbsp;表示规则已添加，false 表示规则未添加。 |
**示例：**
```js
try {
// 添加一条规则
hichecker.addCheckRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS);
// 查询是否包含
hichecker.containsCheckRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); // return true;
hichecker.containsCheckRule(hichecker.RULE_CAUTION_PRINT_LOG); // return false;
catch (err) {
console.error(`code: ${err.code}, message: ${err.message}`);
}
```
## hichecker.addRule<sup>(deprecated)</sup>
addRule(rule: bigint): void
> **说明：** 从 API Version 9 开始废弃，建议使用[hichecker.addCheckRule](#hicheckeraddcheckrule9)替代。
添加一条或多条规则到系统，系统根据添加的规则进行检测或反馈。
**系统能力：** SystemCapability.HiviewDFX.HiChecker
......@@ -52,10 +144,12 @@ hichecker.addRule(
hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH);
```
## hichecker.removeRule
## hichecker.removeRule<sup>(deprecated)</sup>
removeRule(rule: bigint): void
> **说明：** 从 API Version 9 开始废弃，建议使用[hichecker.removeCheckRule](#hicheckerremovecheckrule9)替代。
删除一条或多条规则，删除的规则后续将不再生效。
**系统能力：** SystemCapability.HiviewDFX.HiChecker
......@@ -101,10 +195,12 @@ hichecker.addRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS);
hichecker.getRule(); // return 1n;
```
## hichecker.contains
## hichecker.contains<sup>(deprecated)</sup>
contains(rule: bigint): boolean
> **说明：** 从 API Version 9 开始废弃，建议使用[hichecker.containsCheckRule](#hicheckercontainscheckrule9)替代。
当前已添加的规则集中是否包含了某一个特定的规则，如果传入的规则级别为线程级别，则仅在当前线程中进行查询。
**系统能力：** SystemCapability.HiviewDFX.HiChecker
......
zh-cn/application-dev/reference/apis/js-apis-hidebug.md
浏览文件 @ 5eb8abc0
......@@ -162,10 +162,12 @@ getCpuUsage(): number
let cpuUsage = hidebug.getCpuUsage();
```
## hidebug.startProfiling
## hidebug.startProfiling<sup>(deprecated)</sup>
startProfiling(filename : string) : void
> **说明：** 从 API Version 9 开始废弃，建议使用[hidebug.startJsCpuProfiling](#hidebugstartjscpuprofiling9)替代。
启动虚拟机Profiling方法跟踪，`startProfiling()`方法的调用需要与`stopProfiling()`方法的调用一一对应，先开启后关闭，严禁使用`start->start->stop`，`start->stop->stop`，`start->start->stop->stop`等类似的顺序调用。
**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug
......@@ -188,10 +190,12 @@ hidebug.stopProfiling();
## hidebug.stopProfiling
## hidebug.stopProfiling<sup>(deprecated)</sup>
stopProfiling() : void
> **说明：** 从 API Version 9 开始废弃，建议使用[hidebug.stopJsCpuProfiling](#hidebugstopjscpuprofiling9)替代。
停止虚拟机Profiling方法跟踪，`stopProfiling()`方法的调用需要与`startProfiling()`方法的调用一一对应，先开启后关闭，严禁使用`start->start->stop`，`start->stop->stop`，`start->start->stop->stop`等类似的顺序调用。
**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug
......@@ -206,10 +210,12 @@ hidebug.startProfiling("cpuprofiler-20220216");
hidebug.stopProfiling();
```
## hidebug.dumpHeapData
## hidebug.dumpHeapData<sup>(deprecated)</sup>
dumpHeapData(filename : string) : void
> **说明：** 从 API Version 9 开始废弃，建议使用[hidebug.dumpJsHeapData](#hidebugdumpjsheapdata9)替代。
虚拟机堆导出。
**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug
......@@ -228,11 +234,11 @@ hidebug.dumpHeapData("heap-20220216");
## hidebug.getServiceDump<sup>9+<sup>
getServiceDump(serviceid : number) : string
getServiceDump(serviceid : number, fd : number, args : Array<string>) : void
获取系统服务信息。
此接口为系统接口，三方应用不可用。
**需要权限**: ohos.permission.DUMP
**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug
......@@ -241,16 +247,115 @@ getServiceDump(serviceid : number) : string
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| serviceid | number | 是 | 基于该用户输入的service id获取系统服务信息。|
| fd | number | 是 | 文件描述符，该接口会往该fd中写入数据。|
| args | Array<string> | 是 | 系统服务的Dump接口所对应的参数列表。|
**返回值：**
| 类型 | 说明 |
| ------ | -------------------------- |
| string | 返回dump的service信息文件的绝对路径。 |
**示例：**
```js
import fileio from '@ohos.fileio'
import hidebug from '@ohos.hidebug'
import featureAbility from '@ohos.ability.featureAbility'
let context = featureAbility.getContext();
context.getFilesDir().then((data) => {
var path = data + "/serviceInfo.txt"
console.info("output path: " + path)
let fd = fileio.openSync(path, 0o102, 0o666)
var serviceId = 10
var args = new Array("allInfo")
try {
hidebug.getServiceDump(serviceId, fd, args)
} catch (error) {
console.info(error.code)
console.info(error.message)
}
fileio.closeSync(fd);
})
```
## hidebug.startJsCpuProfiling<sup>9+</sup>
startJsCpuProfiling(filename : string) : void
启动虚拟机Profiling方法跟踪，`startJsCpuProfiling()`方法的调用需要与`stopJsCpuProfiling()`方法的调用一一对应，先开启后关闭，严禁使用`start->start->stop`，`start->stop->stop`，`start->start->stop->stop`等类似的顺序调用。
**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| filename | string | 是 | 用户自定义的profiling文件名，根据传入的`filename`，将在应用的`files`目录生成`filename.json`文件。 |
**示例：**
```js
import hidebug from '@ohos.hidebug'
try {
hidebug.startJsCpuProfiling("cpu_profiling");
...
hidebug.stopJsCpuProfiling();
} catch (error) {
console.info(error.code)
console.info(error.message)
}
```
## hidebug.stopJsCpuProfiling<sup>9+</sup>
stopJsCpuProfiling() : void
停止虚拟机Profiling方法跟踪，`startJsCpuProfiling()`方法的调用需要与`stopJsCpuProfiling()`方法的调用一一对应，先开启后关闭，严禁使用`start->start->stop`，`start->stop->stop`，`start->start->stop->stop`等类似的顺序调用。
**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| filename | string | 是 | 用户自定义的profiling文件名，根据传入的`filename`，将在应用的`files`目录生成`filename.json`文件。 |
**示例：**
```js
import hidebug from '@ohos.hidebug'
try {
hidebug.startJsCpuProfiling("cpu_profiling");
...
hidebug.stopJsCpuProfiling();
} catch (error) {
console.info(error.code)
console.info(error.message)
}
```
## hidebug.dumpJsHeapData<sup>9+</sup>
dumpJsHeapData(filename : string) : void
虚拟机堆导出。
**系统能力：** SystemCapability.HiviewDFX.HiProfiler.HiDebug
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| filename | string | 是 | 用户自定义的虚拟机堆文件名，根据传入的`filename`，将在应用的`files`目录生成`filename.heapsnapshot`文件。 |
**示例：**
```js
let serviceId = 10;
let pathName = hidebug.getServiceDump(serviceId);
import hidebug from '@ohos.hidebug'
try {
hidebug.dumpJsHeapData("heapData");
} catch (error) {
console.info(error.code)
console.info(error.message)
}
```
\ No newline at end of file
zh-cn/application-dev/reference/apis/js-apis-hisysevent.md
浏览文件 @ 5eb8abc0
......@@ -55,6 +55,21 @@ write(info: SysEventInfo, callback: AsyncCallback&lt;void&gt;): void
| info | [SysEventInfo](#syseventinfo) | 是 | 系统事件。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数，可以在回调函数中处理接口返回值。<br/>- 0表示事件校验成功，事件正常异步写入事件文件；<br/>- 正值表示事件打点存在异常，但可以正常写入；<br/>- 负值表示事件打点失败。 |
**错误码：**
以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。
| 错误码ID | 错误信息 |
| ------- | ----------------------------------------------------------------- |
| 11200001 | Invalid event domain. |
| 11200002 | Invalid event name. |
| 11200003 | Abnormal environment. |
| 11200004 | Length of the event is over limit. |
| 11200051 | Invalid event parameter. |
| 11200052 | Size of the event parameter of the string type is over limit. |
| 11200053 | Count of event parameters is over limit. |
| 11200054 | Count of event parameter of the array type is over limit. |
**示例：**
```js
......@@ -101,6 +116,21 @@ write(info: SysEventInfo): Promise&lt;void&gt;
| ------------------- | ------------------------------------------------------------ |
| Promise&lt;void&gt; | Promise实例，可以在其then()、catch()方法中分别对系统事件写入成功、写入异常的回调进行处理。 |
**错误码：**
以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------------------------------- |
| 11200001 | Invalid event domain. |
| 11200002 | Invalid event name. |
| 11200003 | Abnormal environment. |
| 11200004 | Length of the event is over limit. |
| 11200051 | Invalid event parameter. |
| 11200052 | Size of the event parameter of the string type is over limit. |
| 11200053 | Count of event parameters is over limit. |
| 11200054 | Count of event parameter of the array type is over limit. |
**示例：**
```js
......@@ -171,7 +201,7 @@ try {
## hiSysEvent.addWatcher
addWatcher(watcher: Watcher): number
addWatcher(watcher: Watcher): void
订阅系统事件，接收[Watcher](#watcher)类型的对象作为事件参数。
......@@ -185,6 +215,15 @@ addWatcher(watcher: Watcher): number
| ------ | ----------------------------- | ---- | ------------------------ |
| watcher | [Watcher](#watcher) | 是 | 系统事件订阅者对象。 |
**错误码：**
以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。
| 错误码ID | 错误信息 |
| -------- | ----------------------------------- |
| 11200101 | Count of watchers is over limit. |
| 11200102 | Count of watch rules is over limit. |
**示例：**
```js
......@@ -213,7 +252,7 @@ try {
## hiSysEvent.removeWatcher
removeWatcher(watcher: Watcher): number
removeWatcher(watcher: Watcher): void
取消订阅系统事件，接收[Watcher](#watcher)类型的对象作为事件参数。
......@@ -224,9 +263,17 @@ removeWatcher(watcher: Watcher): number
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------- | ---- | ------------------------ |
| ------ | ------------- | ---- | ------------------------- |
| watcher | [Watcher](#watcher) | 是 | 系统事件订阅者对象。 |
**错误码：**
以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。
| 错误码ID | 错误信息 |
| -------- | --------------------------- |
| 11200201 | The watcher does not exist. |
**示例：**
```js
......@@ -247,7 +294,7 @@ let watcher = {
}
}
try {
let ret = hiSysEvent.addWatcher(watcher)
hiSysEvent.addWatcher(watcher)
hiSysEvent.removeWatcher(watcher)
} catch (error) {
console.error(`error code: ${error.code}, error msg: ${error.message}`);
......@@ -290,7 +337,7 @@ try {
## hiSysEvent.query
query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): number
query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void
查询系统事件。
......@@ -306,6 +353,17 @@ query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): number
| rules | [QueryRule](#queryrule)[] | 是 | 查询规则数组，每次查询可配置多个查询规则。 |
| querier | [Querier](#querier) | 是 | 查询者对象，包含查询结果及结束的相关回调。 |
**错误码：**
以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。
| 错误码ID | 错误信息 |
| -------- | ------------------------------------------- |
| 11200301 | Count of query rules is over limit. |
| 11200302 | Invalid query rule. |
| 11200303 | Count of concurrent queriers is over limit. |
| 11200304 | Query frequency is over limit. |
**示例：**
```js
......
zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md
浏览文件 @ 5eb8abc0
......@@ -12,22 +12,6 @@
import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent';
```
## 使用说明
开发者在使用应用事件打点功能前，需要首先了解应用事件相关的使用规格。
**事件打点回调**
开发者在调用事件打点方法时，可以在回调函数中对打点结果进行处理，当前支持callback形式和Promise形式的回调。
**事件订阅回调**
开发者在调用事件订阅方法时，可以在订阅回调函数中对订阅数据进行处理，其入参定义如下：
- curRow：返回的订阅事件数量；
- curSize：返回的订阅事件数据大小，单位为byte；
- holder：返回的订阅事件数据持有者，可以通过其对订阅事件进行处理。
## hiAppEvent.write
write(info: [AppEventInfo](#appeventinfo), callback: AsyncCallback&lt;void&gt;): void
......@@ -41,7 +25,7 @@ write(info: [AppEventInfo](#appeventinfo), callback: AsyncCallback&lt;void&gt;):
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------ | ---- | -------------- |
| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 |
| callback | AsyncCallback&lt;void&gt; | 否 | 事件回调函数。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 打点回调函数。 |
**错误码：**
......@@ -93,9 +77,9 @@ write(info: [AppEventInfo](#appeventinfo)): Promise&lt;void&gt;
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------------------------------------------ |
| Promise&lt;void&gt; | Promise对象，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行异步处理。 |
| 类型 | 说明 |
| ------------------- | ------------- |
| Promise&lt;void&gt; | Promise对象。 |
**错误码：**
......@@ -144,9 +128,9 @@ hiAppEvent.write({
## hiAppEvent.configure
configure(config: ConfigOption): void
configure(config: [ConfigOption](configoption)): void
应用事件打点配置方法，可用于配置打点开关、文件目录存储限额大小等功能。
应用事件打点配置方法，可用于配置打点开关、目录存储配额大小等功能。
**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
......@@ -167,12 +151,12 @@ configure(config: ConfigOption): void
**示例：**
```js
// 配置应用事件打点功能开关
// 配置打点开关为关闭状态
hiAppEvent.configure({
disable: true
});
// 配置事件文件目录存储限额大小
// 配置文件目录存储配额为100M
hiAppEvent.configure({
maxStorage: '100M'
});
......@@ -180,20 +164,20 @@ hiAppEvent.configure({
## ConfigOption
此接口提供了应用事件打点的配置选项。
此接口提供了对应用事件打点功能的配置选项。
**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------- | ---- | ------------------------------------------------------------ |
| disable | boolean | 否 | 应用事件打点功能开关。配置值为true表示关闭打点功能，false表示不关闭打点功能。 |
| maxStorage | string | 否 | 打点数据本地存储文件所在目录的配额大小，默认限额为“10M”。所在目录大小超出限额后会对目录进行清理操作，会按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出限额时停止。 |
| disable | boolean | 否 | 打点功能开关，默认值为false。true：关闭打点功能，false：不关闭打点功能。 |
| maxStorage | string | 否 | 打点数据存放目录的配额大小，默认值为“10M”。<br>在目录大小超出配额后，下次打点会触发对目录的清理操作：按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出配额时结束。 |
## hiAppEvent.addWatcher
addWatcher(watcher: [Watcher](#watcher)): [AppEventPackageHolder](#appeventpackageholder)
添加应用事件订阅者。
添加应用事件观察者方法，可用于订阅应用事件。
**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
......@@ -201,7 +185,7 @@ addWatcher(watcher: [Watcher](#watcher)): [AppEventPackageHolder](#appeventpacka
| 参数名 | 类型 | 必填 | 说明 |
| ------- | -------------------- | ---- | ---------------- |
| watcher | [Watcher](#watcher) | 是 | 应用事件订阅者。 |
| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 |
**返回值：**
......@@ -224,12 +208,12 @@ addWatcher(watcher: [Watcher](#watcher)): [AppEventPackageHolder](#appeventpacka
**示例：**
```js
// 1. 如果订阅者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理
// 1. 如果观察者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理
hiAppEvent.addWatcher({
name: "watcher1",
appEventFilters: [
{
domain: "domain_test1",
domain: "test_domain",
eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR]
}
],
......@@ -255,7 +239,7 @@ hiAppEvent.addWatcher({
}
});
// 2. 如果订阅者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件
// 2. 如果观察者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件
let holder = hiAppEvent.addWatcher({
name: "watcher2",
});
......@@ -276,7 +260,7 @@ if (holder != null) {
removeWatcher(watcher: [Watcher](#watcher)): void
移除应用事件订阅者。
移除应用事件观察者方法，可用于取消订阅应用事件。
**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
......@@ -284,7 +268,7 @@ removeWatcher(watcher: [Watcher](#watcher)): void
| 参数名 | 类型 | 必填 | 说明 |
| ------- | -------------------- | ---- | ---------------- |
| watcher | [Watcher](#watcher) | 是 | 应用事件订阅者。 |
| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 |
**错误码：**
......@@ -297,46 +281,46 @@ removeWatcher(watcher: [Watcher](#watcher)): void
**示例：**
```js
// 1. 定义一个应用事件订阅者
// 1. 定义一个应用事件观察者
let watcher = {
name: "watcher1",
}
// 2. 开始订阅事件
// 2. 添加一个应用事件观察者来订阅事件
hiAppEvent.addWatcher(watcher);
// 3. 取消订阅事件
// 3. 移除该应用事件观察者以取消订阅事件
hiAppEvent.removeWatcher(watcher);
```
## Watcher
此接口提供了应用事件订阅者的参数选项。
此接口提供了应用事件观察者的参数选项。
**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
| 名称 | 参数类型 | 必填 | 说明 |
| ---------------- | ------------------------------------------------------------ | ---- | -------------------------------- |
| name | string | 是 | 订阅者名称，用于唯一标识订阅者。 |
| triggerCondition | [TriggerCondition](#triggercondition) | 否 | 订阅回调触发条件。 |
| appEventFilters | [AppEventFilter](#appeventfilter)[] | 否 | 订阅过滤条件。 |
| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | 否 | 订阅回调函数 。 |
| 名称 | 参数类型 | 必填 | 说明 |
| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| name | string | 是 | 观察者名称，用于唯一标识观察者。 |
| triggerCondition | [TriggerCondition](#triggercondition) | 否 | 订阅回调触发条件，需要与回调函数一同传入才会生效。 |
| appEventFilters | [AppEventFilter](#appeventfilter)[] | 否 | 订阅过滤条件，在需要对订阅事件进行过滤时传入。 |
| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | 否 | 订阅回调函数，需要与回调触发条件一同传入才会生效，函数入参说明如下：<br>curRow：在本次回调触发时的订阅事件总数量； <br>curSize：在本次回调触发时的订阅事件总大小，单位为byte； <br/>holder：订阅数据持有者对象，可以通过其对订阅事件进行处理。 |
## TriggerCondition
此接口提供了订阅者回调触发条件的参数选项。
此接口提供了回调触发条件的参数选项，只要满足任一条件就会触发订阅回调。
**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
| 名称 | 参数类型 | 必填 | 说明 |
| ------- | -------- | ---- | -------------------------------------- |
| row | number | 否 | 满足触发回调的事件总数。 |
| row | number | 否 | 满足触发回调的事件总数量。 |
| size | number | 否 | 满足触发回调的事件总大小，单位为byte。 |
| timeOut | number | 否 | 满足触发回调的定时时长，单位为30s。 |
| timeOut | number | 否 | 满足触发回调的超时时长，单位为30s。 |
## AppEventFilter
此接口提供了订阅者过滤应用事件的参数选项。
此接口提供了过滤应用事件的参数选项。
**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
......@@ -353,12 +337,18 @@ hiAppEvent.removeWatcher(watcher);
### constructor
constructor(watcherName: string);
constructor(watcherName: string)
类构造函数，在添加订阅时会被系统自动调用来创建一个订阅数据持有者对象并返回给开发者。
类构造函数，在添加应用事件观察者时，会由系统自动调用来创建一个该观察者对应的订阅数据持有者对象，并返回给开发者。
**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ----------------- | ---- | ------------------------ |
| watcherName | string | 是 | 观察者名称。 |
**示例：**
```js
......@@ -371,10 +361,16 @@ let holder = hiAppEvent.addWatcher({
setSize(size: number): void
设置每次取出的应用事件包的数据大小阈值，单位为byte，默认值为512*1024。
设置每次取出的应用事件包的数据大小阈值。
**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------------- |
| size | number | 是 | 数据大小阈值，单位为byte，默认值为512*1024。 |
**错误码：**
以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。
......@@ -419,7 +415,7 @@ let eventPkg = holder.takeNext();
| --------- | -------- | ------------------------------ |
| packageId | number | 事件包ID，从0开始自动递增。 |
| row | number | 事件包的事件数量。 |
| size | number | 事件包的数据大小，单位为byte。 |
| size | number | 事件包的事件大小，单位为byte。 |
| data | string[] | 事件包的事件信息。 |
## hiAppEvent.clearData
......
zh-cn/application-dev/reference/apis/js-apis-huks.md
浏览文件 @ 5eb8abc0
因为 它太大了无法显示 source diff 。你可以改为 查看blob。
zh-cn/application-dev/reference/apis/js-apis-osAccount.md
浏览文件 @ 5eb8abc0
因为 它太大了无法显示 source diff 。你可以改为 查看blob。
zh-cn/application-dev/reference/apis/js-apis-request.md
浏览文件 @ 5eb8abc0
......@@ -33,6 +33,7 @@ var config = {
在开发stage模型下的应用程序时，不涉及属性标识 "cleartextTraffic"。
下载服务器需要支持http协议的header方法，能够通过content-length获取下载数据大小，否则下载任务失败，可通过[on('fail')<sup>7+</sup>)](#onfail7)查看失败原因。
## 常量
......@@ -53,6 +54,8 @@ var config = {
| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | 是 | 否 | 存储空间不足。 |
| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | 是 | 否 | 网络重定向过多导致的错误。 |
| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | 是 | 否 | 无法识别的HTTP代码。 |
| ERROR_OFFLINE<sup>9+</sup> | number | 是 | 否 | 网络未连接。 |
| ERROR_UNSUPPORTED_NETWORK_TYPE<sup>9+</sup> | number | 是 | 否 | 网络类型不匹配。 |
| ERROR_UNKNOWN<sup>7+</sup> | number | 是 | 否 | 未知错误。 |
| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | 是 | 否 | 下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。 |
| PAUSED_UNKNOWN<sup>7+</sup> | number | 是 | 否 | 未知原因导致暂停下载。 |
......@@ -73,6 +76,8 @@ upload(config: UploadConfig): Promise&lt;UploadTask&gt;
此接口仅可在FA模型下使用
> **说明：** 从API Version 9开始废弃，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
......@@ -116,6 +121,8 @@ upload(config: UploadConfig, callback: AsyncCallback&lt;UploadTask&gt;): void
此接口仅可在FA模型下使用
> **说明：** 从API Version 9开始废弃，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9-1)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
......@@ -152,6 +159,8 @@ upload(context: BaseContext, config: UploadConfig): Promise&lt;UploadTask&gt;
上传，异步方法，使用promise形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
......@@ -195,6 +204,8 @@ upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback&lt;Up
上传，异步方法，使用callback形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9-1)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
......@@ -227,6 +238,103 @@ upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback&lt;Up
});
```
## request.uploadFile<sup>9+</sup>
uploadFile(context: BaseContext, config: UploadConfig): Promise&lt;UploadTask&gt;
上传，异步方法，使用promise形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| context | BaseContext | 是 | 基于应用程序的上下文。 |
| config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;[UploadTask](#uploadtask)&gt; | 返回上传任务。 |
**错误码：**
以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcodes-request.md)。
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 13400002 | Bad file path. |
**示例：**
```js
let uploadTask;
let uploadConfig = {
url: 'https://patch',
header: { key1: "value1", key2: "value2" },
method: "POST",
files: { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" },
data: { name: "name123", value: "123" },
};
request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => {
uploadTask = data;
}).catch((err) => {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
});
```
## request.uploadFile<sup>9+</sup>
uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback&lt;UploadTask&gt;): void
上传，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| context | BaseContext | 是 | 基于应用程序的上下文。 |
| config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 |
| callback | AsyncCallback&lt;[UploadTask](#uploadtask)&gt; | 否 | 回调函数，异步返回UploadTask对象。 |
**错误码：**
以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcodes-request.md)。
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 13400002 | Bad file path. |
**示例：**
```js
let uploadTask;
let uploadConfig = {
url: 'https://patch',
header: { key1: "value1", key2: "value2" },
method: "POST",
files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
data: [{ name: "name123", value: "123" }],
};
request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => {
if (err) {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
return;
}
uploadTask = data;
});
```
## UploadTask
上传任务，使用下列方法前，需要先获取UploadTask对象。
......@@ -455,6 +563,8 @@ remove(): Promise&lt;boolean&gt;
移除上传的任务，异步方法，使用promise形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[delete<sup>9+</sup>](#delete9)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
......@@ -486,6 +596,8 @@ remove(callback: AsyncCallback&lt;boolean&gt;): void
移除上传的任务，异步方法，使用callback形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[delete<sup>9+</sup>](#delete9-1)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
......@@ -513,6 +625,70 @@ remove(callback: AsyncCallback&lt;boolean&gt;): void
```
### delete<sup>9+</sup>
delete(): Promise&lt;boolean&gt;
移除上传的任务，异步方法，使用promise形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;boolean&gt; | 移除任务是否成功。true：成功，false：不成功。 |
**示例：**
```js
uploadTask.delete().then((result) => {
if (result) {
console.info('Upload task removed successfully. ');
} else {
console.error('Failed to remove the upload task. ');
}
}).catch((err) => {
console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
});
```
### delete<sup>9+</sup>
delete(callback: AsyncCallback&lt;boolean&gt;): void
移除上传的任务，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Upload
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 移除任务的回调函数。 |
**示例：**
```js
uploadTask.delete((err, result) => {
if (err) {
console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
return;
}
if (result) {
console.info('Upload task removed successfully.');
} else {
console.error('Failed to remove the upload task.');
}
});
```
## UploadConfig
**需要权限**：ohos.permission.INTERNET
......@@ -543,21 +719,21 @@ remove(callback: AsyncCallback&lt;boolean&gt;): void
**需要权限**：ohos.permission.INTERNET
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
| 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| filename | string | 否 | multipart提交时，请求头中的文件名。 |
| name | string | 否 | multipart提交时，表单项目的名称，缺省为file。 |
| filename | string | 是 | multipart提交时，请求头中的文件名。 |
| name | string | 是 | multipart提交时，表单项目的名称，缺省为file。 |
| uri | string | 是 | 文件的本地存储路径。<br/>支持“dataability”和“internal”两种协议类型，但“internal”仅支持临时目录，示例：<br/>dataability:///com.domainname.dataability.persondata/person/10/file.txt<br/>internal://cache/path/to/file.txt |
| type | string | 否 | 文件的内容类型，默认根据文件名或路径的后缀获取。 |
| type | string | 是 | 文件的内容类型，默认根据文件名或路径的后缀获取。 |
## RequestData
**需要权限**：ohos.permission.INTERNET
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
| 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
......@@ -571,6 +747,8 @@ download(config: DownloadConfig): Promise&lt;DownloadTask&gt;
下载，异步方法，使用promise形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)替代。
此接口仅可在FA模型下使用
**需要权限**：ohos.permission.INTERNET
......@@ -607,6 +785,8 @@ download(config: DownloadConfig, callback: AsyncCallback&lt;DownloadTask&gt;): v
下载，异步方法，使用callback形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)替代。
此接口仅可在FA模型下使用
**需要权限**：ohos.permission.INTERNET
......@@ -640,6 +820,8 @@ download(context: BaseContext, config: DownloadConfig): Promise&lt;DownloadTask&
下载，异步方法，使用promise形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -675,6 +857,8 @@ download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback&l
下载，异步方法，使用callback形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -700,6 +884,94 @@ download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback&l
downloadTask = data;
});
```
## request.downloadFile<sup>9+</sup>
downloadFile(context: BaseContext, config: DownloadConfig): Promise&lt;DownloadTask&gt;
下载，异步方法，使用promise形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| context | BaseContext | 是 | 基于应用程序的上下文。 |
| config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;[DownloadTask](#downloadtask)&gt; | 返回下载任务。 |
**错误码：**
以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcodes-request.md)。
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 13400001 | File operation error. |
| 13400002 | Bad file path. |
| 13400003 | Task manager service error. |
**示例：**
```js
let downloadTask;
request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => {
downloadTask = data;
}).catch((err) => {
console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
})
```
## request.downloadFile<sup>9+</sup>
downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback&lt;DownloadTask&gt;): void;
下载，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| context | BaseContext | 是 | 基于应用程序的上下文。 |
| config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 |
| callback | AsyncCallback&lt;[DownloadTask](#downloadtask)&gt; | 否 | 下载接口的回调函数。 |
**错误码：**
以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcodes-request.md)。
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 13400001 | File operation error. |
| 13400002 | Bad file path. |
| 13400003 | Task manager service error. |
**示例：**
```js
let downloadTask;
request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap',
filePath: 'xxx/xxxxx.hap'}, (err, data) => {
if (err) {
console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
return;
}
downloadTask = data;
});
```
## DownloadTask
下载任务。
......@@ -899,6 +1171,8 @@ remove(): Promise&lt;boolean&gt;
移除下载的任务，异步方法，使用promise形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[delete<sup>9+</sup>](#delete9-2)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -930,6 +1204,8 @@ remove(callback: AsyncCallback&lt;boolean&gt;): void
移除下载的任务，异步方法，使用callback形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[delete<sup>9+</sup>](#delete9-3)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -963,6 +1239,8 @@ query(): Promise&lt;DownloadInfo&gt;
查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。
> **说明：** 从API Version 9开始废弃，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -989,6 +1267,8 @@ query(callback: AsyncCallback&lt;DownloadInfo&gt;): void
查询下载的任务，异步方法，使用callback形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9-1)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -1018,6 +1298,8 @@ queryMimeType(): Promise&lt;string&gt;
查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -1045,6 +1327,8 @@ queryMimeType(callback: AsyncCallback&lt;string&gt;): void;
查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9-1)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -1074,6 +1358,8 @@ pause(): Promise&lt;void&gt;
暂停下载任务，异步方法，使用promise形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[suspend<sup>9+</sup>](#suspend9)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -1103,6 +1389,8 @@ pause(): Promise&lt;void&gt;
pause(callback: AsyncCallback&lt;void&gt;): void
> **说明：** 从API Version 9开始废弃，建议使用[suspend<sup>9+</sup>](#suspend9-1)替代。
暂停下载任务，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
......@@ -1138,6 +1426,8 @@ resume(): Promise&lt;void&gt;
重新启动暂停的下载任务，异步方法，使用promise形式返回结果。
> **说明：** 从API Version 9开始废弃，建议使用[restore<sup>9+</sup>](#restore9)替代。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
......@@ -1168,6 +1458,8 @@ resume(): Promise&lt;void&gt;
resume(callback: AsyncCallback&lt;void&gt;): void
> **说明：** 从API Version 9开始废弃，建议使用[restore<sup>9+</sup>](#restore9-1)替代。
重新启动暂停的下载任务，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
......@@ -1197,6 +1489,310 @@ resume(callback: AsyncCallback&lt;void&gt;): void
```
### delete<sup>9+</sup>
delete(): Promise&lt;boolean&gt;
移除下载的任务，异步方法，使用promise形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;boolean&gt; | 移除任务是否成功。 |
**示例：**
```js
downloadTask.delete().then((result) => {
if (result) {
console.info('Download task removed.');
} else {
console.error('Failed to remove the download task.');
}
}).catch ((err) => {
console.error('Failed to remove the download task.');
});
```
### delete<sup>9+</sup>
delete(callback: AsyncCallback&lt;boolean&gt;): void
移除下载的任务，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 移除任务是否成功。 |
**示例：**
```js
downloadTask.delete((err, result)=>{
if(err) {
console.error('Failed to remove the download task.');
return;
}
if (result) {
console.info('Download task removed.');
} else {
console.error('Failed to remove the download task.');
}
});
```
### getTaskInfo<sup>9+</sup>
getTaskInfo(): Promise&lt;DownloadInfo&gt;
查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**参数：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;[DownloadInfo](#downloadinfo7)&gt; | 查询下载任务信息。 |
**示例：**
```js
downloadTask.getTaskInfo().then((downloadInfo) => {
console.info('Download task queried. Data:' + JSON.stringify(downloadInfo))
}) .catch((err) => {
console.error('Failed to query the download task. Cause:' + err)
});
```
### getTaskInfo<sup>9+</sup>
query(callback: AsyncCallback&lt;DownloadInfo&gt;): void
查询下载的任务，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[DownloadInfo](#downloadinfo7)&gt; | 是 | 查询下载任务的回调函数。 |
**示例：**
```js
downloadTask.getTaskInfo((err, downloadInfo)=>{
if(err) {
console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
} else {
console.info('download query success. data:'+ JSON.stringify(downloadInfo));
}
});
```
### getTaskMimeType<sup>9+</sup>
getTaskMimeType(): Promise&lt;string&gt;
查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;string&gt; | 查询下载任务的MimeType。 |
**示例：**
```js
downloadTask.getTaskMimeType().then((data) => {
console.info('Download task queried. Data:' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err))
});
```
### getTaskMimeType<sup>9+</sup>
getTaskMimeType(callback: AsyncCallback&lt;string&gt;): void;
查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | 是 | 查询下载任务的MimeType的回调函数。 |
**示例：**
```js
downloadTask.getTaskMimeType((err, data)=>{
if(err) {
console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
} else {
console.info('Download task queried. data:' + JSON.stringify(data));
}
});
```
### suspend<sup>9+</sup>
suspend(): Promise&lt;void&gt;
暂停下载任务，异步方法，使用promise形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | 暂停下载任务是否成功。 |
**示例：**
```js
downloadTask.suspend().then((result) => {
if (result) {
console.info('Download task paused. ');
} else {
console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
}
}).catch((err) => {
console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
});
```
### suspend<sup>9+</sup>
suspend(callback: AsyncCallback&lt;void&gt;): void
暂停下载任务，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | 是 | 暂停下载任务的回调函数。 |
**示例：**
```js
downloadTask.suspend((err, result)=>{
if(err) {
console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
return;
}
if (result) {
console.info('Download task paused. ');
} else {
console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
}
});
```
### restore<sup>9+</sup>
restore(): Promise&lt;void&gt;
重新启动暂停的下载任务，异步方法，使用promise形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**参数：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | 重新启动暂停的下载任务是否成功。 |
**示例：**
```js
downloadTask.restore().then((result) => {
if (result) {
console.info('Download task resumed.')
} else {
console.error('Failed to resume the download task. ');
}
console.info('Download task resumed.')
}).catch((err) => {
console.error('Failed to resume the download task. Cause:' + err);
});
```
### restore<sup>9+</sup>
restore(callback: AsyncCallback&lt;void&gt;): void
重新启动暂停的下载任务，异步方法，使用callback形式返回结果。
**需要权限**：ohos.permission.INTERNET
**系统能力**: SystemCapability.MiscServices.Download
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | 是 | 重新启动暂停的下载任务的回调函数。 |
**示例：**
```js
downloadTask.restore((err, result)=>{
if (err) {
console.error('Failed to resume the download task. Cause:' + err);
return;
}
if (result) {
console.info('Download task resumed.');
} else {
console.error('Failed to resume the download task.');
}
});
```
## DownloadConfig
**需要权限**：ohos.permission.INTERNET
......
zh-cn/application-dev/reference/apis/js-apis-usb-deprecated.md 0 → 100644
浏览文件 @ 5eb8abc0
# USB管理
本模块主要提供管理USB设备的相关功能，包括查询USB设备列表、批量数据传输、控制命令传输、权限控制等。
> **说明：**
>
> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
>
> 从API version 9开始，该接口不再维护，推荐使用新接口[`@ohos.usbV9`](js-apis-usb.md)。
## 导入模块
```js
import usb from "@ohos.usb";
```
## usb.getDevices
getDevices(): Array&lt;Readonly&lt;USBDevice&gt;&gt;
获取USB设备列表。
**系统能力：** SystemCapability.USB.USBManager
**返回值：**
| 类型 | 说明 |
| ---------------------------------------------------- | ------- |
| Array&lt;Readonly&lt;[USBDevice](#usbdevice)&gt;&gt; | 设备信息列表。 |
**示例：**
```js
let devicesList = usb.getDevices();
console.log(`devicesList = ${JSON.stringify(devicesList)}`);
//devicesList 返回的数据结构
//此处提供一个简单的示例，如下
[
{
name: "1-1",
serial: "",
manufacturerName: "",
productName: "",
version: "",
vendorId: 7531,
productId: 2,
clazz: 9,
subclass: 0,
protocol: 1,
devAddress: 1,
busNum: 1,
configs: [
{
id: 1,
attributes: 224,
isRemoteWakeup: true,
isSelfPowered: true,
maxPower: 0,
name: "1-1",
interfaces: [
{
id: 0,
protocol: 0,
clazz: 9,
subclass: 0,
alternateSetting: 0,
name: "1-1",
endpoints: [
{
address: 129,
attributes: 3,
interval: 12,
maxPacketSize: 4,
direction: 128,
number: 1,
type: 3,
interfaceId: 0,
},
],
},
],
},
],
},
]
```
## usb.connectDevice
connectDevice(device: USBDevice): Readonly&lt;USBDevicePipe&gt;
打开USB设备。
需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)获取设备请求权限。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| device | [USBDevice](#usbdevice) | 是 | USB设备信息。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Readonly&lt;[USBDevicePipe](#usbdevicepipe)&gt; | 指定的传输通道对象。 |
**示例：**
```js
let devicepipe= usb.connectDevice(device);
console.log(`devicepipe = ${JSON.stringify(devicepipe)}`);
```
## usb.hasRight
hasRight(deviceName: string): boolean
判断是否有权访问该设备。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| deviceName | string | 是 | 设备名称。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| boolean | true表示有访问设备的权限，false表示没有访问设备的权限。 |
**示例：**
```js
let devicesName="1-1";
let bool = usb.hasRight(devicesName);
console.log(bool);
```
## usb.requestRight
requestRight(deviceName: string): Promise&lt;boolean&gt;
请求软件包的临时权限以访问设备。使用Promise异步回调。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| deviceName | string | 是 | 设备名称。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise对象，返回临时权限的申请结果。返回true表示临时权限申请成功；返回false则表示临时权限申请失败。 |
**示例：**
```js
let devicesName="1-1";
usb.requestRight(devicesName).then((ret) => {
console.log(`requestRight = ${JSON.stringify(ret)}`);
});
```
## usb.claimInterface
claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number
注册通信接口。
需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要获取接口的索引。 |
| force | boolean | 否 | 可选参数，是否强制获取。默认值为false&nbsp;，表示不强制获取。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| number | 注册通信接口成功返回0；注册通信接口失败返回其他错误码。 |
**示例：**
```js
let ret = usb.claimInterface(devicepipe, interfaces);
console.log(`claimInterface = ${ret}`);
```
## usb.releaseInterface
releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number
释放注册过的通信接口。
需要调用[usb.claimInterface](#usbclaiminterface)先获取接口，才能使用此方法释放接口。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要释放接口的索引。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| number | 释放接口成功返回0；释放接口失败返回其他错误码。 |
**示例：**
```js
let ret = usb.releaseInterface(devicepipe, interfaces);
console.log(`releaseInterface = ${ret}`);
```
## usb.setConfiguration
setConfiguration(pipe: USBDevicePipe, config: USBConfig): number
设置设备配置。
需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及config；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
| config | [USBConfig](#usbconfig) | 是 | 用于确定需要设置的配置。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| number | 设置设备配置成功返回0；设置设备配置失败返回其他错误码。 |
**示例：**
```js
let ret = usb.setConfiguration(devicepipe, config);
console.log(`setConfiguration = ${ret}`);
```
## usb.setInterface
setInterface(pipe: USBDevicePipe, iface: USBInterface): number
设置设备接口。
需要调用[usb.getDevices](#usbgetdevices)获取设备列表以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数；调用[usb.claimInterface](#usbclaiminterface)注册通信接口。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----- | ------------------------------- | --- | ------------- |
| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要设置的接口。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| number | 设置设备接口成功返回0；设置设备接口失败返回其他错误码。 |
**示例：**
```js
let ret = usb.setInterface(devicepipe, interfaces);
console.log(`setInterface = ${ret}`);
```
## usb.getRawDescriptor
getRawDescriptor(pipe: USBDevicePipe): Uint8Array
获取原始的USB描述符。
需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Uint8Array | 返回获取的原始数据；失败返回undefined。 |
**示例：**
```js
let ret = usb.getRawDescriptor(devicepipe);
```
## usb.getFileDescriptor
getFileDescriptor(pipe: USBDevicePipe): number
获取文件描述符。
需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
**返回值：**
| 类型 | 说明 |
| ------ | -------------------- |
| number | 返回设备对应的文件描述符；失败返回-1。 |
**示例：**
```js
let ret = usb.getFileDescriptor(devicepipe);
```
## usb.controlTransfer
controlTransfer(pipe: USBDevicePipe, contrlparam: USBControlParams, timeout?: number): Promise&lt;number&gt;
控制传输。
需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 |
| contrlparam | [USBControlParams](#usbcontrolparams) | 是 | 控制传输参数。 |
| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;number&gt; | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 |
**示例：**
```js
usb.controlTransfer(devicepipe, USBControlParams).then((ret) => {
console.log(`controlTransfer = ${JSON.stringify(ret)}`);
})
```
## usb.bulkTransfer
bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout?: number): Promise&lt;number&gt;
批量传输。
需要调用[usb.getDevices](#usbgetdevices)获取设备信息列表以及endpoint；再调用[usb.requestRight](#usbrequestright)获取设备请求权限；然后调用[usb.connectDevice](#usbconnectdevice)接口得到返回数据devicepipe之后，再次获取接口[usb.claimInterface](#usbclaiminterface)；再调用usb.bulkTransfer接口。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 |
| endpoint | [USBEndpoint](#usbendpoint) | 是 | 用于确定传输的端口。 |
| buffer | Uint8Array | 是 | 用于写入或读取的缓冲区。 |
| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。|
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;number&gt; | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 |
**示例：**
```js
//usb.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限 。
//把获取到的设备对象作为参数传入usb.connectDevice;当usb.connectDevice接口成功返回之后；
//才可以调用第三个接口usb.claimInterface.当usb.claimInterface 调用成功以后,再调用该接口。
usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret) => {
console.log(`bulkTransfer = ${JSON.stringify(ret)}`);
});
```
## usb.closePipe
closePipe(pipe: USBDevicePipe): number
关闭设备消息控制通道。
需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定USB设备消息控制通道。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| number | 关闭设备消息控制通道成功返回0；关闭设备消息控制通道失败返回其他错误码。 |
**示例：**
```js
let ret = usb.closePipe(devicepipe);
console.log(`closePipe = ${ret}`);
```
## usb.usbFunctionsFromString<sup>9+</sup>
usbFunctionsFromString(funcs: string): number
在设备模式下，将字符串形式的USB功能列表转化为数字掩码。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------------- |
| funcs | string | 是 | 字符串形式的功能列表。 |
**返回值：**
| 类型 | 说明 |
| ------ | ------------------ |
| number | 转化后的数字掩码。 |
**示例：**
```js
let funcs = "acm";
let ret = usb.usbFunctionsFromString(funcs);
```
## usb.usbFunctionsToString<sup>9+</sup>
usbFunctionsToString(funcs: FunctionType): string
在设备模式下，将数字掩码形式的USB功能列表转化为字符串。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------ | ---- | ----------------- |
| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 |
**返回值：**
| 类型 | 说明 |
| ------ | ------------------------------ |
| string | 转化后的字符串形式的功能列表。 |
**示例：**
```js
let funcs = ACM | ECM;
let ret = usb.usbFunctionsToString(funcs);
```
## usb.setCurrentFunctions<sup>9+</sup>
setCurrentFunctions(funcs: FunctionType): Promise\<boolean\>
在设备模式下，设置当前的USB功能列表。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------ | ---- | ----------------- |
| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 |
**返回值：**
| 类型 | 说明 |
| ------------------ | ------------------------------------------------------------ |
| Promise\<boolean\> | Promise对象，返回设置成功与否的结果。true表示设置成功，false表示设置失败。 |
**示例：**
```js
let funcs = HDC;
let ret = usb.setCurrentFunctions(funcs);
```
## usb.getCurrentFunctions<sup>9+</sup>
getCurrentFunctions(): FunctionType
在设备模式下，获取当前的USB功能列表的数字组合掩码。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
**返回值：**
| 类型 | 说明 |
| ------------------------------ | --------------------------------- |
| [FunctionType](#functiontype9) | 当前的USB功能列表的数字组合掩码。 |
**示例：**
```js
let ret = usb.getCurrentFunctions();
```
## usb.getPorts<sup>9+</sup>
getPorts(): Array\<USBPort\>
获取所有物理USB端口描述信息。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
**返回值：**
| 类型 | 说明 |
| ----------------------------- | --------------------- |
| [Array\<USBPort\>](#usbport9) | USB端口描述信息列表。 |
**示例：**
```js
let ret = usb.getPorts();
```
## usb.getSupportedModes<sup>9+</sup>
getSupportedModes(portId: number): PortModeType
获取指定的端口支持的模式列表的组合掩码。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------- |
| portId | number | 是 | 端口号。 |
**返回值：**
| 类型 | 说明 |
| ------------------------------ | -------------------------- |
| [PortModeType](#portmodetype9) | 支持的模式列表的组合掩码。 |
**示例：**
```js
let ret = usb.getSupportedModes(0);
```
## usb.setPortRoles<sup>9+</sup>
setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<boolean\>
设置指定的端口支持的角色模式，包含充电角色、数据传输角色。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | -------------------------------- | ---- | ---------------- |
| portId | number | 是 | 端口号。 |
| powerRole | [PowerRoleType](#powerroletype9) | 是 | 充电的角色。 |
| dataRole | [DataRoleType](#dataroletype9) | 是 | 数据传输的角色。 |
**返回值：**
| 类型 | 说明 |
| ------------------ | ------------------------------------------------------------ |
| Promise\<boolean\> | Promise对象，返回设置成功与否的结果。true表示设置成功，false表示设置失败。 |
**示例：**
```js
let ret = usb.getSupportedModes(0);
```
## USBEndpoint
通过USB发送和接收数据的端口。通过[USBInterface](#usbinterface)获取。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 参数类型 | 说明 |
| ------------- | ------------------------------------------- | ------------- |
| address | number | 端点地址。 |
| attributes | number | 端点属性。 |
| interval | number | 端点间隔。 |
| maxPacketSize | number | 端点最大数据包大小。 |
| direction | [USBRequestDirection](#usbrequestdirection) | 端点的方向。 |
| number | number | 端点号。 |
| type | number | 端点类型。 |
| interfaceId | number | 端点所属的接口的唯一标识。 |
## USBInterface
一个[USBConfig](#usbconfig)中可以含有多个USBInterface，每个USBInterface提供一个功能。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 参数类型 | 说明 |
| ---------------- | ---------------------------------------- | --------------------- |
| id | number | 接口的唯一标识。 |
| protocol | number | 接口的协议。 |
| clazz | number | 设备类型。 |
| subClass | number | 设备子类。 |
| alternateSetting | number | 在同一个接口中的多个描述符中进行切换设置。 |
| name | string | 接口名称。 |
| endpoints | Array&lt;[USBEndpoint](#usbendpoint)&gt; | 当前接口所包含的端点。 |
## USBConfig
USB配置，一个[USBDevice](#usbdevice)中可以含有多个配置。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 参数类型 | 说明 |
| -------------- | ------------------------------------------------ | --------------- |
| id | number | 配置的唯一标识。 |
| attributes | number | 配置的属性。 |
| maxPower | number | 最大功耗，以毫安为单位。 |
| name | string | 配置的名称，可以为空。 |
| isRemoteWakeup | boolean | 检查当前配置是否支持远程唤醒。 |
| isSelfPowered | boolean | 检查当前配置是否支持独立电源。 |
| interfaces | Array&nbsp;&lt;[USBInterface](#usbinterface)&gt; | 配置支持的接口属性。 |
## USBDevice
USB设备信息。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 参数类型 | 说明 |
| ---------------- | ------------------------------------ | ---------- |
| busNum | number | 总线地址。 |
| devAddress | number | 设备地址。 |
| serial | string | 序列号。 |
| name | string | 设备名字。 |
| manufacturerName | string | 产商信息。 |
| productName | string | 产品信息。 |
| version | string | 版本。 |
| vendorId | number | 厂商ID。 |
| productId | number | 产品ID。 |
| clazz | number | 设备类。 |
| subClass | number | 设备子类。 |
| protocol | number | 设备协议码。 |
| configs | Array&lt;[USBConfig](#usbconfig)&gt; | 设备配置描述符信息。 |
## USBDevicePipe
USB设备消息传输通道，用于确定设备。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 参数类型 | 说明 |
| ---------- | ------ | ----- |
| busNum | number | 总线地址。 |
| devAddress | number | 设备地址。 |
## USBControlParams
控制传输参数。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 参数类型 | 说明 |
| ------- | ----------------------------------------------- | ---------------- |
| request | number | 请求类型。 |
| target | [USBRequestTargetType](#usbrequesttargettype) | 请求目标类型。 |
| reqType | [USBControlRequestType](#usbcontrolrequesttype) | 请求控制类型。 |
| value | number | 请求参数。 |
| index | number | 请求参数value对应的索引值。 |
| data | Uint8Array | 用于写入或读取的缓冲区。 |
## USBPort<sup>9+</sup>
USB设备端口。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 参数类型 | 说明 |
| -------------- | -------------------------------- | ----------------------------------- |
| id | number | USB端口唯一标识。 |
| supportedModes | [PortModeType](#portmodetype9) | USB端口所支持的模式的数字组合掩码。 |
| status | [USBPortStatus](#usbportstatus9) | USB端口角色。 |
## USBPortStatus<sup>9+</sup>
USB设备端口角色信息。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 参数类型 | 说明 |
| ---------------- | -------- | ---------------------- |
| currentMode | number | 当前的USB模式。 |
| currentPowerRole | number | 当前设备充电模式。 |
| currentDataRole | number | 当前设备数据传输模式。 |
## USBRequestTargetType
请求目标类型。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
| ---------------------------- | ---- | ------ |
| USB_REQUEST_TARGET_DEVICE | 0 | 设备。 |
| USB_REQUEST_TARGET_INTERFACE | 1 | 接口。 |
| USB_REQUEST_TARGET_ENDPOINT | 2 | 端点。 |
| USB_REQUEST_TARGET_OTHER | 3 | 其他。 |
## USBControlRequestType
控制请求类型。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
| ------------------------- | ---- | ------ |
| USB_REQUEST_TYPE_STANDARD | 0 | 标准。 |
| USB_REQUEST_TYPE_CLASS | 1 | 类。 |
| USB_REQUEST_TYPE_VENDOR | 2 | 厂商。 |
## USBRequestDirection
请求方向。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
| --------------------------- | ---- | ------------------------ |
| USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据，主设备往从设备。 |
| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 |
## FunctionType<sup>9+</sup>
USB设备侧功能。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
| ------------ | ---- | ---------- |
| NONE | 0 | 没有功能。 |
| ACM | 1 | acm功能。 |
| ECM | 2 | ecm功能。 |
| HDC | 4 | hdc功能。 |
| MTP | 8 | 暂不支持。 |
| PTP | 16 | 暂不支持。 |
| RNDIS | 32 | 暂不支持。 |
| MIDI | 64 | 暂不支持。 |
| AUDIO_SOURCE | 128 | 暂不支持。 |
| NCM | 256 | 暂不支持。 |
## PortModeType<sup>9+</sup>
USB端口模式类型。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
| --------- | ---- | ---------------------------------------------------- |
| NONE | 0 | 无。 |
| UFP | 1 | 数据上行，需要外部供电。 |
| DFP | 2 | 数据下行，对外提供电源。 |
| DRP | 3 | 既可以做DFP(Host)，也可以做UFP(Device)，当前不支持。 |
| NUM_MODES | 4 | 当前不支持。 |
## PowerRoleType<sup>9+</sup>
电源角色类型。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
| ------ | ---- | ---------- |
| NONE | 0 | 无。 |
| SOURCE | 1 | 外部供电。 |
| SINK | 2 | 内部供电。 |
## DataRoleType<sup>9+</sup>
数据角色类型。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
| 名称 | 值 | 说明 |
| ------ | ---- | ------------ |
| NONE | 0 | 无。 |
| HOST | 1 | 主设备角色。 |
| DEVICE | 2 | 从设备角色。 |
zh-cn/application-dev/reference/apis/js-apis-usb.md
浏览文件 @ 5eb8abc0
# USB管理
本模块主要提供管理USB设备的相关功能，包括查询USB设备列表、批量数据传输、控制命令传输、权限控制等。
本模块主要提供管理USB设备的相关功能，包括主设备上查询USB设备列表、批量数据传输、控制命令传输、权限控制等；从设备上端口管理、功能切换及查询等。
> **说明：**
>
> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块
```js
import usb from "@ohos.usb";
import usb from "@ohos.usbV9";
```
## usb.getDevices
getDevices(): Array&lt;Readonly&lt;USBDevice&gt;&gt;
获取USB设备列表。
获取接入主设备的USB设备列表。如果没有设备接入，那么将会返回一个空的列表。
**系统能力：** SystemCapability.USB.USBManager
......@@ -89,7 +89,7 @@ connectDevice(device: USBDevice): Readonly&lt;USBDevicePipe&gt;
打开USB设备。
需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)获取设备请求权限。
需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)请求使用该设备的权限。
**系统能力：** SystemCapability.USB.USBManager
......@@ -105,10 +105,26 @@ connectDevice(device: USBDevice): Readonly&lt;USBDevicePipe&gt;
| -------- | -------- |
| Readonly&lt;[USBDevicePipe](#usbdevicepipe)&gt; | 指定的传输通道对象。 |
**错误码：**
以下错误码的详细介绍参见[USB错误码](../errorcodes/errcode-usb.md)。
| 错误码ID | 错误信息 |
| -------- | -------- |
| 14400001 |Permission denied. Need call requestRight to get permission. |
**示例：**
```js
let devicepipe= usb.connectDevice(device);
let devicesList = usb.getDevices();
if (devicesList.length == 0) {
console.log(`device list is empty`);
return;
}
let device = devicesList[0];
usb.requestRight(device.name);
let devicepipe = usb.connectDevice(device);
console.log(`devicepipe = ${JSON.stringify(devicepipe)}`);
```
......@@ -169,6 +185,70 @@ usb.requestRight(devicesName).then((ret) => {
});
```
## usb.removeRight
removeRight(deviceName: string): boolean;
移除软件包访问设备的权限。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| deviceName | string | 是 | 设备名称。 |
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| boolean | 返回权限移除结果。返回true表示权限移除成功；返回false则表示权限移除失败。 |
**示例：**
```js
let devicesName="1-1";
if (usb.removeRight(devicesName) {
console.log(`Succeed in removing right`);
}
```
## usb.addRight
addRight(bundleName: string, deviceName: string): boolean;
添加软件包访问设备的权限。
[requestRight](#usbrequestright)的会触发弹框请求用户授权；addRight不会触发弹框，而是直接添加软件包访问设备的权限。
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.USB.USBManager
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| deviceName | string | 是 | 设备名称。 |
| bundleName | string | 是 | 软件包名称。|
**返回值：**
| 类型 | 说明 |
| -------- | -------- |
| boolean | 返回权限添加结果。返回true表示权限添加成功；返回false则表示权限添加失败。 |
**示例：**
```js
let devicesName = "1-1";
let bundleName = "com.example.hello";
if (usb.addRight(bundleName, devicesName) {
console.log(`Succeed in adding right`);
}
```
## usb.claimInterface
claimInterface(pipe: USBDevicePipe, iface: USBInterface, force?: boolean): number
......@@ -443,7 +523,7 @@ let ret = usb.closePipe(devicepipe);
console.log(`closePipe = ${ret}`);
```
## usb.usbFunctionsFromString<sup>9+</sup>
## usb.usbFunctionsFromString
usbFunctionsFromString(funcs: string): number
......@@ -472,7 +552,7 @@ let funcs = "acm";
let ret = usb.usbFunctionsFromString(funcs);
```
## usb.usbFunctionsToString<sup>9+</sup>
## usb.usbFunctionsToString
usbFunctionsToString(funcs: FunctionType): string
......@@ -486,7 +566,7 @@ usbFunctionsToString(funcs: FunctionType): string
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------ | ---- | ----------------- |
| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 |
| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 |
**返回值：**
......@@ -501,7 +581,7 @@ let funcs = ACM | ECM;
let ret = usb.usbFunctionsToString(funcs);
```
## usb.setCurrentFunctions<sup>9+</sup>
## usb.setCurrentFunctions
setCurrentFunctions(funcs: FunctionType): Promise\<boolean\>
......@@ -515,7 +595,7 @@ setCurrentFunctions(funcs: FunctionType): Promise\<boolean\>
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------ | ---- | ----------------- |
| funcs | [FunctionType](#functiontype9) | 是 | USB功能数字掩码。 |
| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 |
**返回值：**
......@@ -530,7 +610,7 @@ let funcs = HDC;
let ret = usb.setCurrentFunctions(funcs);
```
## usb.getCurrentFunctions<sup>9+</sup>
## usb.getCurrentFunctions
getCurrentFunctions(): FunctionType
......@@ -544,7 +624,7 @@ getCurrentFunctions(): FunctionType
| 类型 | 说明 |
| ------------------------------ | --------------------------------- |
| [FunctionType](#functiontype9) | 当前的USB功能列表的数字组合掩码。 |
| [FunctionType](#functiontype) | 当前的USB功能列表的数字组合掩码。 |
**示例：**
......@@ -552,7 +632,7 @@ getCurrentFunctions(): FunctionType
let ret = usb.getCurrentFunctions();
```
## usb.getPorts<sup>9+</sup>
## usb.getPorts
getPorts(): Array\<USBPort\>
......@@ -566,7 +646,7 @@ getPorts(): Array\<USBPort\>
| 类型 | 说明 |
| ----------------------------- | --------------------- |
| [Array\<USBPort\>](#usbport9) | USB端口描述信息列表。 |
| [Array\<USBPort\>](#usbport) | USB端口描述信息列表。 |
**示例：**
......@@ -574,7 +654,7 @@ getPorts(): Array\<USBPort\>
let ret = usb.getPorts();
```
## usb.getSupportedModes<sup>9+</sup>
## usb.getSupportedModes
getSupportedModes(portId: number): PortModeType
......@@ -594,7 +674,7 @@ getSupportedModes(portId: number): PortModeType
| 类型 | 说明 |
| ------------------------------ | -------------------------- |
| [PortModeType](#portmodetype9) | 支持的模式列表的组合掩码。 |
| [PortModeType](#portmodetype) | 支持的模式列表的组合掩码。 |
**示例：**
......@@ -602,7 +682,7 @@ getSupportedModes(portId: number): PortModeType
let ret = usb.getSupportedModes(0);
```
## usb.setPortRoles<sup>9+</sup>
## usb.setPortRoles
setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<boolean\>
......@@ -617,8 +697,8 @@ setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType):
| 参数名 | 类型 | 必填 | 说明 |
| --------- | -------------------------------- | ---- | ---------------- |
| portId | number | 是 | 端口号。 |
| powerRole | [PowerRoleType](#powerroletype9) | 是 | 充电的角色。 |
| dataRole | [DataRoleType](#dataroletype9) | 是 | 数据传输的角色。 |
| powerRole | [PowerRoleType](#powerroletype) | 是 | 充电的角色。 |
| dataRole | [DataRoleType](#dataroletype) | 是 | 数据传输的角色。 |
**返回值：**
......@@ -729,7 +809,7 @@ USB设备消息传输通道，用于确定设备。
| index | number | 请求参数value对应的索引值。 |
| data | Uint8Array | 用于写入或读取的缓冲区。 |
## USBPort<sup>9+</sup>
## USBPort
USB设备端口。
......@@ -740,10 +820,10 @@ USB设备端口。
| 名称 | 参数类型 | 说明 |
| -------------- | -------------------------------- | ----------------------------------- |
| id | number | USB端口唯一标识。 |
| supportedModes | [PortModeType](#portmodetype9) | USB端口所支持的模式的数字组合掩码。 |
| status | [USBPortStatus](#usbportstatus9) | USB端口角色。 |
| supportedModes | [PortModeType](#portmodetype) | USB端口所支持的模式的数字组合掩码。 |
| status | [USBPortStatus](#usbportstatus) | USB端口角色。 |
## USBPortStatus<sup>9+</sup>
## USBPortStatus
USB设备端口角色信息。
......@@ -793,7 +873,7 @@ USB设备端口角色信息。
| USB_REQUEST_DIR_TO_DEVICE | 0 | 写数据，主设备往从设备。 |
| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 |
## FunctionType<sup>9+</sup>
## FunctionType
USB设备侧功能。
......@@ -814,7 +894,7 @@ USB设备侧功能。
| AUDIO_SOURCE | 128 | 暂不支持。 |
| NCM | 256 | 暂不支持。 |
## PortModeType<sup>9+</sup>
## PortModeType
USB端口模式类型。
......@@ -830,7 +910,7 @@ USB端口模式类型。
| DRP | 3 | 既可以做DFP(Host)，也可以做UFP(Device)，当前不支持。 |
| NUM_MODES | 4 | 当前不支持。 |
## PowerRoleType<sup>9+</sup>
## PowerRoleType
电源角色类型。
......@@ -844,7 +924,7 @@ USB端口模式类型。
| SOURCE | 1 | 外部供电。 |
| SINK | 2 | 内部供电。 |
## DataRoleType<sup>9+</sup>
## DataRoleType
数据角色类型。
......
zh-cn/application-dev/reference/arkui-ts/Readme-CN.md
浏览文件 @ 5eb8abc0
......@@ -98,6 +98,7 @@
- [ColumnSplit](ts-container-columnsplit.md)
- [Counter](ts-container-counter.md)
- [Flex](ts-container-flex.md)
- [FlowItem](ts-container-flowitem.md)
- [GridContainer](ts-container-gridcontainer.md)
- [GridCol](ts-container-gridcol.md)
- [GridRow](ts-container-gridrow.md)
......@@ -118,6 +119,7 @@
- [Swiper](ts-container-swiper.md)
- [Tabs](ts-container-tabs.md)
- [TabContent](ts-container-tabcontent.md)
- [WaterFlow](ts-container-waterflow.md)
- 媒体组件
- [Video](ts-media-components-video.md)
- 绘制组件
......
zh-cn/application-dev/reference/arkui-ts/ts-container-alphabet-indexer.md
浏览文件 @ 5eb8abc0
......@@ -20,8 +20,8 @@ AlphabetIndexer(value: {arrayValue: Array&lt;string&gt;, selected: number})
| 参数名 | 参数类型 | 必填 | 参数描述 |
| -------- | -------- | -------- | -------- |
| arrayValue | Array&lt;string&gt; | 是 | 字母索引字符串数组。 |
| selected | number | 是 | 初始选中项索引值。 |
| arrayValue | Array&lt;string&gt; | 是 | 字母索引字符串数组，不可设置为空。 |
| selected | number | 是 | 初始选中项索引值，若超出索引值范围，则取默认值0。 |
## 属性
......@@ -29,19 +29,19 @@ AlphabetIndexer(value: {arrayValue: Array&lt;string&gt;, selected: number})
| 名称 | 参数类型 | 描述 |
| ----------------------- | --------------- | ----------------------------------------------------------- |
| color | [ResourceColor](ts-types.md#resourcecolor) | 设置文字颜色。 |
| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | 设置选中项文字颜色。 |
| popupColor | [ResourceColor](ts-types.md#resourcecolor) | 设置提示弹窗文字颜色。 |
| selectedBackgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 设置选中项背景颜色。 |
| popupBackground | [ResourceColor](ts-types.md#resourcecolor) | 设置提示弹窗背景色。 |
| usingPopup | boolean | 设置是否使用提示弹窗。 |
| selectedFont | [Font](ts-types.md#font) | 设置选中项文字样式。 |
| popupFont | [Font](ts-types.md#font) | 设置提示弹窗字体样式。 |
| font | [Font](ts-types.md#font) | 设置字母索引条默认字体样式。 |
| itemSize | string&nbsp;\|&nbsp;number | 设置字母索引条字母区域大小，字母区域为正方形，即正方形边长。 |
| alignStyle | IndexerAlign | 设置字母索引条弹框的对齐样式，支持弹窗显示在索引条右侧和左侧。<br/>默认值：IndexerAlign.Right |
| selected | number | 设置选中项索引值。 |
| popupPosition | [Position](ts-types.md#position8) | 设置弹出窗口相对于索引器条上边框中点的位置。 |
| color | [ResourceColor](ts-types.md#resourcecolor) | 设置文字颜色。<br/>默认值：0x99000000。 |
| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | 设置选中项文字颜色。<br/>默认值：0xFF254FF7。 |
| popupColor | [ResourceColor](ts-types.md#resourcecolor) | 设置提示弹窗文字颜色。<br/>默认值：0xFF254FF7。 |
| selectedBackgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 设置选中项背景颜色。<br/>默认值：0x1F0A59F7。 |
| popupBackground | [ResourceColor](ts-types.md#resourcecolor) | 设置提示弹窗背景色。<br/>默认值：0xFFF1F3F5。 |
| usingPopup | boolean | 设置是否使用提示弹窗。<br/>默认值：false。 |
| selectedFont | [Font](ts-types.md#font) | 设置选中项文字样式。<br/>默认值：<br/>{<br/>fontSize:10,<br/> fontStyle:FontStyle.Normal,<br/> fontWeight:FontWeight.Normal,<br/> fontFamily:HarmonyOS Sans<br/>} |
| popupFont | [Font](ts-types.md#font) | 设置提示弹窗字体样式。<br/>默认值：<br/>{<br/>fontSize:10,<br/> fontStyle:FontStyle.Normal,<br/> fontWeight:FontWeight.Normal,<br/> fontFamily:HarmonyOS Sans<br/>} |
| font | [Font](ts-types.md#font) | 设置字母索引条默认字体样式。<br/>默认值：<br/>{<br/>fontSize:10,<br/> fontStyle:FontStyle.Normal,<br/> fontWeight:FontWeight.Normal,<br/> fontFamily:HarmonyOS Sans<br/>} |
| itemSize | string&nbsp;\|&nbsp;number | 设置字母索引条字母区域大小，字母区域为正方形，即正方形边长。<br/>默认值：24.0。 |
| alignStyle | IndexerAlign | 设置字母索引条弹框的对齐样式，支持弹窗显示在索引条右侧和左侧。<br/>默认值:IndexerAlign.Right。 |
| selected | number | 设置选中项索引值。<br/>默认值：0。 |
| popupPosition | [Position](ts-types.md#position8) | 设置弹出窗口相对于索引器条上边框中点的位置。<br/>默认值：{x:96.0, y:48.0}。 |
## IndexerAlign枚举说明
......
zh-cn/application-dev/reference/arkui-ts/ts-container-flowitem.md 0 → 100644
浏览文件 @ 5eb8abc0
# FlowItem
[瀑布流组件](ts-container-waterflow.md)的子组件，用来展示瀑布流具体item。
> **说明：**
>
> 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
支持单个子组件。
## 接口
FlowItem()
使用该接口来创建瀑布流子组件。
## 属性
无
## 示例
详见[瀑布流组件示例](ts-container-waterflow.md#示例)。
\ No newline at end of file
zh-cn/application-dev/reference/arkui-ts/ts-container-waterflow.md 0 → 100644
浏览文件 @ 5eb8abc0
# WaterFlow
瀑布流容器，由“行”和“列”分割的单元格所组成，通过容器自身的排列规则，将不同大小的“项目”自上而下，如瀑布般紧密布局。
> **说明：**
>
> 该组件从API Version 9 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
## 子组件
包含[FlowItem](ts-container-flowitem.md)子组件。
## 接口
WaterFlow(options?: {footer?: CustomBuilder, scroller?: Scroller})
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| ---------- | ----------------------------------------------- | ------ | -------------------------------------------- |
| footer | [CustomBuilder](ts-types.md#custombuilder8) | 否 | 设置WaterFlow尾部组件。 |
| scroller | [Scroller](ts-container-scroll.md#scroller) | 否 | 可滚动组件的控制器，与可滚动组件绑定。 |
## 属性
除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
| 名称 | 参数类型 | 描述 |
| -------- | -------- | -------- |
| columnsTemplate | string | 设置当前瀑布流组件布局列的数量，不设置时默认1列。<br/>例如, '1fr 1fr 2fr' 是将父组件分3列，将父组件允许的宽分为4等份，第一列占1份，第二列占1份，第三列占2份。并支持[auto-fill](#auto-fill说明)。<br>默认值：'1fr' |
| rowsTemplate | string | 设置当前瀑布流组件布局行的数量，不设置时默认1行。<br/>例如, '1fr 1fr 2fr'是将父组件分三行，将父组件允许的高分为4等份，第一行占1份，第二行占一份，第三行占2份。并支持[auto-fill](#auto-fill说明)。<br/>默认值：'1fr' |
| itemConstraintSize | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 设置约束尺寸，子组件布局时，进行尺寸范围限制。 |
| columnsGap | Length |设置列与列的间距。 <br>默认值：0|
| rowsGap | Length |设置行与行的间距。<br> 默认值：0|
| layoutDirection | [FlexDirection](ts-appendix-enums.md#flexdirection) |设置布局的主轴方向。|
## 事件
除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件：
| 名称 | 功能描述 |
| -------- | -------- |
| onReachStart(event: () => void) | 瀑布流组件到达起始位置时触发。 |
| onReachEnd(event: () => void) | 瀑布流组件到底末尾位置时触发。 |
## auto-fill说明
WaterFlow的columnsTemplate、rowsTemplate属性的auto-fill仅支持以下格式：
```css
repeat(auto-fill, track-size)
```
其中repeat、auto-fill为关键字。track-size为行高或者列宽，支持的单位包括px、vp、%或有效数字，track-size至少包括一个有效行高或者列宽。
## 示例
```ts
// WaterFlowDataSource.ets
// 实现IDataSource接口的对象，用于瀑布流组件加载数据
export class WaterFlowDataSource implements IDataSource {
private dataArray: number[] = []
private listeners: DataChangeListener[] = []
constructor() {
for (let i = 0; i <= 100; i++) {
this.dataArray.push(i);
}
}
// 获取索引对应的数据
public getData(index: number): any {
return this.dataArray[index]
}
// 通知控制器数据重新加载
notifyDataReload(): void {
this.listeners.forEach(listener => {
listener.onDataReloaded()
})
}
// 通知控制器数据增加
notifyDataAdd(index: number): void {
this.listeners.forEach(listener => {
listener.onDataAdded(index)
})
}
// 通知控制器数据变化
notifyDataChange(index: number): void {
this.listeners.forEach(listener => {
listener.onDataChanged(index)
})
}
// 通知控制器数据删除
notifyDataDelete(index: number): void {
this.listeners.forEach(listener => {
listener.onDataDeleted(index)
})
}
// 通知控制器数据位置变化
notifyDataMove(from: number, to: number): void {
this.listeners.forEach(listener => {
listener.onDataMoved(from, to)
})
}
// 获取数据总数
public totalCount(): number {
return this.dataArray.length
}
// 注册改变数据的控制器
registerDataChangeListener(listener: DataChangeListener): void {
if (this.listeners.indexOf(listener) < 0) {
this.listeners.push(listener)
}
}
// 注销改变数据的控制器
unregisterDataChangeListener(listener: DataChangeListener): void {
const pos = this.listeners.indexOf(listener);
if (pos >= 0) {
this.listeners.splice(pos, 1)
}
}
// 增加数据
public Add1stItem(): void {
this.dataArray.splice(0, 0, this.dataArray.length)
this.notifyDataAdd(0)
}
// 在数据尾部增加一个元素
public AddLastItem(): void {
this.dataArray.splice(this.dataArray.length, 0, this.dataArray.length)
this.notifyDataAdd(this.dataArray.length-1)
}
// 在指定索引位置增加一个元素
public AddItem(index: number): void {
this.dataArray.splice(index, 0, this.dataArray.length)
this.notifyDataAdd(index)
}
// 删除第一个元素
public Delete1stItem(): void {
this.dataArray.splice(0, 1)
this.notifyDataDelete(0)
}
// 删除第二个元素
public Delete2ndItem(): void {
this.dataArray.splice(1, 1)
this.notifyDataDelete(1)
}
// 删除最后一个元素
public DeleteLastItem(): void {
this.dataArray.splice(-1, 1)
this.notifyDataDelete(this.dataArray.length)
}
// 重新加载数据
public Reload(): void {
this.dataArray.splice(1, 1);
this.dataArray.splice(3, 2);
this.notifyDataReload();
}
}
```
```ts
// WaterflowDemo.ets
import { WaterFlowDataSource } from './WaterFlowDataSource'
@Entry
@Component
struct WaterflowDemo {
@State minSize: number = 50
@State maxSize: number = 100
@State fontSize: number = 24
@State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F]
scroller: Scroller = new Scroller();
datasource: WaterFlowDataSource = new WaterFlowDataSource();
// 计算flow item宽/高
getSize() {
let ret = Math.floor(Math.random() * this.maxSize)
return (ret > this.minSize ? ret : this.minSize)
}
@Builder itemFoot() {
Column() {
Text(`Footer`)
.fontSize(10)
.backgroundColor(Color.Red)
.width(50)
.height(50)
.align(Alignment.Center)
.margin({ top: 2 })
}
}
build() {
Column({ space: 2 }) {
WaterFlow({ footer: this.itemFoot, scroller: this.scroller }) {
LazyForEach(this.datasource, (item: number) => {
FlowItem() {
Column() {
Text("N" + item).fontSize(12).height('16')
Image('res/waterFlowTest(' + item % 5 + ').jpg')
.objectFit(ImageFit.Fill)
}
}
.width(this.getSize())
.height(this.getSize())
.backgroundColor(this.colors[item % 5])
}, item => item)
}
.columnsTemplate("1fr 1fr 1fr 1fr")
.itemConstraintSize({
minWidth: 0,
maxWidth: '100%',
minHeight: 0,
maxHeight: '100%'
})
.columnsGap(10)
.rowsGap(5)
.onReachStart(() => {
console.info("onReachStart")
})
.onReachEnd(() => {
console.info("onReachEnd")
})
.backgroundColor(0xFAEEE0)
.width('100%')
.height('80%')
.layoutDirection(FlexDirection.Column)
}
}
}
```
![zh-cn_image_WaterFlow.gif](figures/waterflow.gif)
\ No newline at end of file
zh-cn/application-dev/reference/errorcodes/errcode-usb.md 0 → 100644
浏览文件 @ 5eb8abc0
# USB服务错误码
## 14400001 连接USB设备被拒绝
**错误信息**
Permission denied. Need call requestRight to get permission.
**错误描述**
当调用USB模块部分接口时，如果没有相关权限，会报此错误码。
**可能原因**
没有获取到设备的使用权限。
**处理步骤**
调用requestRight方法申请设备的使用权限。
\ No newline at end of file
zh-cn/application-dev/reference/errorcodes/errorcode-device-manager.md 0 → 100644
浏览文件 @ 5eb8abc0
# 设备管理错误码
## 11600101 服务调用异常
**错误信息**
Failed to execute the function.
**可能原因**
服务内部调用异常。
**处理步骤**
重新调用接口再次触发调用。
## 11600102 获取服务失败
**错误信息**
Failed to obtain the service.
**可能原因**
服务未启动或者服务启动失败。
**处理步骤**
检查服务是否正常启动，重新获取服务。
## 11600103 认证业务不可用
**错误信息**
Authentication invalid.
**可能原因**
上一次认证业务未结束。
**处理步骤**
等待上一次认证业务结束，重新发起认证调用。
## 11600104 发现业务不可用
**错误信息**
Discovery invalid.
**可能原因**
上一次发现业务未结束。
**处理步骤**
等待上一次发现业务结束，重新发起发现调用。
## 11600105 发布业务不可用
**错误信息**
Publish invalid.
**可能原因**
上一次发布业务未结束。
**处理步骤**
等待上一次发布业务结束，重新发起发布调用。
zh-cn/application-dev/reference/errorcodes/errorcode-hisysevent.md 0 → 100644
浏览文件 @ 5eb8abc0
# 系统事件错误码
## 1120001 非法的事件领域
**错误信息**
Invalid event domain.
**错误描述**
在调用write接口进行系统事件打点时，由于传入了非法的事件领域名称，系统将忽略此次系统事件打点。
**可能原因**
1.系统事件领域名称长度超过16个字符；
2.系统事件领域名称包含特殊字符；
3.系统事件领域名称为空。
**处理步骤**
检查系统事件领域名称是否合法。
## 1120002 非法的事件名称
**错误信息**
Invalid event name.
**错误描述**
在调用write接口进行系统事件打点时，由于传入了非法的事件名称，系统将忽略此次系统事件打点。
**可能原因**
1.系统事件名称长度超过32个字符；
2.系统事件名称包含特殊字符；
3.系统事件名称为空。
**处理步骤**
检查系统事件名称是否合法。
## 11200003 环境异常
**错误信息**
Abnormal environment.
**错误描述**
在调用write接口进行系统事件打点时，由于环境异常，系统将忽略此次系统事件打点。
**可能原因**
1.hiview服务未成功启动；
2.hiview服务socket异常。
**处理步骤**
尝试重新调用write接口进行打点。
## 11200004 事件长度超过限制
**错误信息**
Length of the event is over limit.
**错误描述**
在调用write接口进行系统事件打点时，由于传入的事件总长度超过限制，系统将忽略此次系统事件打点。
**可能原因**
系统事件总长度超过384K。
**处理步骤**
检查系统事件总长度是否大于384K。
## 11200051 非法的事件参数
**错误信息**
Invalid event parameter.
**错误描述**
在调用write接口进行系统事件打点时，由于传入了非法的参数名称，系统将忽略此次系统事件打点。
**可能原因**
1.系统事件参数名称长度超过32个字符；
2.系统事件参数名称包含特殊字符；
3.系统事件参数名为空。
**处理步骤**
检查系统事件参数名称是否合法。
## 11200052 字符串类型的事件参数值的长度超过限制
**错误信息**
Size of the event parameter of the string type is over limit.
**错误描述**
在调用write接口进行系统事件打点时，由于传入了长度超限的字符串类型参数，系统将忽略此次系统事件打点。
**可能原因**
字符串类型的参数值的长度超过256K。
**处理步骤**
检查系统事件中字符串类型的参数值的长度是否超过256K。
## 11200053 事件参数的数量超过限制
**错误信息**
Count of event parameters is over limit.
**错误描述**
在调用write接口进行系统事件打点时，由于传入的事件参数数量超过限制，系统将将忽略此次系统事件打点。
**可能原因**
系统事件的参数数量超过128个。
**处理步骤**
检查系统事件的参数数量是否超过了128个。
## 11200054 数组类型的事件参数值的长度超过限制
**错误信息**
Count of event parameter of the array type is over limit.
**错误描述**
在调用write接口进行系统事件打点时，由于传入了长度超过限制的数组类型的参数，系统将忽略此次系统事件打点。
**可能原因**
系统事件中有数组类型的参数值的长度超过100。
**处理步骤**
检查数组类型的参数值的长度是否超过100.
## 11200101 事件监听者的数量超过限制
**错误信息**
Count of watchers is over limit.
**错误描述**
在调用addWatcher接口添加系统事件监听者时，由于添加的监听者数量超过限制，系统将拒绝此系统事件监听者的添加。
**可能原因**
hiview服务已添加30个系统事件监听者，无法添加新的系统事件监听者。
**处理步骤**
检查已成功添加的系统事件监听者数量是否超过了30个。
## 11200102 事件监听者包含的监听规则数量超过限制
**错误信息**
Count of watch rules is over limit.
**错误描述**
在调用addWatcher接口添加系统事件监听者时，由于该系统事件监听者包含的监听规则数量超过限制，系统将拒绝此系统事件监听者的添加。
**可能原因**
系统事件监听者包含的监听规则的数量超过20个。
**处理步骤**
检查系统事件监听者包含的监听规则数量是否超过20个。
## 11200201 事件监听者不存在
**错误信息**
The watcher does not exist.
**错误描述**
在调用removeWatcher移除系统事件监听者时，由于该系统事件监听者不在监听队列，系统将拒绝此系统事件监听者的移除。
**可能原因**
1.尝试移除的系统事件监听者为空；
2.尝试移除的系统事件监听者没有被成功添加过。
**处理步骤**
检查移除的系统事件监听者是否为空，或者是否成功添加过此系统事件监听者。
## 11200301 查询规则的数量超过限制
**错误信息**
Count of query rules is over limit.
**错误描述**
在调用query接口查询系统事件时，由于传入的查询规则数量超限，系统将忽略此次系统事件的查询。
**可能原因**
查询规则个数超过10个。
**处理步骤**
检查查询规则数量是否超过10个。
## 11200302 非法的查询规则
**错误信息**
Invalid query rule.
**错误描述**
在调用query接口查询系统事件时，由于传入了非法的查询规则，系统将忽略此次系统事件的查询。
**可能原因**
1.查询规则中的事件领域名称长度超过16个字符或者事件名称长度超过32个字符；
2.查询规则中的事件领域名称或者事件名称包含特殊字符；
3.查询规则中的事件领域名称或者事件名称为空。
**处理步骤**
检查查询规则中配置的事件领域名称及事件名称是否合法。
## 11200303 并发查询的数量超过限制
**错误信息**
Count of concurrent queriers is over limit.
**错误描述**
在调用query接口查询系统事件时，由于在同一时间点并发查询的数量超过限制，系统将忽略此次系统事件的查询。
**可能原因**
并发查询的数量超过4个。
**处理步骤**
检查在同一时间点是否有4个以上的查询操作。
## 11200304 查询频率超过限制
**错误信息**
Query frequency is over limit.
**错误描述**
在调用query接口查询系统事件时，由于查询频率超过限制，系统将忽略此次系统事件的查询。
**可能原因**
查询频率超过1次/秒。
**处理步骤**
检查是否在1秒内进行1次以上的查询。
zh-cn/application-dev/reference/errorcodes/errorcode-hiviewdfx-hidebug.md 0 → 100644
浏览文件 @ 5eb8abc0
# Hidebug错误码
## 11400101 系统服务获取失败
**错误信息**
ServiceId is invalid, systemAbility is not exist.
**错误描述**
当前serviceId未查询到对应的系统服务。
**可能原因**
当前serviceId未查询到对应的系统服务。
**处理步骤**
传入正确的系统服务id。
zh-cn/application-dev/reference/errorcodes/errorcodes-request.md 0 → 100644
浏览文件 @ 5eb8abc0
# 上传下载错误码
## 13400001 文件操作异常
**错误信息**
File operation error.
**错误描述**
在调用uploadFile或downloadFile接口时，文件权限不足或操作失败。
**可能原因**
该错误码表示文件操作异常，可能原因文件权限不足。
**处理步骤**
请检查文件权限是否合理。
## 13400002 文件路径异常
**错误信息**
Bad file path.
**错误描述**
在调用uploadFile或downloadFile接口时，文件路径不合法。
**可能原因**
该错误码表示文件路径异常，可能原因文件路径错误。
**处理步骤**
请检查上传下载的文件路径是否正确。
## 13400003 服务异常
**错误信息**
Task manager service error.
**错误描述**
在调用downloadFile接口时，下载任务后台服务失败。
**可能原因**
该错误码表示服务异常，，可能原因任务创建失败
**处理步骤**
请检查任务配置是否正确。
zh-cn/application-dev/security/cryptoFramework-guidelines.md
浏览文件 @ 5eb8abc0
......@@ -100,7 +100,7 @@ function testGenerateAesKey() {
示例3：根据指定的RSA非对称密钥二进制数据，生成KeyPair对象（场景2）
1. 获取RSA二进制密钥数据封装成DataBlob对象，按keysize(32位) 、nsize(keysize/8)、 esize(e实际长度)、dsize(keysize/8)、nval(大数n的二进制数据)、eval(大数e的二进制数据)和dval(大数d的二进制数据)拼接形成。
1. 获取RSA二进制密钥数据封装成DataBlob对象，按keysize(32位的密钥位数) 、nsize(32位，值为keysize/8)、 esize(32位的大数e的实际长度，单位Byte)、dsize(32位，值位keysize/8)、nval(大数n的二进制数据)、eval(大数e的二进制数据)和dval(大数d的二进制数据)拼接形成。
2. 调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。
```javascript
......@@ -649,7 +649,7 @@ function signMessageCallback() {
}
function verifyMessageCallback() {
let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA25");
let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256");
verifyer.init(globalKeyPair.pubKey, function (err, data) {
verifyer.update(input1, function(err, data) {
verifyer.verify(input2, SignMessageBlob, function(err, data) {
......@@ -875,15 +875,6 @@ function doMdByCallback(algName) {
```javascript
import cryptoFramework from "@ohos.security.cryptoFramework"
function stringToUint8Array(str) {
var arr = [];
for (var i = 0, j = str.length; i < j; ++i) {
arr.push(str.charCodeAt(i));
}
var tmpArray = new Uint8Array(arr);
return tmpArray;
}
let globalKeyPair;
function ecdhPromise() {
......
zh-cn/application-dev/task-management/Readme-CN.md
浏览文件 @ 5eb8abc0
......@@ -2,12 +2,11 @@
- 后台任务
- [后台任务概述](background-task-overview.md)
- [后台任务开发指导](background-task-dev-guide.md)
- 延迟任务调度
- [延迟任务调度概述](work-scheduler-overview.md)
- [延迟任务调度开发指导](work-scheduler-dev-guide.md)
- [短时任务开发指导](transient-task-dev-guide.md)
- [长时任务开发指导](continuous-task-dev-guide.md)
- [延迟任务开发指导](work-scheduler-dev-guide.md)
- [申请能效资源开发指导](efficiency-resources-apply-dev-guide.md)
- 后台代理提醒
- [后台代理提醒开发概述](background-agent-scheduled-reminder-overview.md)
- [后台代理提醒开发指导](background-agent-scheduled-reminder-guide.md)
\ No newline at end of file
- [后台代理提醒开发指导](background-agent-scheduled-reminder-guide.md)
zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md
浏览文件 @ 5eb8abc0
......@@ -24,147 +24,155 @@ reminderAgent：封装了发布、取消提醒类通知的方法。
## 开发步骤
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> **说明：**
>
> 1. 应用需要配置权限：ohos.permission.PUBLISH_AGENT_REMINDER。
>
> 2. 应用需要申请通知弹窗：[Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8)。
1. 定义一个提醒代理。
倒计时实例定义：
```js
import reminderAgent from '@ohos.reminderAgent';
import notification from '@ohos.notification';
export default {
// eTS工程：
let timer : reminderAgent.ReminderRequestTimer = {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER,
triggerTimeInSeconds: 10,
actionButton: [
{
title: "close",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
}
],
wantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
maxScreenWantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
title: "this is title",
content: "this is content",
expiredContent: "this reminder has expired",
notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION
}
}
```
日历实例定义：
```js
// eTS工程：
let calendar : reminderAgent.ReminderRequestCalendar = {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR,
dateTime: {
year: 2050,
month: 7,
day: 30,
hour: 11,
minute: 14,
second: 30
},
repeatMonths: [1],
repeatDays: [1],
actionButton: [
{
title: "close",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
},
{
title: "snooze",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
},
],
wantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
maxScreenWantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
ringDuration: 5,
snoozeTimes: 2,
timeInterval: 5,
title: "this is title",
content: "this is content",
expiredContent: "this reminder has expired",
snoozeContent: "remind later",
notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION
}
```
闹钟实例定义：
```js
// eTS工程：
let alarm : reminderAgent.ReminderRequestAlarm = {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM,
> 只有用户授权后，提醒代理的功能才能使用。
1、定义目标提醒代理。
2、发布相应的提醒代理。
```ts
import reminderAgent from '@ohos.reminderAgent';
import notification from '@ohos.notification';
// 倒计时实例定义：
let timer : reminderAgent.ReminderRequestTimer = {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER,
triggerTimeInSeconds: 10,
actionButton: [
{
title: "close",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
}
],
wantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
maxScreenWantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
title: "this is title",
content: "this is content",
expiredContent: "this reminder has expired",
notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION
}
// 日历实例定义：
let calendar : reminderAgent.ReminderRequestCalendar = {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR,
dateTime: {
year: 2050,
month: 7,
day: 30,
hour: 11,
minute: 14,
daysOfWeek: [0],
actionButton: [
{
title: "close",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
},
{
title: "snooze",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
},
],
wantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
second: 30
},
repeatMonths: [1],
repeatDays: [1],
actionButton: [
{
title: "close",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
},
{
title: "snooze",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
},
],
wantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
maxScreenWantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
ringDuration: 5,
snoozeTimes: 2,
timeInterval: 5,
title: "this is title",
content: "this is content",
expiredContent: "this reminder has expired",
snoozeContent: "remind later",
notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION
}
// 闹钟实例定义：
let alarm : reminderAgent.ReminderRequestAlarm = {
reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM,
hour: 11,
minute: 14,
daysOfWeek: [0],
actionButton: [
{
title: "close",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
},
maxScreenWantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
{
title: "snooze",
type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
},
ringDuration: 5,
snoozeTimes: 2,
timeInterval: 5,
title: "this is title",
content: "this is content",
expiredContent: "this reminder has expired",
snoozeContent: "remind later",
notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION
],
wantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
maxScreenWantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
ringDuration: 5,
snoozeTimes: 2,
timeInterval: 5,
title: "this is title",
content: "this is content",
expiredContent: "this reminder has expired",
snoozeContent: "remind later",
notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION
}
@Entry
@Component
struct Index {
@State message: string = 'test'
publishReminder() {
reminderAgent.publishReminder(timer, (err, reminderId) => {
console.log("callback, reminderId = " + reminderId);
});
}
build() {
Row() {
Column() {
Text("Index")
.fontSize(50)
.fontWeight(FontWeight.Bold)
Button() { Text('倒计时提醒代理').fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule)
.margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40)
.onClick(() => {
// 示例通过按钮控制提醒代理的发布
this.publishReminder();
})
}
.width('100%')
}
```
2. 发布倒计时提醒。
```js
startTimer() {
reminderAgent.publishReminder(this.timer, (err, reminderId) =>{
this.printInfo(JSON.stringify(err));
this.printInfo("reminderId:" + reminderId);
});
}
```
HML页面：
```html
<div class="container">
<button type="text" value="publishReminder" onclick="startTimer"></button>
</div>
```
.height('100%')
}
}
```
## 相关实例
......
zh-cn/application-dev/task-management/background-agent-scheduled-reminder-overview.md
浏览文件 @ 5eb8abc0
# 后台代理提醒概述
开发者在应用开发时，可以调用后台代理提醒类ReminderRequest去创建定时提醒，包括倒计时、日历、闹钟三种提醒类型。使用后台代理提醒能力后，应用可以被冻结或退出，计时和弹出提醒的功能将被后台系统服务代理。
OpenHarmony设计了相关的后台活动规范。三方应用退后台后如果没有执行相关的后台任务，会被挂起。而对于某些应用，可能需要在某些指定的时刻，处理一些工作。如购物类应用，可能需要在某些时间点，提醒用户有抢购活动可以参加。此类功能通常的实现是应用使用定时器，在时间达到后，由系统拉起应用，执行相关的任务。但是给应用开放了定时器的功能，可能会造成这个机制被滥用，导致后台被挂起的应用频繁地用定时器唤醒。为了避免恶意的后台活动，同时满足应用的业务诉求，设计了后台代理提醒功能。
开发者在应用开发时，使用后台代理提醒能力后，应用可以被挂起或退出，计时和弹出提醒的功能将被后台系统服务代理。避免的应用被频繁唤醒的问题，有助于降低功耗。
## 提醒实例类型
- **倒计时类型**：基于倒计时的提醒功能，适用于短时的计时提醒业务。
- **日历类型**：基于日历的提醒功能，适用于较长时间的提醒业务。
- **闹钟类型**：基于时钟的提醒功能，应用可以使用此功能，实现闹钟相关的业务。
zh-cn/application-dev/task-management/background-task-overview.md
浏览文件 @ 5eb8abc0
# 后台任务概述
后台应用频繁活动，会造成用户设备耗电快、卡顿等现象。因此，为了支撑性能、功耗诉求，系统仅允许应用在后台执行规范内的活动，规范外的活动默认会被挂起，当资源不足时会被回收。同时，应用可以申请能效资源，保证自己在一段时间内不会被挂起，或者在挂起状态能够正常使用一些资源，例如公共事件、计时器等。
后台应用频繁活动，会造成用户设备耗电快、卡顿等现象。因此，为了支撑性能、功耗诉求，系统仅允许应用在后台执行规范内的活动，规范外的活动默认会被挂起，当资源不足时会被回收。
针对应用或业务模块处于后台（无可见界面）时，有需要继续执行或者后续执行的业务，可基于业务类型，申请[短时任务](#短时任务)延迟挂起或者[长时任务](#长时任务)避免进入挂起状态；使用[延迟调度任务](#延迟任务)，执行对实时性要求不高的任务；同时针对特权应用，如果需要更加灵活的配置，可以申请[能效资源](#申请能效资源)。
## 后台任务类型
本文描述的后台任务特指应用或业务模块处于后台（无可见界面）时，有需要继续执行或者后续执行的业务。OpenHarmony将后台任务分为三种类型，并执行不同的处理：
OpenHarmony将后台任务分为四种类型，并提供了一个资源申请的扩展功能：
**1. 无后台业务** ：应用或业务模块退到后台后，无任务需要处理。
**无后台业务** ：应用或业务模块退到后台后，无任务需要处理。
**2. 短时任务** ：应用或业务模块退到后台后，如果有紧急不可推迟且短时间能完成的任务，如应用退后台要进行数据压缩，不可中断，则使用短时任务申请延迟进入挂起（Suspend）状态。
**短时任务** ：应用或业务模块退到后台后，如果有紧急不可推迟且短时间能完成的任务，如应用退后台要进行数据压缩，不可中断，则使用短时任务申请延迟进入挂起（Suspend）状态。
**3. 长时任务** ：如果是用户发起的可感知业务需要长时间后台运行，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。
**长时任务** ：如果是用户发起的可感知业务需要长时间后台运行，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。
**4. 能效资源** ：能效资源包括CPU资源、WORK_SCHEDULER资源、软件资源(COMMON_EVENT, TIMER)、硬件资源(GPS, BLUETOOTH)。如果应用或者进程申请了能效资源，那么根据能效资源的类型会拥有相应的特权，例如申请了CPU资源的可以不被挂起，申请了WORK_SCHEDULER后延时任务可以拥有更长的执行时间。
**延迟任务** ：延迟任务调度给应用提供一个机制，允许应用根据系统安排，在系统空闲时执行实时性不高的任务。当满足设定条件的时候，任务会被放入待调度队列，当系统空闲时调度该任务。
**能效资源** ：能效资源包括CPU资源、WORK_SCHEDULER资源、软件资源(COMMON_EVENT, TIMER)、硬件资源(GPS, BLUETOOTH)。如果应用或者进程申请了能效资源，那么根据能效资源的类型会拥有相应的特权，例如申请了CPU资源的可以不被挂起，申请了WORK_SCHEDULER后延时任务可以拥有更长的执行时间。
## 最佳后台任务选择
![后台任务选择](public_sys-resources/bgtask_choice.png)
## 短时任务
退到后台的应用有不可中断且短时间能完成的任务时，可以使用短时任务机制。该机制允许应用在后台短时间内完成任务，保障应用业务运行不受后台生命周期管理的影响。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> **说明：**
> 短时任务仅针对应用的临时任务提供资源使用生命周期保障，限制单次最大使用时长为3分钟，全天使用配额默认为10分钟（具体时长系统根据应用场景和系统状态智能调整）。
......@@ -63,9 +69,44 @@ OpenHarmony提供了九种后台模式，供需要在后台做长时任务的业
- 长时任务是为了真正在后台长时间执行某个任务，如果一个应用申请了长时任务，但在实际运行过程中，并未真正运行或执行此类任务时，也会被系统检测到并被挂起（Suspend）。
- 一个Ability同一时刻只能申请运行一个长时任务。
## 能效资源申请
能效资源可以分为四种，CPU资源，WORK_SCHEDULER资源，软件资源(COMMON_EVENT，TIMER)，硬件资源(GPS,BLOOTOOTH,AUDIO)。
应用或进程申请能效资源后能够获得相应特权，例如：申请CPU资源后可以不被挂起；申请WORK_SCHEDULER资源后不受延迟任务执行频率约束，且任务执行时间增加；申请软件、硬件资源后，相关资源在挂起状态下不被代理。
## 延迟任务
延迟任务调度给应用提供一个机制，允许应用根据系统安排，在系统空闲时执行实时性要求不高的任务，比如设备空闲时候做一次数据学习等场景。当应用申请延迟任务的时候，任务会被放入待调度队列，系统会根据当前状态，如内存、功耗、温度等统一决策最优的调度时机。同时支持任务的持久化，应用退出或者设备重启，设置的任务同样能够被触发。
### 延迟任务调度约束
延迟调度任务的使用需要遵从如下约束和规则：
- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。默认的超时限制为2分钟，对于系统应用，可以通过[申请能效资源](efficiency-resources-apply-dev-guide.md)获取更长的执行时间（充电状态20分钟，非充电状态10分钟）。
- **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。对于通过能效资源接口申请了WORK_SCHEDULER资源的应用，在资源的有效期内，它的延迟任务执行频率不受限制。
| 应用分组 | 延迟任务执行频率约束 |
| --------------------|------------------------- |
| 活跃 | 最小间隔2小时 |
| 每日使用 | 最小间隔4小时 |
| 经常使用 | 最小间隔24小时 |
| 不经常使用 | 最小间隔48小时 |
| 受限分组 | 禁止 |
| 未使用分组 | 禁止 |
| [能效资源豁免分组](../reference/apis/js-apis-backgroundTaskManager.md#resourcetype9) | 执行频率不受限制 |
- **WorkInfo设置参数约束**
- workId、bundleName、abilityName为必填项，bundleName必须填本应用，否则校验失败。
- 至少要设置一个满足的条件。
- 重复任务时间间隔至少20分钟，当设置重复任务时间间隔时，必须设置始终重复和重复次数中的一个。
- 携带参数信息支持number、string、bool三种类型。
## 申请能效资源
能效资源可以分为四种：CPU资源，WORK_SCHEDULER资源，软件资源(COMMON_EVENT，TIMER)，硬件资源(GPS,BLUETOOTH,AUDIO)。
应用或进程申请能效资源后能够获得相应特权：
* 申请CPU资源后可以不被挂起，直到任务完成。
* 申请WORK_SCHEDULER资源后不受延迟任务执行频率约束，且任务执行时间增加
* 申请COMMON_EVENT资源后，应用在后台处于挂起状态时，仍然能够接收到系统公共事件，申请TIMER资源后，应用能够使用定时器执行精确定时任务、
* 申请硬件资源后，应用在后台被挂起后，依然能够被相关服务唤醒，执行相应的任务。
**表1** 能效资源种类
......@@ -84,3 +125,4 @@ OpenHarmony提供了九种后台模式，供需要在后台做长时任务的业
- 能效资源申请或者释放可以由进程或者应用发起，由应用发起的资源释放会释放属于它的同类型的所有资源，包括进程申请的资源。例如应用申请了CPU资源,进程申请了CPU和WORK_SCHEDULER资源，当应用释放CPU资源的时候，会将进程的CPU资源一同释放，同时不同类型的WORK_SCHEDULER资源不受影响。由进程发起的资源释放对应用申请的资源没有影响，例如当应用和进程同时申请了CPU，进程发起了CPU资源释放，应用的CPU资源不会被释放。
- 同时申请同一类持久资源和非持久资源，持久资源会覆盖非持久资源，在超时时不会释放资源。例如应用首先申请了10s的CPU资源，然后在第5s的时候申请了持久的CPU资源，那么资源会变成持久的，非持久的CPU资源记录会被持久化的CPU资源记录覆盖，到了第10s的时候资源不会被释放，如果在第8s的时候提前释放了资源，那么会将CPU资源释放，无法单独释放其中非持久的或者持久的CPU资源。
- WORK_SCHEDULER资源只能由应用申请和释放，不能由进程申请和释放。
- 需要使用能效资源的应用，需要向应用中心提出申请，获取相应的特权。
zh-cn/application-dev/task-management/background-task-dev-guide.md → zh-cn/application-dev/task-management/continuous-task-dev-guide.md
浏览文件 @ 5eb8abc0
# 后台任务开发指导
## 场景介绍
应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。如果应用需要更加灵活的配置，可以申请能效资源。常见的使用能效资源的场景有：1.应用保证自己在一个时间段内不被挂起，直到任务完成；2.应用处于挂起状态时仍然需要系统的资源，例如闹钟需要计时器资源；3.延时任务需要不受到执行频率的限制，并且拥有更长的执行时间。
在挂起时如果需要单独的某种资源不被代理或者需要更长的延时任务执行时间，可以申请所需的能效资源。
## 短时任务
### 接口说明
**表1** 短时任务主要接口
> **说明：** 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。
| 接口名 | 描述 |
| ---------------------------------------- | ---------------------------------------- |
| requestSuspendDelay(reason:&nbsp;string,&nbsp;callback:&nbsp;Callback&lt;void&gt;):&nbsp;[DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo) | 后台应用申请延迟挂起。<br/>延迟挂起时间一般情况下默认值为180000，低电量时默认值为60000。 |
| getRemainingDelayTime(requestId:&nbsp;number):&nbsp;Promise&lt;number&gt; | 获取应用程序进入挂起状态前的剩余时间。<br/>使用Promise形式返回。 |
| cancelSuspendDelay(requestId:&nbsp;number):&nbsp;void | 取消延迟挂起。 |
### 开发步骤
1. 申请延迟挂起
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let myReason = 'test requestSuspendDelay';
try {
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
})
var id = delayInfo.requestId;
var time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);
} catch (error) {
console.error(`requestSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
```
2. 获取进入挂起前的剩余时间
```js
try {
backgroundTaskManager.getRemainingDelayTime(id, (error, res) => {
if(error) {
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
} else {
console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}
})
} catch (error) {
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
}
```
3. 取消延迟挂起
```js
try {
backgroundTaskManager.cancelSuspendDelay(id);
} catch (error) {
console.error(`cancelSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
```
### 开发实例
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let myReason = 'test requestSuspendDelay';
var delayInfo;
// 申请延迟挂起
try {
delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
})
} catch (error) {
console.error(`requestSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
// 打印延迟挂起信息
var id = delayInfo.requestId;
var time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);
// 获取应用程序进入挂起状态前的剩余时间
try {
backgroundTaskManager.getRemainingDelayTime(id, (error, res) => {
if(error) {
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
} else {
console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}
})
} catch (error) {
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
}
## 长时任务
// 取消延迟挂起
try {
backgroundTaskManager.cancelSuspendDelay(id);
} catch (error) {
console.error(`cancelSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
```
### 场景说明
## 长时任务
如果应用需要在后台长时间执行用户可感知的任务，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。
长时任务在后台执行没有时间限制。为了避免该机制被滥用，系统只允许申请有限个数的长时任务类型，同时会有相应的通知提示与长时任务相关联，使用户可感知，并且系统会添加相应的校验机制，确保应用是的确在执行相应的长时任务。
### 权限
......@@ -153,109 +42,56 @@ ohos.permission.KEEP_BACKGROUND_RUNNING
基于FA模型：
1. 新建Api Version 8的工程后，在工程目录中右键选择“new” -> “Ability” -> “Service Ability” 快速创建Service Ability组件。并在config.json文件中配置长时任务权限、后台模式类型，其中Ability类型为“service”。
```
"module": {
"package": "com.example.myapplication",
"abilities": [
{
"backgroundModes": [
"dataTransfer",
"location"
], // 后台模式类型
"type": "service" // ability类型为service
}
],
"reqPermissions": [
{
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // 长时任务权限
}
]
}
```
2. 申请长时任务。
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
// 通过wantAgent模块的getWantAgent方法获取WantAgent对象
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err);
});
});
```
3. 停止长时任务。
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
基于FA的Service Ability使用，参考[ServiceAbility开发指导](../ability/fa-serviceability.md)。
```
当不需要与后台执行的长时任务交互时，可以采用startAbility()方法启动Service Ability。并在Service Ability的onStart回调方法中，调用长时任务的申请接口，声明此服务需要在后台长时运行。当任务执行完，再调用长时任务取消接口，及时释放资源。
基于Stage模型：
当需要与后台执行的长时任务交互时（如播放音乐等）。可以采用connectAbility()方法启动并连接Service Ability。在获取到服务的代理对象后，与服务进行通信，控制长时任务的申请和取消。
1. 新建Api Version 9的工程后，在工程目录中右键选择“New” -> “Ability” 快速创建Ability组件。并在module.json5文件中配置长时任务权限、后台模式类型。
1、新建Api Version 8的工程后，在工程目录中右键选择“new” -> “Ability” -> “Service Ability” 快速创建Service Ability组件。并在config.json文件中配置长时任务权限、后台模式类型，其中Ability类型为“service”。
```
"module": {
"abilities": [
```
"module": {
"package": "com.example.myapplication",
"abilities": [
{
"backgroundModes": [
"backgroundModes": [
"dataTransfer",
"location"
], // 后台模式类型
], // 后台模式类型
"type": "service" // ability类型为service
}
],
"requestPermissions": [
],
"reqPermissions": [
{
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // 长时任务权限
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // 长时任务权限
}
]
}
```
]
}
```
2. 申请长时任务。
2、在Service Ability调用长时任务的申请和取消接口。
```ts
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent';
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';
import rpc from "@ohos.rpc";
function startContinuousTask() {
let wantAgentInfo = {
// 点击通知后，将要执行的动作列表
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
// 点击通知后，动作类型
operationType: wantAgent.OperationType.START_ABILITY,
// 使用者自定义的一个私有值
requestCode: 0,
// 点击通知后，动作执行属性
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
......@@ -265,83 +101,25 @@ ohos.permission.KEEP_BACKGROUND_RUNNING
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((error) => {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err);
});
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
});
```
3. 停止长时任务。
```ts
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
}
function stopContinuousTask() {
try {
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
```
### 开发实例
基于FA模型：
基于FA的Service Ability使用，参考[ServiceAbility开发指导](../ability/fa-serviceability.md)。
当不需要与后台执行的长时任务交互时，可以采用startAbility()方法启动Service Ability。并在Service Ability的onStart回调方法中，调用长时任务的申请接口，声明此服务需要在后台长时运行。当任务执行完，再调用长时任务取消接口，及时释放资源。
当需要与后台执行的长时任务交互时（如播放音乐等）。可以采用connectAbility()方法启动并连接Service Ability。在获取到服务的代理对象后，与服务进行通信，控制长时任务的申请和取消。
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';
import rpc from "@ohos.rpc";
function startContinuousTask() {
let wantAgentInfo = {
// 点击通知后，将要执行的动作列表
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
// 点击通知后，动作类型
operationType: wantAgent.OperationType.START_ABILITY,
// 使用者自定义的一个私有值
requestCode: 0,
// 点击通知后，动作执行属性
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
// 通过wantAgent模块的getWantAgent方法获取WantAgent对象
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err);
});
});
}
function stopContinuousTask() {
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
}
async function processAsyncJobs() {
......@@ -408,13 +186,125 @@ export default {
基于Stage模型：
Stage模型的相关信息参考[Stage模型综述](../ability/stage-brief.md)。
当应用需要在后台执行长时任务时，可以通过Call的方式在后台创建并运行Ability。使用方式参考[Call调用开发指导](../ability/stage-call.md)。
1、新建Api Version 9的工程后，在工程目录中右键选择“New” -> “Ability” 快速创建Ability组件。并在module.json5文件中配置长时任务权限、后台模式类型。
```
"module": {
"abilities": [
{
"backgroundModes": [
"dataTransfer",
"location"
], // 后台模式类型
}
],
"requestPermissions": [
{
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // 长时任务权限
}
]
}
```
2、在应用内执行长时任务时，由于元能力启动管控规则限制，不支持同应用通过startAbilityByCall的形式在后台创建并运行Ability。可以直接在page中，执行相应的代码。Stage模型的Ability使用参考[Ability开发指导](../ability/stage-ability.md)。
```ts
import wantAgent from '@ohos.wantAgent';
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
@Entry
@Component
struct Index {
@State message: string = 'test'
// 通过getContext方法，来获取page所在的Ability上下文。
private context: any = getContext(this)
startContinuousTask() {
let wantAgentInfo = {
// 点击通知后，将要执行的动作列表
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility",
}
],
// 点击通知后，动作类型
operationType: wantAgent.OperationType.START_ABILITY,
// 使用者自定义的一个私有值
requestCode: 0,
// 点击通知后，动作执行属性
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
// 通过wantAgent模块的getWantAgent方法获取WantAgent对象
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
try {
backgroundTaskManager.startBackgroundRunning(this.context,
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err);
});
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
});
}
stopContinuousTask() {
try {
backgroundTaskManager.stopBackgroundRunning(this.context).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
}
build() {
Row() {
Column() {
Text("Index")
.fontSize(50)
.fontWeight(FontWeight.Bold)
Button() { Text('申请长时任务').fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule)
.margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40)
.onClick(() => {
// 通过按钮申请长时任务
this.startContinuousTask();
// 此处执行具体的长时任务逻辑，如放音等。
})
Button() { Text('取消长时任务').fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule)
.margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40)
.onClick(() => {
// 此处结束具体的长时任务的执行
// 通过按钮取消长时任务
this.stopContinuousTask();
})
}
.width('100%')
}
.height('100%')
}
}
```
3、当需要跨设备或者跨应用在后台执行长时任务时，可以通过Call的方式在后台创建并运行Ability。使用方式参考[Call调用开发指导](../ability/stage-call.md)。
```ts
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent';
const MSG_SEND_METHOD: string = 'CallSendMsg'
let mContext = null;
function startContinuousTask() {
......@@ -423,7 +313,7 @@ function startContinuousTask() {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
abilityName: "com.example.myapplication.MainAbility",
}
],
// 点击通知后，动作类型
......@@ -485,15 +375,16 @@ class MySequenceable {
function sendMsgCallback(data) {
console.info('BgTaskAbility funcCallBack is called ' + data)
let receivedData = new Mysequenceable(0, "")
let receivedData = new MySequenceable(0, "")
data.readSequenceable(receivedData)
console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`)
// 可以根据Caller端发送的序列化数据的str值，执行不同的方法。
if (receivedData.str === 'start_bgtask') {
startContinuousTask()
} else if (receivedData.str === 'stop_bgtask') {
stopContinuousTask();
}
return new Mysequenceable(10, "Callee test");
return new MySequenceable(10, "Callee test");
}
export default class BgTaskAbility extends Ability {
......@@ -516,7 +407,7 @@ export default class BgTaskAbility extends Ability {
onWindowStageCreate(windowStage) {
console.info("[Demo] BgTaskAbility onWindowStageCreate")
windowStage.loadContent("pages/second").then((data)=> {
windowStage.loadContent("pages/index").then((data)=> {
console.info(`load content succeed with data ${JSON.stringify(data)}`)
}).catch((error)=>{
console.error(`load content failed with error ${JSON.stringify(error)}`)
......@@ -537,119 +428,6 @@ export default class BgTaskAbility extends Ability {
};
```
## 能效资源申请
### 接口说明
**表1** 能效资源申请主要接口
> **说明：** 后台任务管理错误码见[backgroundTaskManager错误码](../errorcodes/errorcode-backgroundTaskMgr.md)。
| 接口名 | 描述 |
| ---------------------------------------- | ---------------------------------------- |
| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): void | 申请能效资源。 |
| resetAllEfficiencyResources():void | 释放申请的能效资源。 |
### 开发步骤
1. 申请能效资源
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let request = {
resourceTypes: backgroundTaskManager.ResourceType.CPU,
isApply: true,
timeOut: 0,
reason: "apply",
isPersist: true,
isProcess: true,
};
try {
backgroundTaskManager.applyEfficiencyResources(request);
console.info("applyEfficiencyResources success. ");
} catch (error) {
console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
```
2. 释放申请的部分资源
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let request = {
resourceTypes: backgroundTaskManager.ResourceType.CPU,
isApply: false,
timeOut: 0,
reason: "reset",
};
try {
backgroundTaskManager.applyEfficiencyResources(request);
console.info("applyEfficiencyResources success. ");
} catch (error) {
console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
```
3. 释放申请的所有资源
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
try {
backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
} catch (error) {
console.error(`resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
```
### 开发实例
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
// 申请能效资源
let request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT |
backgroundTaskManager.ResourceType.TIMER,
isApply: true,
timeOut: 0,
reason: "apply",
isPersist: true,
isProcess: true,
};
try {
backgroundTaskManager.applyEfficiencyResources(request);
console.info("applyEfficiencyResources success. ");
} catch (error) {
console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
// 释放部分资源
request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT,
isApply: false,
timeOut: 0,
reason: "reset",
};
try {
backgroundTaskManager.applyEfficiencyResources(request);
console.info("applyEfficiencyResources success. ");
} catch (error) {
console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
// 释放全部资源
try {
backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
} catch (error) {
console.error(`resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
```
## 相关实例
基于后台任务管理，有以下相关实例可供参考：
......
zh-cn/application-dev/task-management/efficiency-resources-apply-dev-guide.md 0 → 100644
浏览文件 @ 5eb8abc0
## 申请能效资源
### 场景说明
在实际的系统中，存在一些重要性高的系统应用，虽然此类应用相比普通应用具有一定的特权，但为了进一步平衡系统的功耗开销，这些应用同样需要支持在后台可被挂起。但对于系统特权应用，为了避免挂起后重要功能受到影响，提供了独立的能效资源申请接口，使这些特权应用可以在后台执行一些特殊的任务和使用特定的系统资源，例如在被挂起期间如果仍然希望能够收到系统公共事件，可以使用能效资源接口向系统申请使用公共事件资源。
对于需要升级为特权应用的，开发者需要合理评估自己的业务诉求，向应用中心提出申请。
### 接口说明
**表1** 申请能效资源主要接口
| 接口名 | 描述 |
| ---------------------------------------- | ---------------------------------------- |
| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): boolean | 申请能效资源。 |
| resetAllEfficiencyResources():void | 释放申请的能效资源。 |
### 开发步骤
1、当特权应用需要在后台使用特殊资源时。向系统申请目标资源。
2、当资源使用完毕，需要及时释放。支持释放部分资源或全部资源。
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
// 申请能效资源
let request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT |
backgroundTaskManager.ResourceType.TIMER,
isApply: true,
timeOut: 0,
reason: "apply",
isPersist: true,
isProcess: true,
};
let res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res);
// 释放部分资源
request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT,
isApply: false,
timeOut: 0,
reason: "reset",
};
res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res);
// 释放全部资源
backgroundTaskManager.resetAllEfficiencyResources();
```
zh-cn/application-dev/task-management/transient-task-dev-guide.md 0 → 100644
浏览文件 @ 5eb8abc0
## 短时任务
### 场景说明
当应用退到后台默认有6到12秒的运行时长，超过该时间后，系统会将应用置为挂起状态。对于绝大多数应用，6到12秒的时间，足够执行一些重要的任务，但如果应用需要更多的时间，可以通过短时任务接口，扩展应用的执行时间。
建议不要等到应用退后台后，才调用requestSuspendDelay方法申请延迟挂起，而是应该在执行任何的耗时操作前，都应该调用该接口，向系统申明扩展应用的执行时间。
当应用在前台时，使用requestSuspendDelay方法，不会影响应用的短时任务配额。
由于每个应用每天的短时任务配额时间有限，当执行完耗时任务后，应当及时取消延迟挂起的申请。
一些典型的耗时任务有，需要保存一些状态数据到本地数据库，需要打开和处理一个大型文件，需要同步一些数据到应用的云端服务器等。
### 接口说明
**表1** 短时任务主要接口
| 接口名 | 描述 |
| ---------------------------------------- | ---------------------------------------- |
| requestSuspendDelay(reason:&nbsp;string,&nbsp;callback:&nbsp;Callback&lt;void&gt;):&nbsp;[DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo) | 后台应用申请延迟挂起。<br/>延迟挂起时间一般情况下默认值为180000，低电量时默认值为60000。 |
| getRemainingDelayTime(requestId:&nbsp;number):&nbsp;Promise&lt;number&gt; | 获取应用程序进入挂起状态前的剩余时间。<br/>使用Promise形式返回。 |
| cancelSuspendDelay(requestId:&nbsp;number):&nbsp;void | 取消延迟挂起。 |
### 开发步骤
1、当应用需要开始执行一个耗时的任务时。调用短时任务申请接口，并且在任务执行完后，调用短时任务取消接口。
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let delayInfo;
let id;
// 申请延迟挂起
function requestSuspendDelay() {
let myReason = 'test requestSuspendDelay';
delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
// 此回调函数执行，表示应用的延迟挂起申请即将超时，应用需要执行一些清理和标注工作。
});
id = delayInfo.requestId;
console.info("requestId is: " + id);
}
// 获取进入挂起前的剩余时间
function getRemainingDelayTime() {
let delayTime = 0;
backgroundTaskManager.getRemainingDelayTime(id).then((res) => {
console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
delayTime = res;
}).catch((err) => {
console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code);
});
return delayTime;
}
// 取消延迟挂起
function cancelSuspendDelay() {
backgroundTaskManager.cancelSuspendDelay(id);
}
function performingLongRunningTask() {
// 在执行具体的耗时任务前，调用短时任务申请接口。向系统申请延迟挂起，延长应用的后台执行时间。
requestSuspendDelay();
// 通过剩余时间查询接口，获取可用时间配额。
let delayTime = getRemainingDelayTime();
if (delayTime < 0) { // 如果时间配置少于一定的大小，考虑取消此次耗时操作。
// 处理短时任务配额时间不够的场景
cancelSuspendDelay();
return;
}
// 此处执行具体的耗时任务。
// 耗时任务执行完，调用短时任务取消接口，避免配额浪费。
cancelSuspendDelay();
}
```
zh-cn/application-dev/task-management/work-scheduler-dev-guide.md
浏览文件 @ 5eb8abc0
......@@ -2,7 +2,7 @@
## 场景介绍
应用要执行对实时性要求不高的任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、温度等统一决策调度时间。延迟任务调度约束见[延迟任务调度概述](./work-scheduler-overview.md)。
应用要执行对实时性要求不高的任务或持久性任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、温度等统一决策调度时间。延迟任务调度约束见[延迟任务调度约束](./background-task-overview.md#延迟任务调度约束)。
## 接口说明
注册相关接口包导入：
......@@ -35,7 +35,7 @@ isLastWorkTimeOut(workId: number): Promise\<boolean>;| 获取上次任务是否
**表2** WorkInfo包含参数
> **说明：** WorkInfo设置参数约束见[延迟任务调度概述](./work-scheduler-overview.md)
> **说明：** WorkInfo设置参数约束见[延迟任务调度约束](./background-task-overview.md#延迟任务调度约束)
参数名| 类型 |描述
---------------------------------------------------------|-----------------------------------------|---------------------------------------------------------
......@@ -62,173 +62,139 @@ onWorkStop(work: WorkInfo): void | 延迟调度任务结束回调
### 开发步骤
**开发对应的Extension**
1、开发对应的ExtensionAbility，用于回调执行具体的延迟任务。关于ExtensionAbility的介绍，参考[ExtensionAbility机制](../ability/stage-brief.md#extensionability机制)。
import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility';
export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility {
onWorkStart(workInfo) {
console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo));
}
onWorkStop(workInfo) {
console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo));
}
}
**注册延迟任务**
```ts
import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility';
import workScheduler from '@ohos.resourceschedule.workScheduler';
let workInfo = {
workId: 1,
batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
isRepeat: false,
isPersisted: true,
bundleName: "com.example.myapplication",
abilityName: "MyExtension",
parameters: {
mykey0: 1,
mykey1: "string value",
mykey2: true,
mykey3: 1.5
}
export default class MyExtension extends WorkSchedulerExtensionAbility {
onWorkStart(workInfo) {
console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo));
}
try{
workScheduler.startWork(workInfo);
console.info('workschedulerLog startWork success');
} catch (error) {
console.error(`workschedulerLog startwork failed. code is ${error.code} message is ${error.message}`);
onWorkStop(workInfo) {
console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo));
}
}
```
**取消延迟任务**
2、注册延迟任务
import workScheduler from '@ohos.resourceschedule.workScheduler';
```ts
import workScheduler from '@ohos.resourceschedule.workScheduler';
let workInfo = {
workId: 1,
batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
isRepeat: false,
isPersisted: true,
bundleName: "com.example.myapplication",
abilityName: "MyExtension",
parameters: {
mykey0: 1,
mykey1: "string value",
mykey2: true,
mykey3: 1.5
}
}
try{
workScheduler.stopWork(workInfo, false);
console.info('workschedulerLog stopWork success');
} catch (error) {
console.error(`workschedulerLog stopWork failed. code is ${error.code} message is ${error.message}`);
}
let workInfo = {
workId: 1,
batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
isRepeat: false,
isPersisted: true,
bundleName: "com.example.myapplication",
abilityName: "MyExtension",
parameters: {
mykey0: 1,
mykey1: "string value",
mykey2: true,
mykey3: 1.5
}
}
try{
workScheduler.startWork(workInfo);
console.info('workschedulerLog startWork success');
} catch (error) {
console.error(`workschedulerLog startwork failed. code is ${error.code} message is ${error.message}`);
}
```
**获取指定延迟任务**
3、取消延迟任务
1.Callback写法
```ts
import workScheduler from '@ohos.resourceschedule.workScheduler';
try{
workScheduler.getWorkStatus(50, (error, res) => {
if (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
} else {
for (let item in res) {
console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
}
}
});
} catch (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
}
let workInfo = {
workId: 1,
batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
isRepeat: false,
isPersisted: true,
bundleName: "com.example.myapplication",
abilityName: "MyExtension",
parameters: {
mykey0: 1,
mykey1: "string value",
mykey2: true,
mykey3: 1.5
}
}
try{
workScheduler.stopWork(workInfo, false);
console.info('workschedulerLog stopWork success');
} catch (error) {
console.error(`workschedulerLog stopWork failed. code is ${error.code} message is ${error.message}`);
}
```
2.Promise写法
4、获取指定延迟任务
try{
workScheduler.getWorkStatus(50).then((res) => {
for (let item in res) {
console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
}
}).catch((error) => {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
})
} catch (error) {
```ts
try{
workScheduler.getWorkStatus(50, (error, res) => {
if (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
} else {
for (let item in res) {
console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
}
}
});
} catch (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
}
```
**获取所有延迟任务**
1.Callback写法
try{
workScheduler.obtainAllWorks((error, res) =>{
if (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
} else {
console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
}
});
} catch (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
}
2.Promise写法
5、获取所有延迟任务
try{
workScheduler.obtainAllWorks().then((res) => {
console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
}).catch((error) => {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
})
} catch (error) {
```ts
try{
workScheduler.obtainAllWorks((error, res) =>{
if (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
} else {
console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
}
});
} catch (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
}
```
**停止并清除任务**
try{
workScheduler.stopAndClearWorks();
console.info(`workschedulerLog stopAndClearWorks success`);
} catch (error) {
console.error(`workschedulerLog stopAndClearWorks failed. code is ${error.code} message is ${error.message}`);
}
**判断上次执行是否超时**
6、停止并清除任务
1.Callback写法
```ts
try{
workScheduler.stopAndClearWorks();
console.info(`workschedulerLog stopAndClearWorks success`);
} catch (error) {
console.error(`workschedulerLog stopAndClearWorks failed. code is ${error.code} message is ${error.message}`);
}
```
try{
workScheduler.isLastWorkTimeOut(500, (error, res) =>{
if (error) {
onsole.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
} else {
console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
}
});
} catch (error) {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
}
7、判断上次执行是否超时
2.Promise写法
try{
workScheduler.isLastWorkTimeOut(500)
.then(res => {
console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
})
.catch(error => {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
});
} catch (error) {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
```ts
try{
workScheduler.isLastWorkTimeOut(500, (error, res) =>{
if (error) {
onsole.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
} else {
console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
}
});
} catch (error) {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
}
```
## 相关实例
......
zh-cn/application-dev/task-management/work-scheduler-overview.md 已删除 100644 → 0
浏览文件 @ 5ee1e894
# 延迟任务调度概述
延迟任务调度给应用提供一个机制，允许应用根据系统安排，在系统空闲时执行实时性不高的任务。当满足设定条件的时候，任务会被放入待调度队列，当系统空闲时调度该任务。
## 使用说明
应用要执行对实时性要求不高的任务的时候，比如设备空闲时候做一次数据学习等场景，可以使用延迟调度任务，该机制在满足应用设定条件的时候，会根据系统当前状态，如内存、功耗、温度等统一决策调度时机。
## 延迟任务调度约束
延迟调度任务的使用需要遵从如下约束和规则：
- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。默认的超时限制为2分钟，对于系统应用，可以通过[能效资源申请接口](background-task-overview.md#能效资源申请)获取更长的执行时间（充电状态20分钟，非充电状态10分钟）。
- **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。对于通过能效资源接口申请了WORK_SCHEDULER资源的应用，在资源的有效期内，它的延迟任务执行频率不受限制。
应用分组 | 延迟任务执行频率约束
--------------------|-------------------------
活跃 | 最小间隔2小时
每日使用 | 最小间隔4小时
经常使用 | 最小间隔24小时
不经常使用 | 最小间隔48小时
受限分组 | 禁止
未使用分组 | 禁止
[能效资源豁免分组](../reference/apis/js-apis-backgroundTaskManager.md#resourcetype9) | 执行频率不受限制
- **WorkInfo设置参数约束**
（1） workId、bundleName、abilityName为必填项，bundleName必须填本应用，否则校验失败。
（2）至少要设置一个满足的条件。
（3）重复任务时间间隔至少20分钟，当设置重复任务时间间隔时，必须设置始终重复和重复次数中的一个。
（4）携带参数信息支持number、string、bool三种类型。
\ No newline at end of file
zh-cn/device-dev/driver/driver-peripherals-usb-des.md
浏览文件 @ 5eb8abc0
......@@ -36,51 +36,51 @@ USB驱动模型Host侧开放的API接口功能，参考USB Host驱动模型图
| int32_t&nbsp;UsbInitHostSdk(struct&nbsp;UsbSession&nbsp;\*\*session); | USB主机端驱动开发工具包初始化 |
| int32_t&nbsp;UsbExitHostSdk(const&nbsp;struct&nbsp;UsbSession<br/>\*session); | USB主机端驱动开发工具包退出 |
| const&nbsp;struct&nbsp;UsbInterface&nbsp;\*UsbClaimInterface(const<br/>struct&nbsp;UsbSession&nbsp;\*session,&nbsp;uint8_t&nbsp;busNum,&nbsp;uint8_t<br/>usbAddr,&nbsp;uint8_t&nbsp;interfaceIndex); | 获取USB接口对象 |
| int&nbsp;UsbReleaseInterface(const&nbsp;struct&nbsp;UsbInterface<br/>\*interfaceObj); | 释放USB接口对象 |
| int&nbsp;UsbAddOrRemoveInterface(const&nbsp;struct&nbsp;UsbSession<br/>\*session,&nbsp;uint8_t&nbsp;busNum,&nbsp;uint8_t&nbsp;usbAddr,&nbsp;uint8_t<br/>interfaceIndex,&nbsp;UsbInterfaceStatus&nbsp;status); | 增加移除接口 |
| int32_t&nbsp;UsbReleaseInterface(const&nbsp;struct&nbsp;UsbInterface<br/>\*interfaceObj); | 释放USB接口对象 |
| int32_t&nbsp;UsbAddOrRemoveInterface(const&nbsp;struct&nbsp;UsbSession<br/>\*session,&nbsp;uint8_t&nbsp;busNum,&nbsp;uint8_t&nbsp;usbAddr,&nbsp;uint8_t<br/>interfaceIndex,&nbsp;UsbInterfaceStatus&nbsp;status); | 增加移除接口 |
| UsbInterfaceHandle&nbsp;\*UsbOpenInterface(const&nbsp;struct<br/>UsbInterface&nbsp;\*interfaceObj); | 打开USB对象接口 |
| int32_t&nbsp;UsbCloseInterface(const&nbsp;UsbInterfaceHandle<br/>\*interfaceHandle); | 关闭USB接口对象 |
| int32_t&nbsp;UsbSelectInterfaceSetting(const<br/>UsbInterfaceHandle&nbsp;\*interfaceHandle,&nbsp;uint8_t<br/>settingIndex,&nbsp;struct&nbsp;UsbInterface&nbsp;\*\*interfaceObj); | 设置可选配置 |
| int32_t&nbsp;UsbGetPipeInfo(const&nbsp;UsbInterfaceHandle<br/>\*interfaceHandle,&nbsp;uint8_t&nbsp;settingIndex,&nbsp;uint8_t&nbsp;pipeId,<br/>struct&nbsp;UsbPipeInfo&nbsp;\*pipeInfo); | 获取指定可选设置的管道信息 |
| int32_t&nbsp;UsbClearInterfaceHalt(const<br/>UsbInterfaceHandle&nbsp;\*interfaceHandle,&nbsp;uint8_t<br/>pipeAddress); | 清除指定索引的管道状态 |
| struct&nbsp;UsbRequest&nbsp;\*UsbAllocRequest(const<br/>UsbInterfaceHandle&nbsp;\*interfaceHandle,&nbsp;int&nbsp;isoPackets<br/>,&nbsp;int&nbsp;length); | 分配请求对象 |
| int&nbsp;UsbFreeRequest(const&nbsp;struct&nbsp;UsbRequest<br/>\*request); | 释放请求对象 |
| int&nbsp;UsbSubmitRequestAsync(const&nbsp;struct&nbsp;UsbRequest<br/>\*request); | 发送异步请求 |
| struct&nbsp;UsbRequest&nbsp;\*UsbAllocRequest(const<br/>UsbInterfaceHandle&nbsp;\*interfaceHandle,&nbsp;int32_t&nbsp;isoPackets<br/>,&nbsp;int32_t&nbsp;length); | 分配请求对象 |
| int32_t&nbsp;UsbFreeRequest(const&nbsp;struct&nbsp;UsbRequest<br/>\*request); | 释放请求对象 |
| int32_t&nbsp;UsbSubmitRequestAsync(const&nbsp;struct&nbsp;UsbRequest<br/>\*request); | 发送异步请求 |
| int32_t&nbsp;UsbFillRequest(const&nbsp;struct&nbsp;UsbRequest<br/>\*request,&nbsp;const&nbsp;UsbInterfaceHandle&nbsp;\*interfaceHandle,<br/>const&nbsp;struct&nbsp;UsbRequestParams&nbsp;\*params); | 填充请求 |
| sint&nbsp;UsbCancelRequest(const&nbsp;struct&nbsp;UsbRequest<br/>\*request); | 取消异步请求 |
| int&nbsp;UsbSubmitRequestSync(const&nbsp;struct&nbsp;UsbRequest<br/>\*request); | 发送同步请求 |
| int32_t&nbsp;UsbCancelRequest(const&nbsp;struct&nbsp;UsbRequest<br/>\*request); | 取消异步请求 |
| int32_t&nbsp;UsbSubmitRequestSync(const&nbsp;struct&nbsp;UsbRequest<br/>\*request); | 发送同步请求 |
**表2** usb_raw_api.h
| 接口名称 | 功能描述 |
| -------- | -------- |
| int&nbsp;UsbRawInit(struct&nbsp;UsbSession&nbsp;\*\*session); | USB驱动开发工具包专家模式初始化 |
| int&nbsp;UsbRawExit(const&nbsp;struct&nbsp;UsbSession&nbsp;\*session); | USB驱动开发工具包专家模式退出 |
| int32_t&nbsp;UsbRawInit(struct&nbsp;UsbSession&nbsp;\*\*session); | USB驱动开发工具包专家模式初始化 |
| int32_t&nbsp;UsbRawExit(const&nbsp;struct&nbsp;UsbSession&nbsp;\*session); | USB驱动开发工具包专家模式退出 |
| UsbRawHandle&nbsp;\*UsbRawOpenDevice(const&nbsp;struct<br/>UsbSession&nbsp;\*session,&nbsp;uint8_t&nbsp;busNum,&nbsp;uint8_t<br/>usbAddr); | 打开USB设备对象 |
| int&nbsp;UsbRawCloseDevice(const&nbsp;UsbRawHandle<br/>\*devHandle); | 关闭USB设备对象 |
| int&nbsp;UsbRawSendControlRequest(const&nbsp;struct<br/>UsbRawRequest&nbsp;\*request,&nbsp;const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;const&nbsp;struct&nbsp;UsbControlRequestData<br/>\*requestData); | 执行同步控制传输 |
| int&nbsp;UsbRawSendBulkRequest(const&nbsp;struct<br/>UsbRawRequest&nbsp;\*request,&nbsp;const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;const&nbsp;struct&nbsp;UsbRequestData<br/>\*requestData); | 执行同步批量传输 |
| int&nbsp;UsbRawSendInterruptRequest(const&nbsp;struct<br/>UsbRawRequest&nbsp;\*request,&nbsp;const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;const&nbsp;struct&nbsp;UsbRequestData<br/>\*requestData); | 执行同步中断传输 |
| int&nbsp;UsbRawGetConfigDescriptor(const&nbsp;UsbRawDevice<br/>\*rawDev,&nbsp;uint8_t&nbsp;configIndex,&nbsp;struct<br/>UsbRawConfigDescriptor&nbsp;\*\*config); | 获取给定设备指定ID的设备配置描述符 |
| int32_t&nbsp;UsbRawCloseDevice(const&nbsp;UsbRawHandle<br/>\*devHandle); | 关闭USB设备对象 |
| int32_t&nbsp;UsbRawSendControlRequest(const&nbsp;struct<br/>UsbRawRequest&nbsp;\*request,&nbsp;const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;const&nbsp;struct&nbsp;UsbControlRequestData<br/>\*requestData); | 执行同步控制传输 |
| int32_t&nbsp;UsbRawSendBulkRequest(const&nbsp;struct<br/>UsbRawRequest&nbsp;\*request,&nbsp;const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;const&nbsp;struct&nbsp;UsbRequestData<br/>\*requestData); | 执行同步批量传输 |
| int32_t&nbsp;UsbRawSendInterruptRequest(const&nbsp;struct<br/>UsbRawRequest&nbsp;\*request,&nbsp;const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;const&nbsp;struct&nbsp;UsbRequestData<br/>\*requestData); | 执行同步中断传输 |
| int32_t&nbsp;UsbRawGetConfigDescriptor(const&nbsp;UsbRawDevice<br/>\*rawDev,&nbsp;uint8_t&nbsp;configIndex,&nbsp;struct<br/>UsbRawConfigDescriptor&nbsp;\*\*config); | 获取给定设备指定ID的设备配置描述符 |
| void&nbsp;UsbRawFreeConfigDescriptor(const&nbsp;struct<br/>UsbRawConfigDescriptor&nbsp;\*config); | 释放配置描述符内存空间 |
| int&nbsp;UsbRawGetConfiguration(const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;int&nbsp;\*config); | 获取当前激活配置 |
| int&nbsp;UsbRawSetConfiguration(const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;int&nbsp;config); | 设置当前激活配置 |
| int&nbsp;UsbRawGetDescriptor(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawDescriptorParam&nbsp;\*param,&nbsp;const&nbsp;unsigned&nbsp;char<br/>\*data); | 获取描述符信息 |
| int32_t&nbsp;UsbRawGetConfiguration(const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;int32_t&nbsp;\*config); | 获取当前激活配置 |
| int32_t&nbsp;UsbRawSetConfiguration(const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;int32_t&nbsp;config); | 设置当前激活配置 |
| int32_t&nbsp;UsbRawGetDescriptor(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawDescriptorParam&nbsp;\*param,&nbsp;const&nbsp;unsigned&nbsp;char<br/>\*data); | 获取描述符信息 |
| UsbRawDevice&nbsp;\*UsbRawGetDevice(const&nbsp;UsbRawHandle<br/>\*devHandle); | 由设备句柄获取设备指针 |
| int&nbsp;UsbRawGetDeviceDescriptor(const&nbsp;UsbRawDevice<br/>\*rawDev,&nbsp;struct<br/>UsbDeviceDescriptor&nbsp;\*desc); | 获取给定设备的USB设备描述符 |
| int&nbsp;UsbRawClaimInterface(const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;int<br/>interfaceNumber); | 声明给定设备句柄上的接口 |
| int&nbsp;UsbRawReleaseInterface(const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;in<br/>t&nbsp;interfaceNumber); | 释放之前声明的接口 |
| int&nbsp;UsbRawResetDevice(const&nbsp;UsbRawHandle<br/>\*devHandle); | 复位设备 |
| struct&nbsp;UsbRawRequest&nbsp;\*UsbRawAllocRequest(const<br/>UsbRawHandle<br/>\*devHandle,&nbsp;int&nbsp;isoPackets,&nbsp;int&nbsp;length); | 分配一个带有指定数量的同步包描述符的传输请求 |
| int&nbsp;UsbRawFreeRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request); | 释放之前分配的传输请求 |
| int&nbsp;UsbRawFillBulkRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawFillRequestData&nbsp;\*fillData); | 填充批量传输请求所需信息 |
| int&nbsp;UsbRawFillControlSetup(const&nbsp;unsigned&nbsp;char&nbsp;\*setup,<br/>const&nbsp;struct&nbsp;UsbControlRequestData&nbsp;\*requestData); | 填充控制传输设置包所需信息 |
| int&nbsp;UsbRawFillControlRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawFillRequestData&nbsp;\*fillData); | 填充控制传输请求所需信息 |
| int&nbsp;UsbRawFillInterruptRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawFillRequestData&nbsp;\*fillData); | 填充中断传输请求所需信息 |
| int&nbsp;UsbRawFillIsoRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawFillRequestData&nbsp;\*fillData); | 填充同步传输（Isochronous&nbsp;Transfers）请求所需信息 |
| int&nbsp;UsbRawSubmitRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request); | 提交一个传输请求 |
| int&nbsp;UsbRawCancelRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request); | 取消一个传输请求 |
| int&nbsp;UsbRawHandleRequests(const&nbsp;UsbRawHandle<br/>\*devHandle); | 传输请求事件完成处理 |
| int32_t&nbsp;UsbRawGetDeviceDescriptor(const&nbsp;UsbRawDevice<br/>\*rawDev,&nbsp;struct<br/>UsbDeviceDescriptor&nbsp;\*desc); | 获取给定设备的USB设备描述符 |
| int32_t&nbsp;UsbRawClaimInterface(const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;int32_t<br/>interfaceNumber); | 声明给定设备句柄上的接口 |
| int32_t&nbsp;UsbRawReleaseInterface(const&nbsp;UsbRawHandle<br/>\*devHandle,&nbsp;in<br/>t&nbsp;interfaceNumber); | 释放之前声明的接口 |
| int32_t&nbsp;UsbRawResetDevice(const&nbsp;UsbRawHandle<br/>\*devHandle); | 复位设备 |
| struct&nbsp;UsbRawRequest&nbsp;\*UsbRawAllocRequest(const<br/>UsbRawHandle<br/>\*devHandle,&nbsp;int32_t&nbsp;isoPackets,&nbsp;int32_t&nbsp;length); | 分配一个带有指定数量的同步包描述符的传输请求 |
| int32_t&nbsp;UsbRawFreeRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request); | 释放之前分配的传输请求 |
| int32_t&nbsp;UsbRawFillBulkRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawFillRequestData&nbsp;\*fillData); | 填充批量传输请求所需信息 |
| int32_t&nbsp;UsbRawFillControlSetup(const&nbsp;unsigned&nbsp;char&nbsp;\*setup,<br/>const&nbsp;struct&nbsp;UsbControlRequestData&nbsp;\*requestData); | 填充控制传输设置包所需信息 |
| int32_t&nbsp;UsbRawFillControlRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawFillRequestData&nbsp;\*fillData); | 填充控制传输请求所需信息 |
| int32_t&nbsp;UsbRawFillInterruptRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawFillRequestData&nbsp;\*fillData); | 填充中断传输请求所需信息 |
| int32_t&nbsp;UsbRawFillIsoRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request,&nbsp;const&nbsp;UsbRawHandle&nbsp;\*devHandle,&nbsp;const&nbsp;struct<br/>UsbRawFillRequestData&nbsp;\*fillData); | 填充同步传输（Isochronous&nbsp;Transfers）请求所需信息 |
| int32_t&nbsp;UsbRawSubmitRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request); | 提交一个传输请求 |
| int32_t&nbsp;UsbRawCancelRequest(const&nbsp;struct&nbsp;UsbRawRequest<br/>\*request); | 取消一个传输请求 |
| int32_t&nbsp;UsbRawHandleRequests(const&nbsp;UsbRawHandle<br/>\*devHandle); | 传输请求事件完成处理 |
USB驱动模型Device侧开放的API接口功能，参考USB Device驱动模型图。
......@@ -89,19 +89,19 @@ USB驱动模型Device侧开放的API接口功能，参考USB Device驱动模型
| 接口名称 | 功能描述 |
| -------- | -------- |
| const&nbsp;struct&nbsp;UsbFnDevice&nbsp;\*UsbFnCreateDevice(const<br/>char&nbsp;\*udcName,&nbsp;const&nbsp;struct&nbsp;UsbFnDescriptorData<br/>\*descriptor); | 创建USB设备 |
| int&nbsp;UsbFnRemoveDevice(struct&nbsp;UsbFnDevice<br/>\*fnDevice); | 删除USB设备 |
| int32_t&nbsp;UsbFnRemoveDevice(struct&nbsp;UsbFnDevice<br/>\*fnDevice); | 删除USB设备 |
| const&nbsp;struct&nbsp;UsbFnDevice&nbsp;\*UsbFnGetDevice(const&nbsp;char<br/>\*udcName); | 获取USB设备 |
**表4** usbfn_interface.h
| 接口名称 | 功能描述 |
| -------- | -------- |
| int&nbsp;UsbFnStartRecvInterfaceEvent(struct<br/>UsbFnInterface&nbsp;\*interface,&nbsp;uint32_t&nbsp;eventMask,<br/>UsbFnEventCallback&nbsp;callback,&nbsp;void&nbsp;\*context); | 开始接受Event事件 |
| int&nbsp;UsbFnStopRecvInterfaceEvent(struct<br/>UsbFnInterface&nbsp;\*interface); | 停止接受Event事件 |
| int32_t&nbsp;UsbFnStartRecvInterfaceEvent(struct<br/>UsbFnInterface&nbsp;\*interface,&nbsp;uint32_t&nbsp;eventMask,<br/>UsbFnEventCallback&nbsp;callback,&nbsp;void&nbsp;\*context); | 开始接受Event事件 |
| int32_t&nbsp;UsbFnStopRecvInterfaceEvent(struct<br/>UsbFnInterface&nbsp;\*interface); | 停止接受Event事件 |
| UsbFnInterfaceHandle&nbsp;UsbFnOpenInterface(struct&nbsp;UsbFnInterface&nbsp;\*interface); | 打开一个接口 |
| int&nbsp;UsbFnCloseInterface(UsbFnInterfaceHandle&nbsp;handle); | 关闭一个接口 |
| int&nbsp;UsbFnGetInterfacePipeInfo(struct&nbsp;UsbFnInterface<br/>\*interface,&nbsp;uint8_t&nbsp;pipeId,&nbsp;struct&nbsp;UsbFnPipeInfo&nbsp;\*info); | 获取管道信息 |
| int&nbsp;UsbFnSetInterfaceProp(const&nbsp;struct&nbsp;UsbFnInterface<br/>\*interface,&nbsp;const&nbsp;char&nbsp;\*name,&nbsp;const&nbsp;char&nbsp;\*value); | 设置自定义属性 |
| int32_t&nbsp;UsbFnCloseInterface(UsbFnInterfaceHandle&nbsp;handle); | 关闭一个接口 |
| int32_t&nbsp;UsbFnGetInterfacePipeInfo(struct&nbsp;UsbFnInterface<br/>\*interface,&nbsp;uint8_t&nbsp;pipeId,&nbsp;struct&nbsp;UsbFnPipeInfo&nbsp;\*info); | 获取管道信息 |
| int32_t&nbsp;UsbFnSetInterfaceProp(const&nbsp;struct&nbsp;UsbFnInterface<br/>\*interface,&nbsp;const&nbsp;char&nbsp;\*name,&nbsp;const&nbsp;char&nbsp;\*value); | 设置自定义属性 |
**表5** usbfn_request.h
......@@ -109,10 +109,10 @@ USB驱动模型Device侧开放的API接口功能，参考USB Device驱动模型
| -------- | -------- |
| struct&nbsp;UsbFnRequest<br/>\*UsbFnAllocCtrlRequest(UsbFnInterfaceHandle&nbsp;handle,<br/>uint32_t&nbsp;len); | 申请一个控制请求 |
| struct&nbsp;UsbFnRequest&nbsp;\*UsbFnAllocRequest(UsbFnInterfaceHandle&nbsp;handle,<br/>uint8_t&nbsp;pipe,&nbsp;uint32_t&nbsp;len); | 申请一个数据请求 |
| int&nbsp;UsbFnFreeRequest(struct&nbsp;UsbFnRequest&nbsp;\*req); | 释放一个请求 |
| int&nbsp;UsbFnSubmitRequestAsync(struct&nbsp;UsbFnRequest<br/>\*req); | 发送异步请求 |
| int&nbsp;UsbFnSubmitRequestSync(struct&nbsp;UsbFnRequest<br/>\*req,&nbsp;uint32_t&nbsp;timeout); | 发送同步请求 |
| int&nbsp;UsbFnCancelRequest(struct&nbsp;UsbFnRequest&nbsp;\*req); | 取消请求 |
| int32_t&nbsp;UsbFnFreeRequest(struct&nbsp;UsbFnRequest&nbsp;\*req); | 释放一个请求 |
| int32_t&nbsp;UsbFnSubmitRequestAsync(struct&nbsp;UsbFnRequest<br/>\*req); | 发送异步请求 |
| int32_t&nbsp;UsbFnSubmitRequestSync(struct&nbsp;UsbFnRequest<br/>\*req,&nbsp;uint32_t&nbsp;timeout); | 发送同步请求 |
| int32_t&nbsp;UsbFnCancelRequest(struct&nbsp;UsbFnRequest&nbsp;\*req); | 取消请求 |
## 开发步骤
......@@ -218,6 +218,9 @@ root {
}
}
}
```
```cpp
#include "usb_serial.h"
#include "hdf_base.h"
......@@ -236,10 +239,10 @@ static struct UsbRequest *g_ctrlCmdRequest = NULL;
static bool g_acmReleaseFlag = false;
static uint8_t *g_acmReadBuffer = NULL;
...
static int SerialCtrlMsg(struct AcmDevice *acm, uint8_t request,
static int32_t SerialCtrlMsg(struct AcmDevice *acm, uint8_t request,
uint16_t value, void *buf, uint16_t len)
{
int ret;
int32_t ret;
uint16_t index = acm->intPipe->interfaceId;
struct UsbControlParams controlParams;
struct UsbRequestParams params;
......@@ -299,7 +302,7 @@ static struct UsbPipeInfo *EnumePipe(const struct AcmDevice *acm,
uint8_t interfaceIndex, UsbPipeType pipeType, UsbPipeDirection pipeDirection)
{
uint8_t i;
int ret;
int32_t ret;
struct UsbInterfaceInfo *info = NULL;
UsbInterfaceHandle *interfaceHandle = NULL;
if (pipeType == USB_PIPE_TYPE_CONTROL)
......@@ -408,11 +411,11 @@ error:
return HDF_FAILURE;
}
...
static int AcmAllocReadRequests(struct AcmDevice *acm)
static int32_t AcmAllocReadRequests(struct AcmDevice *acm)
{
int ret;
int32_t ret;
struct UsbRequestParams readParams;
for (int i = 0; i < ACM_NR; i++) {
for (int32_t i = 0; i < ACM_NR; i++) {
acm->readReq[i] = UsbAllocRequest(InterfaceIdToHandle(acm, acm->dataInPipe->interfaceId), 0, acm->readSize); // 分配待发送的readReq IO Request对象
if (!acm->readReq[i]) {
HDF_LOGE("readReq request failed");
......@@ -441,9 +444,9 @@ error:
return HDF_ERR_MALLOC_FAIL;
}
static int AcmAllocNotifyRequest(struct AcmDevice *acm)
static int32_t AcmAllocNotifyRequest(struct AcmDevice *acm)
{
int ret;
int32_t ret;
struct UsbRequestParams intParams = {};
acm->notifyReq = UsbAllocRequest(InterfaceIdToHandle(acm, acm->intPipe->interfaceId), 0, acm->intSize); // 分配待发送的中断IO Request对象
if (!acm->notifyReq) {
......@@ -474,7 +477,7 @@ error:
static void AcmReleaseInterfaces(struct AcmDevice *acm)
{
for (int i = 0; i < acm->interfaceCnt; i++) {
for (int32_t i = 0; i < acm->interfaceCnt; i++) {
if (acm->iface[i]) {
UsbReleaseInterface(acm->iface[i]);
acm->iface[i] = NULL;
......@@ -488,7 +491,7 @@ static void AcmReleaseInterfaces(struct AcmDevice *acm)
static int32_t AcmClaimInterfaces(struct AcmDevice *acm)
{
for (int i = 0; i < acm->interfaceCnt; i++) {
for (int32_t i = 0; i < acm->interfaceCnt; i++) {
acm->iface[i] = GetUsbInterfaceById((const struct AcmDevice *)acm, acm->interfaceIndex[i]); // 获取UsbInterface接口对象
if (acm->iface[i] == NULL) {
HDF_LOGE("%s: interface%d is null", __func__, acm->interfaceIndex[i]);
......@@ -511,7 +514,7 @@ static int32_t AcmClaimInterfaces(struct AcmDevice *acm)
static void AcmCloseInterfaces(struct AcmDevice *acm)
{
for (int i = 0; i < acm->interfaceCnt; i++) {
for (int32_t i = 0; i < acm->interfaceCnt; i++) {
if (acm->devHandle[i]) {
UsbCloseInterface(acm->devHandle[i]);
acm->devHandle[i] = NULL;
......@@ -525,7 +528,7 @@ static void AcmCloseInterfaces(struct AcmDevice *acm)
static int32_t AcmOpenInterfaces(struct AcmDevice *acm)
{
for (int i = 0; i < acm->interfaceCnt; i++) {
for (int32_t i = 0; i < acm->interfaceCnt; i++) {
if (acm->iface[i]) {
acm->devHandle[i] = UsbOpenInterface(acm->iface[i]); // 打开获取到的UsbInterface接口对象
if (acm->devHandle[i] == NULL) {
......@@ -606,7 +609,7 @@ static int32_t AcmAllocRequests(struct AcmDevice *acm)
return HDF_ERR_MALLOC_FAIL;
}
for (int i = 0; i < ACM_NW; i++) {
for (int32_t i = 0; i < ACM_NW; i++) {
struct AcmWb *snd = &(acm->wb[i]);
snd->request = UsbAllocRequest(InterfaceIdToHandle(acm, acm->dataOutPipe->interfaceId), 0, acm->writeSize); //分配待发送的IO Request对象
snd->instance = acm;
......@@ -789,7 +792,7 @@ HDF_INIT(g_usbSerialDriverEntry);
### Host RAW API驱动开发
```
```cpp
root {
module = "usb_pnp_device";
usb_pnp_config {
......@@ -836,7 +839,9 @@ root {
}
}
}
```
```cpp
#include "usb_serial_rawapi.h"
#include <unistd.h>
#include "osal_mem.h"
......@@ -858,11 +863,11 @@ struct OsalMutex g_stopIoLock;
static bool g_rawAcmReleaseFlag = false;
......
static int UsbGetConfigDescriptor(UsbRawHandle *devHandle, struct UsbRawConfigDescriptor **config)
static int32_t UsbGetConfigDescriptor(UsbRawHandle *devHandle, struct UsbRawConfigDescriptor **config)
{
UsbRawDevice *dev = NULL;
int activeConfig;
int ret;
int32_t activeConfig;
int32_t ret;
if (devHandle == NULL) {
HDF_LOGE("%s:%d devHandle is NULL",
......@@ -893,9 +898,9 @@ static int UsbGetConfigDescriptor(UsbRawHandle *devHandle, struct UsbRawConfigDe
return HDF_SUCCESS;
}
...
static int UsbAllocWriteRequests(struct AcmDevice *acm)
static int32_t UsbAllocWriteRequests(struct AcmDevice *acm)
{
int i;
int32_t i;
for (i = 0; i < ACM_NW; i++) {
struct AcmWb *snd = &acm->wb[i];
......@@ -965,13 +970,13 @@ error:
return HDF_FAILURE;
}
...
static int UsbAllocReadRequests(struct AcmDevice *acm)
static int32_t UsbAllocReadRequests(struct AcmDevice *acm)
{
struct UsbRawFillRequestData reqData;
int size = acm->dataInEp->maxPacketSize;
int ret;
int32_t size = acm->dataInEp->maxPacketSize;
int32_t ret;
for (int i = 0; i < ACM_NR; i++) {
for (int32_t i = 0; i < ACM_NR; i++) {
acm->readReq[i] = UsbRawAllocRequest(acm->devHandle, 0, size);
if (!acm->readReq[i]) {
HDF_LOGE("readReq request failed");
......@@ -996,11 +1001,11 @@ static int UsbAllocReadRequests(struct AcmDevice *acm)
return HDF_SUCCESS;
}
...
static int UsbAllocNotifyRequest(struct AcmDevice *acm)
static int32_t UsbAllocNotifyRequest(struct AcmDevice *acm)
{
struct UsbRawFillRequestData fillRequestData;
int size = acm->notifyEp->maxPacketSize;
int ret;
int32_t size = acm->notifyEp->maxPacketSize;
int32_t ret;
acm->notifyReq = UsbRawAllocRequest(acm->devHandle, 0, size);
if (!acm->notifyReq) {
......@@ -1226,9 +1231,8 @@ HDF_INIT(g_usbSerialRawDriverEntry);
USB ACM设备核心代码路径为drivers\peripheral\usb\gadget\function\acm\cdcacm.c。其使用示例如下所示，首先根据描述符创建设备，然后获取接口，打开接口，获取Pipe信息，接收Event事件，接着进行USB通信（读写等），设备卸载时候，关闭接口，停止Event接收，删除设备。
```
1、创建设备
```cpp
static int32_t AcmCreateFuncDevice(struct UsbAcmDevice *acm,
struct DeviceResourceIface *iface)
{
......@@ -1251,7 +1255,9 @@ if (useHcs == 0) {
}
...
}
```
2、获取接口，打开接口，获取Pipe信息
```cpp
static int32_t AcmParseEachPipe(struct UsbAcmDevice *acm, struct UsbAcmInterface *iface)
{
...
......@@ -1277,8 +1283,11 @@ static int32_t AcmParseEachIface(struct UsbAcmDevice *acm, struct UsbFnDevice *f
}
return HDF_SUCCESS;
}
```
3、接收Event事件
static int32_t AcmAllocCtrlRequests(struct UsbAcmDevice *acm, int num)
```cpp
static int32_t AcmAllocCtrlRequests(struct UsbAcmDevice *acm, int32_t num)
{
...
req = UsbFnCtrlRequestAlloc(acm->ctrlIface.handle,
......@@ -1292,7 +1301,9 @@ static int32_t AcmDriverInit(struct HdfDeviceObject *device)
ret = UsbFnInterfaceStartRecvEvent(acm->ctrlIface.fn, 0xff, UsbAcmEventCallback, acm);
...
}
```
4、进行USB通信（读写等）
```cpp
static int32_t AcmSendNotifyRequest(struct UsbAcmDevice *acm, uint8_t type,
uint16_t value, void *data, uint32_t length)
{
......@@ -1301,7 +1312,9 @@ static int32_t AcmSendNotifyRequest(struct UsbAcmDevice *acm, uint8_t type,
ret = UsbFnRequestSubmitAsync(req);
...
}
```
5、关闭接口，停止Event接收，删除设备
```cpp
static int32_t AcmReleaseFuncDevice(struct UsbAcmDevice *acm)
{
int32_t ret;
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或