doc of driverExtension

Signed-off-by: N tzb <tangzebiao@huawei.com>

doc of driverExtension
Signed-off-by: N tzb <tangzebiao@huawei.com>
5e0a9c67 · tzb · 566e901c · 5e0a9c67 · 5e0a9c67 · 5e0a9c67
3 changed file
--- a/zh-cn/application-dev/application-models/driverextensionability.md
+++ b/zh-cn/application-dev/application-models/driverextensionability.md
+# 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 &gt; Directory”，新建一个目录并命名为driverextability。
+
+2. 在driverextability目录，右键选择“New &gt; 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
--- 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
+# @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<rpc.RemoteObject>;
+
+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\<void>;
+
+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\<string>): Array\<string>;
+
+转储客户端信息时调用。
+
+**系统能力**：SystemCapability.Driver.ExternalDevice
+
+**系统API**: 此接口为系统接口，三方应用不支持调用。
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| params | Array\<string> | 是 | 表示命令形式的参数。|
+
+**示例：**
+    
+  ```ts
+  class DriverExt extends DriverExtension {
+      onDump(params) {
+          console.log('dump, params: ${JSON.stringify(params)}');
+          return ['params'];
+      }
+  }
+  ```
+
--- 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
+# 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() ;
+  ```