From 5e0a9c673e2a874ac099736f68fb63c5f4b1c8a4 Mon Sep 17 00:00:00 2001 From: tzb Date: Wed, 17 May 2023 06:06:49 +0000 Subject: [PATCH] doc of driverExtension Signed-off-by: tzb --- .../driverextensionability.md | 129 +++++++++++ ...apis-app-ability-driverExtensionAbility.md | 208 ++++++++++++++++++ ...nner-application-driverExtensionContext.md | 45 ++++ 3 files changed, 382 insertions(+) create mode 100644 zh-cn/application-dev/application-models/driverextensionability.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-app-ability-driverExtensionAbility.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-inner-application-driverExtensionContext.md diff --git a/zh-cn/application-dev/application-models/driverextensionability.md b/zh-cn/application-dev/application-models/driverextensionability.md new file mode 100644 index 0000000000..5078f9a5f3 --- /dev/null +++ b/zh-cn/application-dev/application-models/driverextensionability.md @@ -0,0 +1,129 @@ +# DriverExtensionAbility + +[DriverExtensionAbility](../reference/apis/js-apis-app-ability-driverExtensionAbility.md)是DRIVER类型的ExtensionAbility组件，提供驱动相关扩展框架。对于部分设备，支持插入外接的硬件模块来扩展设备能力， 此时可以以应用方式安装该硬件模块的驱动程序。通过DriverExtensionAbility可实现此类应用的开发。 + + +[DriverExtensionAbility](../reference/apis/js-apis-app-ability-driverExtensionAbility.md)可以通过DriverExtensionManager被应用绑定，并根据应用的请求信息在后台处理相关事务。 +每个类型的ExtensionAbility都有自己的Context，DriverExtensionAbility通过[DriverExtensionContext](../reference/apis/js-apis-inner-application-driverExtensionContext.md)提供相关能力。 + +本章节将从如下场景来介绍DriverExtensionAbility的基本使用。 + +- [DriverExtensionAbility](#driverextensionability) + - [开发步骤](#开发步骤) + +## 开发步骤 + +开发者在实现一个驱动时，需要在DevEco Studio工程中手动新建一个DriverExtensionAbility，具体步骤如下。 + +1. 在工程Module对应的ets目录下，右键选择“New > Directory”，新建一个目录并命名为driverextability。 + +2. 在driverextability目录，右键选择“New > TypeScript File”，新建一个TypeScript文件并命名为DriverExtAbility.ts。 + +3. 打开DriverExtAbility.ts文件，导入[RPC通信模块](../reference/apis/js-apis-rpc.md)，重载onRemoteMessageRequest()方法，接收应用传递过来的消息，并将处理的结果返回给应用。REQUEST_VALUE用于校验应用发送的服务请求码。 + + ```ts + import rpc from '@ohos.rpc'; + + const REQUEST_CODE = 99; + + class StubTest extends rpc.RemoteObject { + constructor(des) { + super(des); + } + + // 接收应用传递过来的消息处理，以及将处理的结果返回给应用 + onRemoteMessageRequest(code, data, reply, option) { + if (code === REQUEST_CODE) { + // 接收应用传递过来的数据 + // 应用使用多次调用data.writeInt()写入多个数据时，驱动可以通过多次调用data.readInt()方法接收对应的数据 + let optFir = data.readInt(); + let optSec = data.readInt(); + // 驱动将数据的处理结果返回给应用 + // 示例中为接收了两个数据，并将两个数据的求和返回给应用 + reply.writeInt(optFir + optSec); + } + return true; + } + } + ``` + + +4. 在DriverExtAbility.ts文件中，增加导入[DriverExtensionAbility](../reference/apis/js-apis-app-ability-driverExtensionAbility.md)的依赖包，该包提供了onInit()、onRelease()、onConnect()和onDisconnect()生命周期回调，自定义类继承[DriverExtensionAbility](../reference/apis/js-apis-app-ability-driverExtensionAbility.md)并根据需要重写需要的生命周期回调。 + + ```ts + import DriverExtensionAbility from '@ohos.app.ability.DriverExtensionAbility'; + import rpc from '@ohos.rpc'; + + const TAG: string = '[Example].[Entry].[DriverExtAbility]'; + const REQUEST_CODE = 99; + + class StubTest extends rpc.RemoteObject { + // ... + } + + export default class DriverExtAbility extends DriverExtensionAbility { + onInit(want) { + console.info(TAG, `onInit, want: ${want.abilityName}`); + } + + onRelease() { + console.info(TAG, `onRelease, want: ${want.abilityName}`); + } + + onConnect(want) { + console.info(TAG, `onConnect, want: ${want.abilityName}`); + return new StubTest("test"); + } + + onDisconnect(want) { + console.info(TAG, `onDisconnect, want: ${want.abilityName}`); + } + + onDump() { + console.info(TAG, `onDump, params:` + JSON.stringify(params)); + return ['params']; + } + } + ``` + +5. 在工程Module对应的[module.json5配置文件](../quick-start/module-configuration-file.md)中注册DriverExtensionAbility，type标签需要设置为“driver”，srcEntry标签表示当前ExtensionAbility组件所对应的代码路径。 + + ```json + { + "module": { + // ... + "extensionAbilities": [ + { + "name": "DriverExtAbility", + "icon": "$media:icon", + "description": "driver", + "type": "driver", + "exported": true, + "srcEntry": "./ets/driverextability/DriverExtAbility.ts", + "metadata": [ + { + "name": "bus", // 必填项，所属总线 + "value": "USB", + }, + { + "name": "desc", // 必填项，必要的驱动描述 + "value": "the sample of driverExtensionAbility", + }, + { + "name": "vendor", // 必填项，驱动厂商名称 + "value": "string", + }, + { + "name": "vid", // 支持 USB vendor id 列表，用逗号分隔，不可为空 + "value": "string, string", + }, + { + "name": "pid", // 支持的 USB product id 列表，用逗号分隔，不可为空 + "value": "string, string", + } + ] + } + ] + } + } + ``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-driverExtensionAbility.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-driverExtensionAbility.md new file mode 100644 index 0000000000..90aa19d4cc --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-driverExtensionAbility.md @@ -0,0 +1,208 @@ +# @ohos.app.ability.DriverExtensionAbility (DriverExtensionAbility) + +DriverExtensionAbility模块提供驱动相关扩展能力，提供驱动创建、销毁、连接、断开等生命周期回调。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> 本模块接口仅可在Stage模型下使用。 + +## 导入模块 + +```ts +import DriverExtension from '@ohos.app.ability.DriverExtensionAbility'; +``` + +## 权限 + +无 + +## 属性 + +**系统能力**：SystemCapability.Driver.ExternalDevice + +**系统API**: 此接口为系统接口，三方应用不支持调用。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| context | [DriverExtensionContext](js-apis-inner-application-driverExtensionContext.md) | 是 | 否 | DriverExtension的上下文环境，继承自ExtensionContext。 | + + +## DriverExtensionAbility.onInit + +onInit(want: Want): void; + +Extension生命周期回调，在创建时回调，执行初始化业务逻辑操作。 + +**系统能力**：SystemCapability.Driver.ExternalDevice + +**系统API**: 此接口为系统接口，三方应用不支持调用。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-app-ability-want.md) | 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 | + +**示例：** + + ```ts + class DriverExt extends DriverExtension { + onInit(want) { + console.log('onInit, want: ${want.abilityName}'); + } + } + ``` + + +## DriverExtensionAbility.onRelease + +onRelease(): void; + +Extension生命周期回调，在销毁时回调，执行资源清理等操作。 + +**系统能力**：SystemCapability.Driver.ExternalDevice + +**系统API**: 此接口为系统接口，三方应用不支持调用。 + +**示例：** + + ```ts + class DriverExt extends DriverExtension { + onRelease() { + console.log('onRelease'); + } + } + ``` + + +## DriverExtensionAbility.onConnect + +onConnect(want: Want): rpc.RemoteObject | Promise; + +Extension生命周期回调，如果是connectAbility拉起的服务，会在onCreate之后回调。返回一个RemoteObject对象，用于客户端和服务端进行通信。 + +**系统能力**：SystemCapability.Driver.ExternalDevice + +**系统API**: 此接口为系统接口，三方应用不支持调用。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-app-ability-want.md)| 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 | + +**返回值：** + +| 类型 | 说明 | +| -------- | -------- | +| rpc.RemoteObject | 一个RemoteObject对象，用于客户端和服务端进行通信。 | + +**示例：** + + ```ts + import rpc from '@ohos.rpc'; + class StubTest extends rpc.RemoteObject{ + constructor(des) { + super(des); + } + onRemoteRequest(code, data, reply, option) { + } + } + class DriverExt extends DriverExtension { + onConnect(want) { + console.log('onConnect , want: ${want.abilityName}'); + return new StubTest('test'); + } + } + ``` + +如果生成返回值RemoteObject依赖一个异步接口，可以使用异步生命周期： + + ```ts +import rpc from '@ohos.rpc'; +class StubTest extends rpc.RemoteObject{ + constructor(des) { + super(des); + } + onRemoteRequest(code, data, reply, option) { + } +} +async function getDescriptor() { + // 调用异步函数... + return "asyncTest" +} +class DriverExt extends DriverExtension { + async onConnect(want) { + console.log(`onConnect , want: ${want.abilityName}`); + let descriptor = await getDescriptor(); + return new StubTest(descriptor); + } +} + ``` + +## DriverExtensionAbility.onDisconnect + +onDisconnect(want: Want): void | Promise\; + +Extension的生命周期回调，客户端执行断开连接服务时回调。 + +**系统能力**：SystemCapability.Driver.ExternalDevice + +**系统API**: 此接口为系统接口，三方应用不支持调用。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| want |[Want](js-apis-app-ability-want.md)| 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 | + +**示例：** + + ```ts + class DriverExt extends DriverExtension { + onDisconnect(want) { + console.log('onDisconnect, want: ${want.abilityName}'); + } + } + ``` + +在执行完onDisconnect生命周期回调后，应用可能会退出，从而可能导致onDisconnect中的异步函数未能正确执行，比如异步写入数据库。可以使用异步生命周期，以确保异步onDisconnect完成后再继续后续的生命周期。 + + ```ts +class DriverExt extends DriverExtension { + async onDisconnect(want) { + console.log('onDisconnect, want: ${want.abilityName}'); + // 调用异步函数... + } +} + ``` + + +## DriverExtensionAbility.onDump + +onDump(params: Array\): Array\; + +转储客户端信息时调用。 + +**系统能力**：SystemCapability.Driver.ExternalDevice + +**系统API**: 此接口为系统接口，三方应用不支持调用。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| params | Array\ | 是 | 表示命令形式的参数。| + +**示例：** + + ```ts + class DriverExt extends DriverExtension { + onDump(params) { + console.log('dump, params: ${JSON.stringify(params)}'); + return ['params']; + } + } + ``` + diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-driverExtensionContext.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-driverExtensionContext.md new file mode 100644 index 0000000000..2abc759d54 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-driverExtensionContext.md @@ -0,0 +1,45 @@ +# DriverExtensionContext + +DriverExtensionContext模块是DriverExtensionAbility的上下文环境，继承自ExtensionContext。 + +DriverExtensionContext模块提供DriverExtensionAbility实现中需要主动发起的操作。 + +> **说明：** +> +> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> - 本模块接口仅可在Stage模型下使用。 + +## 导入模块 + +```ts +import common from '@ohos.app.ability.common'; +``` + +## 使用说明 + +在使用DriverExtensionContext的功能前，需要通过DriverExtensionAbility子类实例获取。 + +```ts + import DriverExtensionAbility from '@ohos.app.ability.DriverExtensionAbility'; + + let context; + class EntryAbility extends DriverExtensionAbility { + onInit() { + context = this.context; // 获取DriverExtensionContext + } + } +``` + +## DriverExtensionContext.updateDriverState + +updateDriverState(): void; + +驱动状态上报。预留接口，暂不提供具体功能。 + +**系统能力**：SystemCapability.Driver.ExternalDevice + +**示例：** + + ```ts + this.context.updateDriverState() ; + ``` -- GitLab