diff --git a/CODEOWNERS b/CODEOWNERS index f395d69420381a4e61268211787acd0cff417ec5..52fd5a5404d2809b3e021c09d932c9f4a9cc050f 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -85,6 +85,7 @@ zh-cn/device-dev/subsystems/subsys-security-sigverify.md @duangavin123_admin zh-cn/device-dev/subsystems/subsys-security-rightmanagement.md @duangavin123_admin zh-cn/device-dev/subsystems/subsys-security-communicationverify.md @duangavin123_admin zh-cn/device-dev/subsystems/subsys-security-devicesecuritylevel.md @duangavin123_admin +zh-cn/device-dev/subsystems/subsys-security-huks-guide.md @Austin23 zh-cn/device-dev/subsystems/subsys-boot-appspawn.md @Austin23 zh-cn/device-dev/subsystems/subsys-boot-bootstrap.md @Austin23 zh-cn/device-dev/subsystems/subsys-boot-faqs.md @Austin23 @@ -348,4 +349,6 @@ zh-cn/application-dev/napi/napi-guidelines.md @RayShih zh-cn/application-dev/napi/drawing-guidelines.md @ge-yafang zh-cn/application-dev/napi/rawfile-guidelines.md @HelloCrease zh-cn/application-dev/reference/apis/js-apis-buffer.md @zengyawen -zh-cn/application-dev/reference/js-service-widget-ui @HelloCrease \ No newline at end of file +zh-cn/application-dev/reference/js-service-widget-ui @HelloCrease +zh-cn/application-dev/website.md @zengyawen +zh-cn/application-dev/faqs/ @zengyawen \ No newline at end of file diff --git a/en/application-dev/ability/stage-call.md b/en/application-dev/ability/stage-call.md index aaa9a9918345c52015969245c3bbba3efbb81048..6b5823e76db2c95190111a55b9d2ef43ddd2d946 100644 --- a/en/application-dev/ability/stage-call.md +++ b/en/application-dev/ability/stage-call.md @@ -19,7 +19,7 @@ The table below describes the ability call APIs. For details, see [Ability](../r |API|Description| |:------|:------| |startAbilityByCall(want: Want): Promise\|Obtains the caller interface of the specified ability and, if the specified ability is not running, starts the ability in the background.| -|on(method: string, callback: CaleeCallBack): void|Callback invoked when the callee registers a method.| +|on(method: string, callback: CalleeCallBack): void|Callback invoked when the callee registers a method.| |off(method: string): void|Callback invoked when the callee deregisters a method.| |call(method: string, data: rpc.Sequenceable): Promise\|Sends agreed sequenceable data to the callee.| |callWithResult(method: string, data: rpc.Sequenceable): Promise\|Sends agreed sequenceable data to the callee and returns the agreed sequenceable data.| @@ -28,7 +28,7 @@ The table below describes the ability call APIs. For details, see [Ability](../r ## How to Develop > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
-> The sample code snippets provided in the **How to Develop** section are used to show specific development steps. They may not be able to run independently. For details about the complete project code, see [Samples](#samples). +> The sample code snippets provided in the **How to Develop** section are used to show specific development steps. They may not be able to run independently. ### Creating a Callee For the callee, implement the callback to receive data and the methods to marshal and unmarshal data. When data needs to be received, use the **on** API to register a listener. When data does not need to be received, use the **off** API to deregister the listener. 1. Configure the ability startup mode. diff --git a/en/application-dev/database/database-distributedobject-guidelines.md b/en/application-dev/database/database-distributedobject-guidelines.md index dde1feb495e9827ab1f0fd1fad903f71acb9cbb3..cfde2b66f2a3094355d6166bcaa4fb17856fbfaf 100644 --- a/en/application-dev/database/database-distributedobject-guidelines.md +++ b/en/application-dev/database/database-distributedobject-guidelines.md @@ -17,7 +17,7 @@ Call **createDistributedObject()** to create a distributed data object instance. **Table 1** API for creating a distributed data object instance | Package| API| Description| | -------- | -------- | -------- | -| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | Creates a distributed data object instance for data operations.
- **source**: attributes of the **distributedObject** set.
- **DistributedObject**: returns the distributed object created.| +| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | Creates a distributed data object instance for data operations.
- **source**: attributes of the **distributedObject** set.
- **DistributedObject**: returns the distributed object created.| ### Generating a Session ID @@ -35,16 +35,16 @@ Call **setSessionId()** to set a session ID for a distributed data object. The s **Table 3** API for setting a session ID | Class| API| Description| | -------- | -------- | -------- | -| DistributedDataObject | setSessionId(sessionId?: string): boolean | Sets a session ID for distributed data objects.
**sessionId**: session ID of a distributed object in a trusted network. To remove a distributed data object from the network, set this parameter to "" or leave it empty.| +| DistributedDataObject | setSessionId(sessionId?: string): boolean | Sets a session ID for distributed data objects.
**sessionId**: session ID of a distributed object in a trusted network. To remove a distributed data object from the network, set this parameter to "" or leave it empty.| ### Observing Data Changes Call **on()** to subscribe to data changes of a distributed data object. When the data changes, a callback will be invoked to return the data changes. You can use **off()** to unsubscribe from the data changes. **Table 4** APIs for observing data changes of a distributed data object -| Class| API| Description| +| Class| API| Description| | -------- | -------- | -------- | -| DistributedDataObject| on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void | Subscribes to data changes.| +| DistributedDataObject| on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void | Subscribes to data changes.| | DistributedDataObject| off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void | Unsubscribes from data changes. **Callback**: specifies callback used to return changes of the distributed data object. If this parameter is not specified, all callbacks related to data changes will be unregistered.| ### Observing Online or Offline Status @@ -85,7 +85,11 @@ The following example shows how to implement a distributed data object synchroni ```js import distributedObject from '@ohos.data.distributedDataObject'; ``` -2. Request the permission.
Add the required permission in the **config.json** file. The sample code is as follows: + +2. Request the permission. + + Add the required permission in the **config.json** file. The sample code is as follows: + ``` { "module": { @@ -97,10 +101,11 @@ The following example shows how to implement a distributed data object synchroni } } ``` - This permission must also be authorized by the user through a dialog box when the application is started for the first time. The sample code is as follows: - ```js + This permission must also be authorized by the user through a dialog box when the application is started for the first time. The sample code is as follows: + + ``` import featureAbility from '@ohos.ability.featureAbility'; - + function grantPermission() { console.info('grantPermission'); let context = featureAbility.getContext(); @@ -108,11 +113,13 @@ The following example shows how to implement a distributed data object synchroni console.info(`result.requestCode=${result.requestCode}`) }) - console.info('end grantPermission'); + console.info('end grantPermission'); } grantPermission(); ``` - + + + 3. Obtain a distributed data object instance. The sample code is as follows: @@ -130,7 +137,7 @@ The following example shows how to implement a distributed data object synchroni ```js // Local object var local_object = distributedObject.createDistributedObject({name:"jack", age:18, isVis:true, - parent:{mother:"jack mom",father:"jack Dad"},list:[{mother:"jack mom"}, {father:"jack Dad"}]}); + parent:{mother:"jack mom", father:"jack Dad"}, list:[{mother:"jack mom"}, {father:"jack Dad"}]}); local_object.setSessionId(sessionId); // Remote object @@ -140,8 +147,10 @@ The following example shows how to implement a distributed data object synchroni // After learning that the device goes online, the remote object synchronizes data. That is, name changes to jack and age to 18. ``` -5. Observe the data changes of the distributed data object.
You can subscribe to data changes of the peer object. When the data in the peer object changes, a callback will be called to return the data changes. +5. Observe the data changes of the distributed data object. + You can subscribe to data changes of the peer object. When the data in the peer object changes, a callback will be called to return the data changes. + The sample code is as follows: ```js @@ -152,26 +161,32 @@ The following example shows how to implement a distributed data object synchroni changeData.forEach(element => { console.info("changed !" + element + " " + local_object[element]); }); - } + } } - + // To refresh the page in changeCallback, correctly bind (this) to the changeCallback. local_object.on("change", this.changeCallback.bind(this)); ``` -6. Modify object attributes.
The object attributes support basic data types (such as number, Boolean, and string) and complex data types (array and nested basic types). - +6. Modify object attributes. + + The object attributes support basic data types (such as number, Boolean, and string) and complex data types (array and nested basic types). + The sample code is as follows: ```js local_object.name = "jack"; local_object.age = 19; local_object.isVis = false; - local_object.parent = {mother:"jack mom",father:"jack Dad"}; + local_object.parent = {mother:"jack mom", father:"jack Dad"}; local_object.list = [{mother:"jack mom"}, {father:"jack Dad"}]; ``` - > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
- > For the distributed data object of the complex type, only the root attribute can be modified. The subordinate attributes cannot be modified. Example: + > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** + > + > For the distributed data object of the complex type, only the root attribute can be modified. The subordinate attributes cannot be modified. + + Example: + ```js // Supported modification. local_object.parent = {mother:"mom", father:"dad"}; @@ -179,13 +194,18 @@ The following example shows how to implement a distributed data object synchroni local_object.parent.mother = "mom"; ``` -7. Access the distributed data object.
Obtain the distributed data object attribute, which is the latest data on the network. - +7. Access the distributed data object. + + Obtain the distributed data object attribute, which is the latest data on the network. + The sample code is as follows: ```js console.info("name " + local_object["name"]); ``` -8. Unsubscribe from data changes.
You can specify the callback to unregister. If you do not specify the callback, all data change callbacks of the distributed data object will be unregistered. + +8. Unsubscribe from data changes. + + You can specify the callback to unregister. If you do not specify the callback, all data change callbacks of the distributed data object will be unregistered. The sample code is as follows: ```js @@ -194,6 +214,7 @@ The following example shows how to implement a distributed data object synchroni // Unregister all data change callbacks. local_object.off("change"); ``` + 9. Subscribe to the status (online/offline) changes of the distributed data object. A callback will be invoked to report the status change when the target distributed data object goes online or offline. The sample code is as follows: ```js @@ -207,58 +228,62 @@ The following example shows how to implement a distributed data object synchroni 10. Save a distributed data object and revoke the data saving operation. - Callback - - ```js - // Save a distributed data object. - local_object.save("local", (result, data)=>{ - console.log("save callback"); - console.info("save sessionId " + data.sessionId); - console.info("save version " + data.version); - console.info("save deviceId " + data.deviceId); - }); - // Revoke the data saving operation. - local_object.revokeSave((result, data) =>{ - console.log("revokeSave callback"); - console.info("revokeSave sessionId " + data.sessionId); - }); - ``` - - Promise - ```js - // Save a distributed data object. - g_object.save("local").then((result)=>{ - console.info("save sessionId " + result.sessionId); - console.info("save version " + result.version); - console.info("save deviceId " + result.deviceId); - }, (result)=>{ - console.info("save local failed."); - }); - // Revoke the data saving operation. - g_object.revokeSave().then((result)=>{ - console.info("revokeSave success."); - }, (result)=>{ - console.info("revokeSave failed."); - }); - ``` -11. Unsubscribe from the status changes of the distributed data object.
You can specify the callback to unregister. If you do not specify the callback, this API unregisters all callbacks of this distributed data object. + + ``` + ​```js + // Save a distributed data object. + local_object.save("local", (result, data) => { + console.log("save callback"); + console.info("save sessionId " + data.sessionId); + console.info("save version " + data.version); + console.info("save deviceId " + data.deviceId); + }); + // Revoke the data saving operation. + local_object.revokeSave((result, data) => { + console.log("revokeSave callback"); + console.info("revokeSave sessionId " + data.sessionId); + }); + ​``` + ``` + + - Promise + + ``` + ​```js + // Save a distributed data object. + g_object.save("local").then((result) => { + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); + }, (result)=>{ + console.info("save local failed."); + }); + // Revoke the data saving operation. + g_object.revokeSave().then((result) => { + console.info("revokeSave success."); + }, (result)=>{ + console.info("revokeSave failed."); + }); + ​``` + ``` + + + +11. Unsubscribe from the status changes of the distributed data object. + + You can specify the callback to unregister. If you do not specify the callback, this API unregisters all callbacks of this distributed data object. The sample code is as follows: - ```js + ```js // Unregister the specified status change callback. local_object.off("status", this.statusCallback); // Unregister all status change callbacks. local_object.off("status"); - ``` + ``` + 12. Remove a distributed data object from the synchronization network. Data changes on the local object will not be synchronized to the removed distributed data object. The sample code is as follows: ```js local_object.setSessionId(""); ``` -## Development Example - -The following example is provided for you to better understand the development of distributed data objects: - -- [Distributed Notepad](https://gitee.com/openharmony/distributeddatamgr_objectstore/tree/master/samples/distributedNotepad) - - -When an event of the Notepad app occurs on a device, such as a note is added, the tile or content of a note is changed, or the event list is cleared, the change will be synchronized to other devices in the trusted network. diff --git a/en/application-dev/database/database-mdds-guidelines.md b/en/application-dev/database/database-mdds-guidelines.md index c5608c6eabd526c38a87bd3907fba89fb1a11629..dd1594215a10d1c93c9825444253484ed8956e05 100644 --- a/en/application-dev/database/database-mdds-guidelines.md +++ b/en/application-dev/database/database-mdds-guidelines.md @@ -6,22 +6,20 @@ The Distributed Data Service (DDS) implements synchronization of application dat ## Available APIs - For details about the APIs related to distributed data, see [Distributed Data Management](../reference/apis/js-apis-distributed-data.md). -The table below describes the APIs provided by the OpenHarmony DDS module. **Table 1** APIs provided by the DDS -| Category | API | Description | -| ------------ | ------------- | ------------- | -| Creating a distributed database| createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void
createKVManager(config: KVManagerConfig): Promise<KVManager> | Creates a **KVManager** object for database management.| -| Obtaining a distributed KV store| getKVStore<T extends KVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void
getKVStore<T extends KVStore>(storeId: string, options: Options): Promise<T> | Obtains the KV store with the specified **Options** and **storeId**.| -| Managing data in a distributed KV store| put(key: string, value: Uint8Array \| string \| number \| boolean, callback: AsyncCallback<void>): void
put(key: string, value: Uint8Array \| string \| number \| boolean): Promise<void> | Inserts and updates data.| -| Managing data in a distributed KV store| delete(key: string, callback: AsyncCallback<void>): void
delete(key: string): Promise<void> | Deletes data. | -| Managing data in a distributed KV store| get(key: string, callback: AsyncCallback<Uint8Array \| string \| boolean \| number>): void
get(key: string): Promise<Uint8Array \| string \| boolean \| number> | Queries data. | -| Subscribing to changes in the distributed data| on(event: 'dataChange', type: SubscribeType, observer: Callback<ChangeNotification>): void
on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void | Subscribes to data changes in the KV store.| -| Synchronizing data across devices| sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void | Triggers database synchronization in manual mode. | +| API | Description | +| ------------------------------------------------------------ | ----------------------------------------------- | +| createKVManager(config:KVManagerConfig,callback:AsyncCallback<KVManager>):void
createKVManager(config:KVManagerConfig):Promise<KVManager> | Creates a **KVManager** object for database management.| +| getKVStore<TextendsKVStore>(storeId:string,options:Options,callback:AsyncCallback<T>):void
getKVStore<TextendsKVStore>(storeId:string,options:Options):Promise<T> | Obtains a KV store with the specified **Options** and **storeId**.| +| put(key:string,value:Uint8Array\|string\|number\|boolean,callback:AsyncCallback<void>):void
put(key:string,value:Uint8Array\|string\|number\|boolean):Promise<void> | Inserts and updates data. | +| delete(key:string,callback:AsyncCallback<void>):void
delete(key:string):Promise<void> | Deletes data. | +| get(key:string,callback:AsyncCallback<Uint8Array\|string\|boolean\|number>):void
get(key:string):Promise<Uint8Array\|string\|boolean\|number> | Queries data. | +| on(event:'dataChange',type:SubscribeType,observer:Callback<ChangeNotification>):void
on(event:'syncComplete',syncCallback:Callback<Array<[string,number]>>):void | Subscribes to data changes in the KV store. | +| sync(deviceIdList:string[],mode:SyncMode,allowedDelayMs?:number):void | Triggers database synchronization in manual mode. | @@ -36,11 +34,14 @@ The following uses a single KV store as an example to describe the development p ``` 2. Create a **KvManager** instance based on the specified **KvManagerConfig** object. + (1) Create a **KvManagerConfig** object based on the application context. - (2) Create a **KvManager** instance. + (2) Create a **KvManager** instance. + The sample code is as follows: - ```js + + ``` let kvManager; try { const kvManagerConfig = { @@ -62,9 +63,12 @@ The following uses a single KV store as an example to describe the development p console.log("An unexpected error occurred. Error:" + e); } ``` - + + 3. Create and obtain a single KV store. + (1) Declare the ID of the single KV store to create. + (2) Create a single KV store. You are advised to disable automatic synchronization (**autoSync:false**) and call **sync** when a synchronization is required. The sample code is as follows: @@ -92,8 +96,9 @@ The following uses a single KV store as an example to describe the development p } ``` - > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
- > For data synchronization between networked devices, you are advised to open the distributed KV store during application startup to obtain the database handle. With this database handle (**kvStore** in this example), you can perform operations, such as inserting data into the KV store, without creating the KV store repeatedly during the lifecycle of the handle. + > **NOTE** + > + > For data synchronization between networked devices, you are advised to open the distributed KV store during application startup to obtain the database handle. With this database handle (`kvStore` in this example), you can perform operations, such as inserting data into the KV store, without creating the KV store repeatedly during the lifecycle of the handle. 4. Subscribe to changes in the distributed data.
The following is the sample code for subscribing to the data changes of a single KV store: @@ -104,7 +109,9 @@ The following uses a single KV store as an example to describe the development p ``` 5. Write data to the single KV store. + (1) Construct the key and value to be written into the single KV store. + (2) Write key-value pairs into the single KV store. The following is the sample code for writing key-value pairs of the string type into the single KV store: @@ -126,7 +133,9 @@ The following uses a single KV store as an example to describe the development p ``` 6. Query data in the single KV store. + (1) Construct the key to be queried from the single KV store. + (2) Query data from the single KV store. The following is the sample code for querying data of the string type from the single KV store: @@ -152,7 +161,11 @@ The following uses a single KV store as an example to describe the development p 7. Synchronize data to other devices.
Select the devices in the same network and the synchronization mode to synchronize data. - The following is the sample code for data synchronization in a single KV store. **deviceIds** can be obtained by deviceManager by calling **getTrustedDeviceListSync()**, and **1000** indicates that the maximum delay time is 1000 ms. + > **NOTE** + > + > The APIs of the `deviceManager` module are system interfaces. + + The following is the sample code for synchronizing data in a single KV store: ```js import deviceManager from '@ohos.distributedHardware.deviceManager'; @@ -161,7 +174,7 @@ The following uses a single KV store as an example to describe the development p deviceManager.createDeviceManager("bundleName", (err, value) => { if (!err) { devManager = value; - // Obtain deviceIds. + // deviceIds is obtained by deviceManager by calling getTrustedDeviceListSync(). let deviceIds = []; if (devManager != null) { var devices = devManager.getTrustedDeviceListSync(); @@ -170,6 +183,7 @@ The following uses a single KV store as an example to describe the development p } } try{ + // 1000 indicates that the maximum delay is 1000 ms. kvStore.sync(deviceIds, distributedData.SyncMode.PUSH_ONLY, 1000); }catch (e) { console.log("An unexpected error occurred. Error:" + e); @@ -177,7 +191,3 @@ The following uses a single KV store as an example to describe the development p } }); ``` -## Samples -The following samples are provided to help you better understand the distributed data development: -- [`KvStore`: Distributed Database (eTS) (API8)](https://gitee.com/openharmony/app_samples/tree/master/data/Kvstore) -- [Distributed Database](https://gitee.com/openharmony/codelabs/tree/master/Data/JsDistributedData) diff --git a/en/application-dev/database/database-relational-guidelines.md b/en/application-dev/database/database-relational-guidelines.md index 3a85b9ceab78ff6eadecd5bbb9c572977a8f7da1..f6c7395339d66cb1c79bf71d424c15072f77f1b6 100644 --- a/en/application-dev/database/database-relational-guidelines.md +++ b/en/application-dev/database/database-relational-guidelines.md @@ -7,7 +7,7 @@ A relational database (RDB) store allows you to operate local data with or witho ## Available APIs -For details about RDB APIs, see [Relational Database](../reference/apis/js-apis-data-rdb.md). +Most of the RDB store APIs are asynchronous interfaces, which can use a callback or promise to return the result. This document uses the promise-based APIs as an example. For details about the APIs, see [Relational Database](../reference/apis/js-apis-data-rdb.md). ### Creating or Deleting an RDB Store @@ -15,51 +15,48 @@ The table below describes the APIs available for creating and deleting an RDB st **Table 1** APIs for creating and deleting an RDB store -| API| Description| -| -------- | -------- | -|getRdbStore(context: Context, config: StoreConfig, version: number, callback: AsyncCallback<RdbStore>): void| Obtains an RDB store. This API uses a callback to return the result. You can set parameters for the RDB store based on service requirements, and then call APIs to perform data operations.
- **context**: context of the application or function.
- **config**: configuration of the RDB store.
- **version**: RDB version.
- **callback**: callback invoked to return the RDB store obtained.| -|getRdbStore(context: Context, config: StoreConfig, version: number): Promise<RdbStore> | Obtains an RDB store. This API uses a promise to return the result. You can set parameters for the RDB store based on service requirements, and then call APIs to perform data operations.
- **context**: context of the application or function.
- **config**: configuration of the RDB store.
- **version**: RDB version.| -|deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void> ): void | Deletes an RDB store. This API uses a callback to return the result.
- **context**: context of the application or function.
- **name**: RDB store to delete.
- **callback**: callback invoked to return the result.| -| deleteRdbStore(context: Context, name: string): Promise<void> | Deletes an RDB store. This API uses a promise to return the result.
- **context**: context of the application or function.
- **name**: RDB store to delete.| +| API | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| getRdbStore(context: Context, config: StoreConfig, version: number): Promise<RdbStore> | Obtains an RDB store. This API uses a promise to return the result. You can set parameters for the RDB store based on service requirements and call APIs to perform data operations.
- **context**: context of the application or function.
- **config**: configuration of the RDB store.
- **version**: version of the RDB store.| +| deleteRdbStore(context: Context, name: string): Promise<void> | Deletes an RDB store. This API uses a promise to return the result.
- **context**: context of the application or function.
- **name**: name of the RDB store to delete.| ### Managing Data in an RDB Store The RDB provides APIs for inserting, deleting, updating, and querying data in the local RDB store. -- **Inserting data** +- **Inserting Data** The RDB provides APIs for inserting data through a **ValuesBucket** in a data table. If the data is inserted, the row ID of the data inserted will be returned; otherwise, **-1** will be returned. - **Table 2** APIs for inserting data + **Table 2** API for inserting data - | Class| API| Description| - | -------- | -------- | -------- | - | RdbStore | insert(table: string, values: ValuesBucket, callback: AsyncCallback<number>):void | Inserts a row of data into a table. This API uses a callback to return the result.
- **table**: name of the target table.
- **values**: data to be inserted into the table.
- **callback**: callback invoked to return the result. If the operation is successful, the row ID will be returned; otherwise, **-1** will be returned.| - | RdbStore | insert(table: string, values: ValuesBucket): Promise<number> | Inserts a row of data into a table. This API uses a promise to return the result.
- **table**: name of the target table.
- **values**: data to be inserted into the table.| + | Class | API | Description | + | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | + | RdbStore | insert(table:string,values:ValuesBucket):Promise<number> | Inserts a row of data into a table. This API uses a promise to return the result.
If the operation is successful, the row ID will be returned; otherwise, **-1** will be returned.
- **table**: name of the target table.
- **values**: data to be inserted into the table.| -- **Updating data** +- **Updating Data** Call the **update()** method to pass new data and specify the update conditions by using **RdbPredicates**. If the data is updated, the number of rows of the updated data will be returned; otherwise, **0** will be returned. - **Table 3** APIs for updating data + **Table 3** API for updating data - | Class| API| Description| - | -------- | -------- | -------- | - | RdbStore | update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback<number>):void | Updates data in the RDB store based on the specified **RdbPredicates** object. This API uses a callback to return the result.
- **values**: data to update, which is stored in a **ValuesBucket**.
- **predicates**: conditions for updating data.
- **callback**: callback invoked to return the number of rows updated.| - | RdbStore | update(values: ValuesBucket, predicates: RdbPredicates): Promise<number> | Updates data in the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.
- **values**: data to update, which is stored in a **ValuesBucket**.
- **predicates**: conditions for updating data.| + | Class | API | Description | + | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | + | RdbStore | update(values:ValuesBucket,predicates:RdbPredicates):Promise<number> | Updates data based on the specified **RdbPredicates** object. This API uses a promise to return the result.
- **values**: data to update, which is stored in **ValuesBucket**.
- **predicates**: conditions for updating data.
Return value: number of rows updated. | -- **Deleting data** +- **Deleting Data** Call the **delete()** method to delete data meeting the conditions specified by **RdbPredicates**. If the data is deleted, the number of rows of the deleted data will be returned; otherwise, **0** will be returned. - **Table 4** APIs for deleting data + **Table 4** API for deleting data - | Class| API| Description| - | -------- | -------- | -------- | - | RdbStore | delete(predicates: RdbPredicates, callback: AsyncCallback<number>):void | Deletes data from the RDB store based on the specified **RdbPredicates** object. This API uses an asynchronous callback to return the result.
- **predicates**: conditions for deleting data.
- **callback**: callback invoked to return the number of rows updated.| - | RdbStore | delete(predicates: RdbPredicates): Promise<number> | Deletes data from the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.
- **predicates**: conditions for deleting data.| + | Class | API | Description | + | -------- | ------------------------------------------------------ | ------------------------------------------------------------ | + | RdbStore | delete(predicates:RdbPredicates):Promise<number> | Deletes data from the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.
- **predicates**: conditions for deleting data.
Return value: number of rows updated. | -- **Querying data** + + +- **Querying Data** You can query data in an RDB store in either of the following ways: @@ -68,78 +65,48 @@ The RDB provides APIs for inserting, deleting, updating, and querying data in th **Table 5** APIs for querying data - | Class| API| Description| - | -------- | -------- | -------- | - | RdbStore | query(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>): void | Queries data in the RDB store based on the specified **RdbPredicates** object. This API uses a callback to return the result.
- **predicates**: conditions for querying data.
- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.
- **callback**: callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.| - | RdbStore | query(predicates: RdbPredicates, columns?: Array<string>): Promise<ResultSet> | Queries data in the RDB store based on the specified **RdbPredicates** object. This API uses a promise to return the result.
- **predicates**: conditions for querying data.
- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.| - | RdbStore | querySql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<ResultSet>):void | Queries data in the RDB store using the specified SQL statement. This API uses a callback to return the result.
- **sql**: SQL statement.
- **bindArgs**: arguments in the SQL statement.
- **callback**: callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.| - | RdbStore | querySql(sql: string, bindArgs?: Array<ValueType>):Promise<ResultSet> | Queries data in the RDB store using the specified SQL statement. This API uses a promise to return the result.
- **sql**: SQL statement.
- **bindArgs**: arguments in the SQL statement.| - | RdbStore | remoteQuery(device: string, table: string, predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>): void |Queries data from the RDB store of a remote device based on specified conditions. This API uses an asynchronous callback to return the result.
- **device**: network ID of the remote device.
- **table**: name of the table to query.
- **predicates**: conditions for querying data.
- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.
- **callback**: callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.| - | RdbStore | remoteQuery(device: string, table: string, predicates: RdbPredicates, columns: Array<string>): Promise<ResultSet> | Queries data from the RDB store of a remote device based on specified conditions. This API uses a promise to return the result.
- **device**: network ID of the remote device.
- **table**: name of the table to query.
- **predicates**: conditions for querying data.
- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.| + | Class | API | Description | + | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | + | RdbStore | query(predicates:RdbPredicates,columns?:Array<string>):Promise<ResultSet> | Queries data from the RDB store based on specified conditions. This API uses a promise to return the result.
- **predicates**: conditions for querying data.
- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.| + | RdbStore | querySql(sql:string,bindArgs?:Array<ValueType>):Promise<ResultSet> | Queries data using the specified SQL statement. This API uses a promise to return the result.
- **sql**: SQL statement.
- **bindArgs**: arguments in the SQL statement.| + | RdbStore | remoteQuery(device: string, table: string, predicates: RdbPredicates, columns: Array<string>): Promise<ResultSet> | Queries data from the database of a remote device based on specified conditions. This API uses a promise to return the result.
- **device**: network ID of the remote device.
- **table**: name of the table to be queried.
- **predicates**: **RdbPredicates** that specifies the query condition.
- **columns**: columns to query. If this parameter is not specified, the query applies to all columns.| ### Using Predicates The RDB provides **RdbPredicates** for you to set database operation conditions. +The following lists common predicates. For more information about predicates, see [**RdbPredicates**](../reference/apis/js-apis-data-rdb.md#rdbpredicates). + **Table 6** APIs for using RDB store predicates -| Class| API| Description| -| -------- | -------- | -------- | -| RdbPredicates |inDevices(devices: Array\): RdbPredicates | Specifies remote devices on the network with RDB stores to be synchronized.
- **devices**: IDs of the remote devices on the network.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates |inAllDevices(): RdbPredicates | Connects to all remote devices on the network with RDB stores to be synchronized.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | equalTo(field: string, value: ValueType): RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value equal to the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | notEqualTo(field: string, value: ValueType): RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value not equal to the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | beginWrap(): RdbPredicates | Adds a left parenthesis to the **RdbPredicates**.
- **RdbPredicates**: returns a **RdbPredicates** with a left parenthesis.| -| RdbPredicates | endWrap(): RdbPredicates | Adds a right parenthesis to the **RdbPredicates**.
- **RdbPredicates**: returns a **RdbPredicates** with a right parenthesis.| -| RdbPredicates | or(): RdbPredicates | Adds the OR condition to the **RdbPredicates**.
- **RdbPredicates**: returns a **RdbPredicates** with the OR condition.| -| RdbPredicates | and(): RdbPredicates | Adds the AND condition to the **RdbPredicates**.
- **RdbPredicates**: returns a **RdbPredicates** with the AND condition.| -| RdbPredicates | contains(field: string, value: string): RdbPredicates | Sets an **RdbPredicates** to match a string containing the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified string.| -| RdbPredicates | beginsWith(field: string, value: string): RdbPredicates | Sets an **RdbPredicates** to match a string that starts with the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | endsWith(field: string, value: string): RdbPredicates | Sets an **RdbPredicates** to match a string that ends with the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | isNull(field: string): RdbPredicates | Sets an **RdbPredicates** to match the field whose value is null.
- **field**: column name in the database table.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | isNotNull(field: string): RdbPredicates | Sets an **RdbPredicates** to match the field whose value is not null.
- **field**: column name in the database table.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | like(field: string, value: string): RdbPredicates | Sets an **RdbPredicates** to match a string that is similar to the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | glob(field: string, value: string): RdbPredicates | Sets an **RdbPredicates** to match the specified string.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | between(field: string, low: ValueType, high: ValueType): RdbPredicates | Sets ta **RdbPredicates** to match the field with data type **ValueType** and value within the specified range.
- **field**: column name in the database table.
- **low**: minimum value that matches the **RdbPredicates**.
- **high**: maximum value that matches the **RdbPredicates**.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | notBetween(field: string, low: ValueType, high: ValueType): RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value out of the specified range.
- **field**: column name in the database table.
- **low**: minimum value that matches the **RdbPredicates**.
- **high**: maximum value that matches the **RdbPredicates**.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | greaterThan(field: string, value: ValueType): RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value greater than the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | lessThan(field: string, value: ValueType): RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value less than the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | greaterThanOrEqualTo(field: string, value: ValueType): RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value greater than or equal to the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | lessThanOrEqualTo(field: string, value: ValueType): RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value less than or equal to the specified value.
- **field**: column name in the database table.
- **value**: value specified.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | orderByAsc(field: string): RdbPredicates | Sets an **RdbPredicates** to match the column with values sorted in ascending order.
- **field**: column name in the database table.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | orderByDesc(field: string): RdbPredicates | Sets an **RdbPredicates** to match the column with values sorted in descending order.
- **field**: column name in the database table.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | distinct(): RdbPredicates | Sets an **RdbPredicates** to filter out duplicate records.
- **RdbPredicates**: returns a **RdbPredicates** object that can filter out duplicate records.| -| RdbPredicates | limitAs(value: number): RdbPredicates | Sets an **RdbPredicates** to specify the maximum number of records.
- **value**: maximum number of records.
- **RdbPredicates**: returns a **RdbPredicates** object that can be used to set the maximum number of records.| -| RdbPredicates | offsetAs(rowOffset: number): RdbPredicates | Sets the **RdbPredicates** to specify the start position of the returned result.
- **rowOffset**: start position of the returned result. The value is a positive integer.
- **RdbPredicates**: returns a **RdbPredicates** object that specifies the start position of the returned result.| -| RdbPredicates | groupBy(fields: Array<string>): RdbPredicates | Sets an **RdbPredicates** to group rows that have the same value into summary rows.
- **fields**: names of the columns grouped for querying data.
- **RdbPredicates**: returns a **RdbPredicates** object that groups rows with the same value.| -| RdbPredicates | indexedBy(indexName: string): RdbPredicates | Sets an **RdbPredicates** to specify the index column.
- **indexName**: name of the index column.
- **RdbPredicates**: returns a **RdbPredicates** object that specifies the index column.| -| RdbPredicates | in(field: string, value: Array<ValueType>): RdbPredicates | Sets an **RdbPredicates** to match the field with data type **Array<ValueType>** and value within the specified range.
- **field**: column name in the database table.
- **value**: array of **ValueType** to match.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| -| RdbPredicates | notIn(field: string, value: Array<ValueType>): RdbPredicates | Sets an **RdbPredicates** to match the field with data type **Array<ValueType>** and value out of the specified range.
- **field**: column name in the database table.
- **value**: array of **ValueType** to match.
- **RdbPredicates**: returns a **RdbPredicates** object that matches the specified field.| +| Class | API | Description | +| ------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| RdbPredicates | equalTo(field:string,value:ValueType):RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object that matches the specified field.| +| RdbPredicates | notEqualTo(field:string,value:ValueType):RdbPredicates | Sets an **RdbPredicates** to match the field with data type **ValueType** and value not equal to the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object that matches the specified field.| +| RdbPredicates | or():RdbPredicates | Adds the OR condition to the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** with the OR condition.| +| RdbPredicates | and():RdbPredicates | Adds the AND condition to the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** with the AND condition.| +| RdbPredicates | contains(field:string,value:string):RdbPredicates | Sets an **RdbPredicates** to match a string containing the specified value.
- **field**: column name in the database table.
- **value**: value to match the **RdbPredicates**.
- **RdbPredicates**: **RdbPredicates** object that matches the specified field.| + ### Using the Result Set -A result set can be regarded as a row of data in the queried results. It allows you to traverse and access the data you have queried. The following table describes the external APIs of **ResultSet**. +A result set can be regarded as a row of data in the queried results. It allows you to traverse and access the data you have queried. + +For details about how to use result set APIs, see [Result Set](../reference/apis/js-apis-data-resultset.md). > **NOTICE**
> After a result set is used, you must call the **close()** method to close it explicitly. **Table 7** APIs for using the result set -| Class| API| Description| -| -------- | -------- | -------- | -| ResultSet | goTo(offset:number): boolean | Moves the result set forwards or backwards by the specified offset relative to its current position.| -| ResultSet | goToRow(position: number): boolean | Moves the result set to the specified row.| -| ResultSet | goToNextRow(): boolean | Moves the result set to the next row.| -| ResultSet | goToPreviousRow(): boolean | Moves the result set to the previous row.| -| ResultSet | getColumnIndex(columnName: string): number | Obtains the column index based on the specified column name.| -| ResultSet | getColumnName(columnIndex: number): string | Obtains the column name based on the specified column index.| -| ResultSet | goToFirstRow(): boolean | Moves to the first row of the result set.| -| ResultSet | goToLastRow(): boolean | Moves to the last row of the result set.| -| ResultSet | getString(columnIndex: number): string | Obtains the value in the specified column of the current row, in a string.| -| ResultSet | getBlob(columnIndex: number): Uint8Array | Obtains the values in the specified column of the current row, in a byte array.| -| ResultSet | getDouble(columnIndex: number): number | Obtains the values in the specified column of the current row, in double.| -| ResultSet | isColumnNull(columnIndex: number): boolean | Checks whether the value in the specified column of the current row is null.| -| ResultSet | close(): void | Closes the result set.| +| Class | API | Description | +| --------- | ---------------------------------------------------- | ------------------------------------------ | +| ResultSet | goToFirstRow():boolean | Moves to the first row of the result set. | +| ResultSet | getString(columnIndex:number):string | Obtains the value in the form of a string based on the specified column and current row. | +| ResultSet | getBlob(columnIndex:number):Uint8Array | Obtains the value in the form of a byte array based on the specified column and the current row.| +| ResultSet | getDouble(columnIndex:number):number | Obtains the value in the form of double based on the specified column and current row. | +| ResultSet | getLong(columnIndex:number):number | Obtains the value in the form of a long integer based on the specified column and current row. | +| ResultSet | close():void | Closes the result set. | @@ -149,78 +116,73 @@ A result set can be regarded as a row of data in the queried results. It allows **Setting Distributed Tables** -**Table 8** APIs for setting distributed tables +**Table 8** API for setting distributed tables -| Class| API| Description| -| -------- | -------- | -------- | -| RdbStore | setDistributedTables(tables: Array\, callback: AsyncCallback\): void | Sets a list of distributed tables. This API uses a callback to return the result.
- **tables**: names of the distributed tables to set.
- **callback**: callback invoked to return the result.| -| RdbStore | setDistributedTables(tables: Array\): Promise\ | Sets a list of distributed tables. This API uses a promise to return the result.
- **tables**: names of the distributed tables to set.| +| Class | API | Description | +| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| RdbStore | setDistributedTables(tables: Array\): Promise\ | Sets distributed tables. This API uses a promise to return the result.
- **tables**: names of the distributed tables to set.| **Obtaining the Distributed Table Name for a Remote Device** You can obtain the distributed table name for a remote device based on the local table name. The distributed table name can be used to query the RDB store of the remote device. -**Table 9** APIs for obtaining the distributed table name of a remote device +**Table 9** API for obtaining the distributed table name of a remote device -| Class| API| Description| -| -------- | -------- | -------- | -| RdbStore | obtainDistributedTableName(device: string, table: string, callback: AsyncCallback\): void | Obtains the distributed table name for a remote device based on the local table name. The distributed table name is required when the database of a remote device is queried. This API uses an asynchronous callback to return the result.
- **device**: remote device.
- **table**: local table name.
- **callback**: callback used to return the result. If the operation is successful, the distributed table name of the remote device will be returned.| -| RdbStore | obtainDistributedTableName(device: string, table: string): Promise\ | Obtains the distributed table name for a remote device based on the local table name. The distributed table name is used to query the RDB store of the remote device. This API uses a promise to return the result.
- **device**: remote device.
- **table**: local table name.| +| Class | API | Description | +| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| RdbStore | obtainDistributedTableName(device: string, table: string): Promise\ | Obtains the distributed table name for a remote device based on the local table name. The distributed table name is required when the RDB store of a remote device is queried. This API uses a promise to return the result.
- **device**: remote device.
- **table**: local table name.| **Synchronizing Data Between Devices** -**Table 10** APIs for synchronizing data between devices +**Table 10** API for synchronizing data between devices -| Class| API| Description| -| -------- | -------- | -------- | -| RdbStore | sync(mode: SyncMode, predicates: RdbPredicates, callback: AsyncCallback\>): void | Synchronizes data between devices. This API uses a callback to return the result.
- **mode**: data synchronization mode. **SYNC_MODE_PUSH** means to push data from the local device to a remote device. **SYNC_MODE_PULL** means to pull data from a remote device to the local device.
- **predicates**: data and devices to be synchronized.
- **callback**: callback invoked to return the result. In the result, **string** indicates the device ID, and **number** indicates the synchronization status of each device. The value **0** indicates a success, and other values indicate a failure.| -| RdbStore | sync(mode: SyncMode, predicates: RdbPredicates): Promise\> | Synchronizes data between devices. This API uses a promise to return the result.
- **mode**: data synchronization mode. **SYNC_MODE_PUSH** means to push data from the local device to a remote device. **SYNC_MODE_PULL** means to pull data from a remote device to the local device.
- **predicates**: data and devices to be synchronized.| +| Class | API | Description | +| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| RdbStore | sync(mode: SyncMode, predicates: RdbPredicates): Promise\> | Synchronizes data between devices. This API uses a promise to return the result.
- **mode**: synchronization mode. **SYNC_MODE_PUSH** means to push data from the local device to a remote device. **SYNC_MODE_PULL** means to pull data from a remote device to the local device.
- **predicates**: specifies the data and devices to synchronize.
- **string**: device ID.
- **number**: synchronization status of that device. The value **0** indicates a successful synchronization. Other values indicate a synchronization failure.| **Registering an RDB Store Observer** **Table 11** API for registering an observer -| Class| API| Description| -| -------- | -------- | -------- | -| RdbStore |on(event: 'dataChange', type: SubscribeType, observer: Callback\>): void| Registers an observer for this RDB store to subscribe to distributed data changes. When data in the RDB store changes, a callback will be invoked to return the data changes.
- **type**: subscription type. **SUBSCRIBE_TYPE_REMOTE** means to subscribe to remote data changes.
- **observer**: observer that listens for data changes in the RDB store.| +| Class | API | Description | +| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| RdbStore | on(event: 'dataChange', type: SubscribeType, observer: Callback\>): void | Registers an observer for this RDB store to subscribe to distributed data changes. When data in the RDB store changes, a callback will be invoked to return the data changes.
- **type**: subscription type. **SUBSCRIBE_TYPE_REMOTE** means to subscribe to remote data changes.
- **observer**: observer that listens for data changes in the RDB store.| **Unregistering an RDB Store Observer** **Table 12** API for unregistering an observer -| Class| API| Description| -| -------- | -------- | -------- | -| RdbStore |off(event:'dataChange', type: SubscribeType, observer: Callback\>): void;| Unregisters the observer of the specified type for the RDB store. This API uses a callback to return the result.
- **type**: subscription type. **SUBSCRIBE_TYPE_REMOTE** means to subscribe to remote data changes.
- **observer**: observer to unregister.| +| Class | API | Description | +| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| RdbStore | off(event:'dataChange', type: SubscribeType, observer: Callback\>): void; | Unregisters the observer of the specified type from the RDB store. This API uses an asynchronous callback to return the result.
- **type**: subscription type. **SUBSCRIBE_TYPE_REMOTE** means to subscribe to remote data changes.
- **observer**: observer to unregister.| ### Backing Up and Restoring an RDB Store **Backing Up an RDB Store** -**Table 13** APIs for backing up an RDB store +**Table 13** API for backing up an RDB store -| Class| API| Description| -| -------- | -------- | -------- | -| RdbStore |backup(destName:string, callback: AsyncCallback<void>):void| Backs up an RDB store. This API uses an asynchronous callback to return the result.
- **destName**: name of the RDB backup file.
- **callback**: callback invoked to return the result.| -| RdbStore |backup(destName:string): Promise<void>| Backs up an RDB store. This API uses a promise to return the result.
- **destName**: name of the RDB backup file.| +| Class | API | Description | +| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| RdbStore | backup(destName:string): Promise<void> | Backs up an RDB store. This API uses a promise to return the result.
- **destName**: name of the RDB backup file.| **Restoring an RDB Store** -**Table 14** APIs for restoring an RDB store +**Table 14** API for restoring an RDB store -| Class| API| Description| -| -------- | -------- | -------- | -| RdbStore |restore(srcName:string, callback: AsyncCallback<void>):void| Restores an RDB store using a backup file. This API uses an asynchronous callback to return the result.
- **srcName**: name of the RDB backup file.
- **callback**: callback invoked to return the result.| -| RdbStore |restore(srcName:string): Promise<void>| Restores an RDB store using a backup file. This API uses a promise to return the result.
- **srcName**: name of the RDB backup file.| +| Class | API | Description | +| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| RdbStore | restore(srcName:string): Promise<void> | Restores an RDB store from a backup file. This API uses a promise to return the result.
- **srcName**: name of the backup file used to restore the RDB store.| **Transaction** Table 15 Transaction APIs -| Class| API| Description| -| -------- | -------- | -------- | -| RdbStore |beginTransaction():void| Starts the transaction before executing SQL statements.| -| RdbStore |commit():void| Commits the executed SQL statements.| -| RdbStore |rollBack():void| Rolls back the SQL statements that have been executed.| +| Class | API | Description | +| -------- | ----------------------- | --------------------------------- | +| RdbStore | beginTransaction():void | Starts the transaction before executing SQL statements.| +| RdbStore | commit():void | Commits the executed SQL statements. | +| RdbStore | rollBack():void | Rolls back the SQL statements that have been executed. | ## How to Develop @@ -238,7 +200,7 @@ Table 15 Transaction APIs import data_rdb from '@ohos.data.rdb' const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (" + "id INTEGER PRIMARY KEY AUTOINCREMENT, " + "name TEXT NOT NULL, " + "age INTEGER, " + "salary REAL, " + "blobType BLOB)"; - const STORE_CONFIG = {name: "rdbstore.db",} + const STORE_CONFIG = {name: "rdbstore.db"} data_rdb.getRdbStore(this.context, STORE_CONFIG, 1, function (err, rdbStore) { rdbStore.executeSql(CREATE_TABLE_TEST) console.info('create table done.') @@ -255,7 +217,7 @@ Table 15 Transaction APIs ```js var u8 = new Uint8Array([1, 2, 3]) - const valueBucket = {"name": "Tom", "age": 18, "salary": 100.5, "blobType": u8,} + const valueBucket = {"name": "Tom", "age": 18, "salary": 100.5, "blobType": u8} let insertPromise = rdbStore.insert("test", valueBucket) ``` @@ -288,11 +250,11 @@ Table 15 Transaction APIs (1) Add the following permission to the permission configuration file: - ```js + ```json "requestPermissions": - { + { "name": "ohos.permission.DISTRIBUTED_DATASYNC" - } + } ``` (2) Obtain the required permissions. @@ -424,3 +386,4 @@ Table 15 Transaction APIs console.info('Restore failed, err: ' + err) }) ``` + diff --git a/en/application-dev/device/device-location-info.md b/en/application-dev/device/device-location-info.md index a32decd05ac0ba0d6db06749c18dcd31d3a7645b..c61c9288eecb35ce4235fb00ce91b595b9160b44 100644 --- a/en/application-dev/device/device-location-info.md +++ b/en/application-dev/device/device-location-info.md @@ -84,7 +84,7 @@ To learn more about the APIs for obtaining device location information, see [Geo } ``` - For details about the fields, see [Application Package Structure Configuration File](../quick-start/stage-structure.md). + For details about these fields, see [Application Package Structure Configuration File](../quick-start/stage-structure.md). 2. Import the **geolocation** module by which you can implement all APIs related to the basic location capabilities. diff --git a/en/application-dev/media/audio-playback.md b/en/application-dev/media/audio-playback.md index d65d0abfc4d4649f7f1847abdbe6fb0a832e194e..faf977c7b42644a03066947e45996a936529f8cc 100644 --- a/en/application-dev/media/audio-playback.md +++ b/en/application-dev/media/audio-playback.md @@ -39,28 +39,28 @@ function printfDescription(obj) { // Set the player callbacks. function setCallBack(audioPlayer) { - audioPlayer.on('dataLoad', () => { // Set the `dataLoad` event callback, which is triggered when the src attribute is set successfully. + audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully. console.info('audio set source success'); audioPlayer.play(); // The play() API can be invoked only after the 'dataLoad' event callback is complete. The 'play' event callback is then triggered. }); - audioPlayer.on('play', () => { // Set the `play` event callback. + audioPlayer.on('play', () => { // Set the 'play' event callback. console.info('audio play success'); audioPlayer.pause(); // Trigger the 'pause' event callback and pause the playback. }); - audioPlayer.on('pause', () => { // Set the `pause` event callback. + audioPlayer.on('pause', () => { // Set the 'pause' event callback. console.info('audio pause success'); audioPlayer.seek(5000); // Trigger the 'timeUpdate' event callback, and seek to 5000 ms for playback. }); - audioPlayer.on('stop', () => { // Set the `stop` event callback. + audioPlayer.on('stop', () => { // Set the 'stop' event callback. console.info('audio stop success'); audioPlayer.reset(); // Trigger the 'reset' event callback, and reconfigure the src attribute to switch to the next song. }); - audioPlayer.on('reset', () => { // Set the `reset` event callback. + audioPlayer.on('reset', () => { // Set the 'reset' event callback. console.info('audio reset success'); audioPlayer.release(); // Release the AudioPlayer instance. audioPlayer = undefined; }); - audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the `timeUpdate` event callback. + audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback. if (typeof(seekDoneTime) == 'undefined') { console.info('audio seek fail'); return; @@ -68,7 +68,7 @@ function setCallBack(audioPlayer) { console.info('audio seek success, and seek time is ' + seekDoneTime); audioPlayer.setVolume(0.5); // Trigger the 'volumeChange' event callback. }); - audioPlayer.on('volumeChange', () => { // Set the `volumeChange` event callback. + audioPlayer.on('volumeChange', () => { // Set the 'volumeChange' event callback. console.info('audio volumeChange success'); audioPlayer.getTrackDescription((error, arrlist) => { // Obtain the audio track information in callback mode. if (typeof (arrlist) != 'undefined') { @@ -107,7 +107,7 @@ async function audioPlayerDemo() { }).catch((err) => { console.info('open fd failed err is' + err); }); - audioPlayer.src = fdPath; // Set the src attribute and trigger the `dataLoad` event callback. + audioPlayer.src = fdPath; // Set the src attribute and trigger the 'dataLoad' event callback. } ``` @@ -119,11 +119,11 @@ import fileIO from '@ohos.fileio' export class AudioDemo { // Set the player callbacks. setCallBack(audioPlayer) { - audioPlayer.on('dataLoad', () => { // Set the `dataLoad` event callback, which is triggered when the src attribute is set successfully. + audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully. console.info('audio set source success'); audioPlayer.play(); // Call the play() API to start the playback and trigger the 'play' event callback. }); - audioPlayer.on('play', () => { // Set the `play` event callback. + audioPlayer.on('play', () => { // Set the 'play' event callback. console.info('audio play success'); }); audioPlayer.on('finish', () => { // Set the 'finish' event callback, which is triggered when the playback is complete. @@ -147,7 +147,7 @@ export class AudioDemo { }).catch((err) => { console.info('open fd failed err is' + err); }); - audioPlayer.src = fdPath; // Set the src attribute and trigger the `dataLoad` event callback. + audioPlayer.src = fdPath; // Set the src attribute and trigger the 'dataLoad' event callback. } } ``` @@ -161,15 +161,15 @@ export class AudioDemo { // Set the player callbacks. private isNextMusic = false; setCallBack(audioPlayer) { - audioPlayer.on('dataLoad', () => { // Set the `dataLoad` event callback, which is triggered when the src attribute is set successfully. + audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully. console.info('audio set source success'); audioPlayer.play(); // Call the play() API to start the playback and trigger the 'play' event callback. }); - audioPlayer.on('play', () => { // Set the `play` event callback. + audioPlayer.on('play', () => { // Set the 'play' event callback. console.info('audio play success'); audioPlayer.reset(); // Call the reset() API and trigger the 'reset' event callback. }); - audioPlayer.on('reset', () => { // Set the `reset` event callback. + audioPlayer.on('reset', () => { // Set the 'reset' event callback. console.info('audio play success'); if (!this.isNextMusic) { // When isNextMusic is false, changing songs is implemented. this.nextMusic(audioPlayer); // Changing songs is implemented. @@ -223,7 +223,7 @@ import fileIO from '@ohos.fileio' export class AudioDemo { // Set the player callbacks. setCallBack(audioPlayer) { - audioPlayer.on('dataLoad', () => { // Set the `dataLoad` event callback, which is triggered when the src attribute is set successfully. + audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully. console.info('audio set source success'); audioPlayer.loop = true; // Set the loop playback attribute. audioPlayer.play(); // Call the play() API to start the playback and trigger the 'play' event callback. @@ -247,7 +247,7 @@ export class AudioDemo { }).catch((err) => { console.info('open fd failed err is' + err); }); - audioPlayer.src = fdPath; // Set the src attribute and trigger the `dataLoad` event callback. + audioPlayer.src = fdPath; // Set the src attribute and trigger the 'dataLoad' event callback. } } ``` diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 6b5bbc8aa3d671c4cf0b01316db441d33c0f189f..edee55c375b0cc31b8f6305ed7fb24397bad12b0 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -19,6 +19,7 @@ - [@ohos.application.ServiceExtensionAbility](js-apis-service-extension-ability.md) - [@ohos.application.StartOptions](js-apis-application-StartOptions.md) - [@ohos.application.StaticSubscriberExtensionAbility](js-apis-application-staticSubscriberExtensionAbility.md) + - [@ohos.application.WindowExtensionAbility](js-apis-application-WindowExtensionAbility.md) - application/[AbilityContext](js-apis-ability-context.md) - application/[ApplicationContext](js-apis-application-applicationContext.md) - application/[AbilityStageContext](js-apis-abilitystagecontext.md) @@ -68,18 +69,25 @@ - [@ohos.bundle](js-apis-Bundle.md) - [@ohos.bundle.defaultAppManager](js-apis-bundle-defaultAppManager.md) + - [@ohos.bundle.innerBundleManager)](js-apis-Bundle-InnerBundleManager.md) - [@ohos.bundleState](js-apis-deviceUsageStatistics.md) + - [@ohos.distributedBundle)](js-apis-Bundle-distributedBundle.md) - [@ohos.zlib](js-apis-zlib.md) - bundle/[AbilityInfo](js-apis-bundle-AbilityInfo.md) - bundle/[ApplicationInfo](js-apis-bundle-ApplicationInfo.md) - bundle/[BundleInfo](js-apis-bundle-BundleInfo.md) + - bundle/[BundleInstaller](js-apis-bundle-BundleInstaller.md) - bundle/[CustomizeData](js-apis-bundle-CustomizeData.md) + - bundle/[DispatchInfo](js-apis-dispatchInfo.md) - bundle/[ElementName](js-apis-bundle-ElementName.md) - bundle/[ExtensionAbilityInfo](js-apis-bundle-ExtensionAbilityInfo.md) - bundle/[HapModuleInfo](js-apis-bundle-HapModuleInfo.md) + - bundle/[LauncherAbilityInfo](js-apis-bundle-LauncherAbilityInfo.md) - bundle/[Metadata](js-apis-bundle-Metadata.md) - bundle/[ModuleInfo](js-apis-bundle-ModuleInfo.md) - + - bundle/[PermissionDef](js-apis-bundle-PermissionDef.md) + - bundle/[RemoteAbilityInfo](js-apis-bundle-remoteAbilityInfo.md) + - bundle/[ShortcutInfo](js-apis-bundle-ShortcutInfo.md) - UI Page - [@ohos.animator](js-apis-animator.md) @@ -90,6 +98,7 @@ - Graphics + - [@ohos.animation.windowAnimationManager](js-apis-windowAnimationManager.md) - [@ohos.display ](js-apis-display.md) - [@ohos.effectKit](js-apis-effectKit.md) - [@ohos.screen](js-apis-screen.md) diff --git a/en/application-dev/reference/apis/js-apis-Bundle-InnerBundleManager.md b/en/application-dev/reference/apis/js-apis-Bundle-InnerBundleManager.md new file mode 100644 index 0000000000000000000000000000000000000000..3691d636ac769e8bfad9099f92554a2476925d40 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-Bundle-InnerBundleManager.md @@ -0,0 +1,307 @@ +# innerBundleManager + +The **innerBundleManager** module manages internal bundles. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +``` +import innerBundleManager from '@ohos.bundle.innerBundleManager'; +``` + +## System Capability + +SystemCapability.BundleManager.BundleFramework + +## Required Permissions + +| Permission | Permission Level | Description | +| ------------------------------------------ | ------------ | ---------------------------- | +| ohos.permission.GET_BUNDLE_INFO_PRIVILEGED | system_basic | Permission to query information about all applications. | +| ohos.permission.LISTEN_BUNDLE_CHANGE | system_grant | Permission to listen for application changes.| + +For details, see [Permission Levels](../../security/accesstoken-overview.md#permission-levels). + +## innerBundleManager.getLauncherAbilityInfos + +getLauncherAbilityInfos(bundleName: string, userId: number, callback: AsyncCallback<Array<LauncherAbilityInfo>>) : void; + +Obtains the launcher ability information based on a given bundle name. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | +| bundleName | string | Yes | Bundle name of an application. | +| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0.| +| callback | AsyncCallback\> | Yes | Callback used to return an array of the launcher ability information. | + + + +## innerBundleManager.getLauncherAbilityInfos + +getLauncherAbilityInfos(bundleName: string, userId: number) : Promise<Array<LauncherAbilityInfo>> + +Obtains the launcher ability information based on a given bundle name. This API uses a promise to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------ | ---- | ----------------------------------------------------- | +| bundleName | string | Yes | Bundle name of an application. | +| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0.| + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ------------------------- | +| Promise\> | Promise used to return an array of the launcher ability information.| + +## innerBundleManager.on + +on(type:"BundleStatusChange", bundleStatusCallback : BundleStatusCallback, callback: AsyncCallback<string>) : void; + +Registers a callback to receive bundle status changes. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.LISTEN_BUNDLE_CHANGE + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------------- | --------------------- | ---- | ---------------------------------------------------- | +| type | "BundleStatusChange" | Yes | Event type. | +| bundleStatusCallback | BundleStatusCallback | Yes | Callback to register. | +| callback | AsyncCallback\ | Yes | Callback used to return a successful result or error information.| + +## innerBundleManager.on + +on(type:"BundleStatusChange", bundleStatusCallback : BundleStatusCallback): Promise<string> + +Registers a callback to receive bundle status changes. This API uses a promise to return the result. + +**Required permissions** + +ohos.permission.LISTEN_BUNDLE_CHANGE + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------------- | -------------------- | ---- | ------------------ | +| type | "BundleStatusChange" | Yes | Event type. | +| bundleStatusCallback | BundleStatusCallback | Yes | Callback to register.| + +**Return value** + +| Type | Description | +| --------------- | ----------------------------------- | +| Promise\ | Promise used to return a successful result or error information.| + +## innerBundleManager.off + +off(type:"BundleStatusChange", callback: AsyncCallback<string>) : void; + +Deregisters the callback that receives bundle status changes. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.LISTEN_BUNDLE_CHANGE + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ---------------------------------------------------- | +| type | "BundleStatusChange" | Yes | Event type. | +| callback | AsyncCallback\ | Yes | Callback used to return a successful result or error information.| + +## innerBundleManager.off + +off(type:"BundleStatusChange"): Promise<string> + +Deregisters the callback that receives bundle status changes. This API uses a promise to return the result. + +**Required permissions** + +ohos.permission.LISTEN_BUNDLE_CHANGE + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type | Mandatory| Description | +| ---- | -------------------- | ---- | ---------------- | +| type | "BundleStatusChange" | Yes | Event type.| + +**Return value** + +| Type | Description | +| --------------- | ----------------------------------- | +| Promise\ | Promise used to return a successful result or error information.| + +## innerBundleManager.getAllLauncherAbilityInfos + +getAllLauncherAbilityInfos(userId: number, callback: AsyncCallback<Array<LauncherAbilityInfo>>) : void; + +Obtains the information about all launcher abilities. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | +| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0.| +| callback | AsyncCallback\> | Yes | Callback used to return an array of the launcher ability information. | + +## innerBundleManager.getAllLauncherAbilityInfos + +getAllLauncherAbilityInfos(userId: number) : Promise<Array<LauncherAbilityInfo>> + +Obtains the information about all launcher abilities. This API uses a promise to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------ | ------ | ---- | ----------------------------------------------------- | +| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0.| + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ------------------------- | +| Promise\> | Promise used to return an array of the launcher ability information.| + +## innerBundleManager.getShortcutInfos + +getShortcutInfos(bundleName :string, callback: AsyncCallback<Array<ShortcutInfo>>) : void; + +Obtains the shortcut information based on a given bundle name. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ---------------------------------------------- | +| bundleName | string | Yes | Bundle name of an application. | +| callback | AsyncCallback\> | Yes | Callback used to return an array of the shortcut information.| + +## innerBundleManager.getShortcutInfos + +getShortcutInfos(bundleName : string) : Promise<Array<ShortcutInfo>> + +Obtains the shortcut information based on a given bundle name. This API uses a promise to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------ | ---- | ------------------------ | +| bundleName | string | Yes | Bundle name of an application.| + +**Return value** + +| Type | Description | +| -------------------------------------------------------- | ----------------------------- | +| Promise\> | Promise used to return an array of the shortcut information.| diff --git a/en/application-dev/reference/apis/js-apis-Bundle-distributedBundle.md b/en/application-dev/reference/apis/js-apis-Bundle-distributedBundle.md new file mode 100644 index 0000000000000000000000000000000000000000..f321aca70ed972845f73ca702501e574aeafe5e0 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-Bundle-distributedBundle.md @@ -0,0 +1,139 @@ +# distributedBundle + +The **distributedBundle** module manages distributed bundles. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +``` +import distributedBundle from '@ohos.distributedBundle'; +``` + +## System Capability + +SystemCapability.BundleManager.DistributedBundleFramework + +## Required Permissions + +| Permission | Permission Level | Description | +| ------------------------------------------ | ------------ | ------------------ | +| ohos.permission.GET_BUNDLE_INFO_PRIVILEGED | system_basic | Permission to query information about all applications.| + +For details, see [Permission Levels](../../security/accesstoken-overview.md#permission-levels). + +## distributedBundle.getRemoteAbilityInfo + +getRemoteAbilityInfo(elementName: ElementName, callback: AsyncCallback<RemoteAbilityInfo>): void; + +Obtains information about the remote ability that matches the given element name. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.DistributedBundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ------------------------------------------------------------ | ---- | -------------------------------------------------- | +| elementName | [ElementName](js-apis-bundle-ElementName.md) | Yes | **ElementName**. | +| callback | AsyncCallback<[RemoteAbilityInfo](js-apis-bundle-remoteAbilityInfo.md)> | Yes | Callback used to return the remote ability information.| + + + +## distributedBundle.getRemoteAbilityInfo + +getRemoteAbilityInfo(elementName: ElementName): Promise<RemoteAbilityInfo> + +Obtains information about the remote ability that matches the given element name. This API uses a promise to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.DistributedBundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | -------------------------------------------- | ---- | ----------------------- | +| elementName | [ElementName](js-apis-bundle-ElementName.md) | Yes | **ElementName**.| + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | --------------------------------- | +| Promise\<[RemoteAbilityInfo](js-apis-bundle-remoteAbilityInfo.md)> | Promise used to return the remote ability information.| + +## distributedBundle.getRemoteAbilityInfos + +getRemoteAbilityInfos(elementNames: Array<ElementName>, callback: AsyncCallback<Array<RemoteAbilityInfo>>): void; + +Obtains information about remote abilities that match the given element names. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.DistributedBundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ------------------------------------------------------------ | ---- | -------------------------------------------------- | +| elementNames | Array<[ElementName](js-apis-bundle-ElementName.md)> | Yes | **ElementName** array, whose maximum length is 10. | +| callback | AsyncCallback< Array<[RemoteAbilityInfo](js-apis-bundle-remoteAbilityInfo.md)>> | Yes | Callback used to return an array of the remote ability information.| + + + +## distributedBundle.getRemoteAbilityInfos + +getRemoteAbilityInfos(elementNames: Array<ElementName>): Promise<Array<RemoteAbilityInfo>> + +Obtains information about remote abilities that match the given element names. This API uses a promise to return the result. + +**Required permissions** + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability** + +SystemCapability.BundleManager.DistributedBundleFramework + +**System API** + +This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | --------------------------------------------------- | ---- | ----------------------- | +| elementNames | Array<[ElementName](js-apis-bundle-ElementName.md)> | Yes | **ElementName** array, whose maximum length is 10.| + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | --------------------------------- | +| Promise\> | Promise used to return an array of the remote ability information.| diff --git a/en/application-dev/reference/apis/js-apis-Bundle.md b/en/application-dev/reference/apis/js-apis-Bundle.md index 94d93df6aa2f25bfce6b2094cfe06a88429df346..e487baedfd496a9ac0a6e90332aa99f3323a4fc2 100644 --- a/en/application-dev/reference/apis/js-apis-Bundle.md +++ b/en/application-dev/reference/apis/js-apis-Bundle.md @@ -39,11 +39,11 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | ------ | ---- | --------------------------------------- | -| bundleName | string | Yes | Bundle name of an application. | -| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| userId | number | No | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | +| Name | Type | Mandatory| Description | +| ----------- | ------ | ---- | ------------------------------------------------------------ | +| bundleName | string | Yes | Bundle name of an application. | +| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the application information flags in [BundleFlag](#bundleflag).| +| userId | number | No | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | **Return value** @@ -81,12 +81,12 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | ------------------------------- | ---- | --------------------------------------- | -| bundleName | string | Yes | Bundle name of an application. | -| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | -| callback | AsyncCallback\<[ApplicationInfo](js-apis-bundle-ApplicationInfo.md)> | Yes | Callback used to return the application information. | +| Name | Type | Mandatory| Description | +| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| bundleName | string | Yes | Bundle name of an application. | +| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the application information flags in [BundleFlag](#bundleflag).| +| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | +| callback | AsyncCallback\<[ApplicationInfo](js-apis-bundle-ApplicationInfo.md)> | Yes | Callback used to return the application information. | **Example** @@ -119,11 +119,11 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | ------------------------------- | ---- | --------------------------------------- | -| bundleName | string | Yes | Bundle name of an application. | -| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| callback | AsyncCallback\<[ApplicationInfo](js-apis-bundle-ApplicationInfo.md)> | Yes | Callback used to return the application information. | +| Name | Type | Mandatory| Description | +| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| bundleName | string | Yes | Bundle name of an application. | +| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the application information flags in [BundleFlag](#bundleflag).| +| callback | AsyncCallback\<[ApplicationInfo](js-apis-bundle-ApplicationInfo.md)> | Yes | Callback used to return the application information. | **Example** @@ -155,10 +155,10 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ---------- | ---- | --------------------------------------- | -| bundleFlag | BundleFlag | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| userId | number | No | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | +| Name | Type | Mandatory| Description | +| ---------- | ---------- | ---- | ------------------------------------------------------------ | +| bundleFlag | BundleFlag | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the bundle information flags in [BundleFlag](#bundleflag).| +| userId | number | No | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | **Return value** @@ -195,10 +195,10 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ---------- | --------------------------------- | ---- | --------------------------------------- | -| bundleFlag | BundleFlag | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| callback | AsyncCallback> | Yes | Callback used to return the information of all available bundles. | +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| bundleFlag | BundleFlag | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the bundle information flags in [BundleFlag](#bundleflag).| +| callback | AsyncCallback> | Yes | Callback used to return the information of all available bundles. | **Example** @@ -229,11 +229,11 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ---------- | --------------------------------- | ---- | --------------------------------------- | -| bundleFlag | BundleFlag | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | -| callback | AsyncCallback> | Yes | Callback used to return the information of all available bundles. | +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| bundleFlag | BundleFlag | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the bundle information flags in [BundleFlag](#bundleflag).| +| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | +| callback | AsyncCallback> | Yes | Callback used to return the information of all available bundles. | **Example** @@ -268,7 +268,7 @@ SystemCapability.BundleManager.BundleFramework | Name | Type | Mandatory | Description | | ----------- | ------------- | ---- | --------------------------------------- | | bundleName | string | Yes | Bundle name of an application. | -| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| +| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the bundle information flags in [BundleFlag](#bundleflag).| | options | [BundleOptions](#bundleoptions) | No | Includes **userId**. | **Return value** @@ -309,11 +309,11 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | -------------------------- | ---- | --------------------------------------- | -| bundleName | string | Yes | Bundle name of an application. | -| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| callback | AsyncCallback\<[BundleInfo](js-apis-bundle-BundleInfo.md)> | Yes | Callback used to return the bundle information. | +| Name | Type | Mandatory| Description | +| ----------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| bundleName | string | Yes | Bundle name of an application. | +| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the bundle information flags in [BundleFlag](#bundleflag).| +| callback | AsyncCallback\<[BundleInfo](js-apis-bundle-BundleInfo.md)> | Yes | Callback used to return the bundle information. | **Example** @@ -346,12 +346,12 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | -------------------------- | ---- | --------------------------------------- | -| bundleName | string | Yes | Bundle name of an application. | -| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| options | [BundleOptions](#bundleoptions) | Yes | Includes **userId**. | -| callback | AsyncCallback\<[BundleInfo](js-apis-bundle-BundleInfo.md)> | Yes | Callback used to return the bundle information. | +| Name | Type | Mandatory| Description | +| ----------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| bundleName | string | Yes | Bundle name of an application. | +| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the bundle information flags in [BundleFlag](#bundleflag).| +| options | [BundleOptions](#bundleoptions) | Yes | Includes **userId**. | +| callback | AsyncCallback\<[BundleInfo](js-apis-bundle-BundleInfo.md)> | Yes | Callback used to return the bundle information. | **Example** @@ -847,10 +847,10 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | ------ | ---- | --------------------------------------- | -| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| userId | number | No | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | +| Name | Type | Mandatory| Description | +| ----------- | ------ | ---- | ------------------------------------------------------------ | +| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the application information flags in [BundleFlag](#bundleflag).| +| userId | number | No | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | **Return value** @@ -889,11 +889,11 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | -------------------------------------- | ---- | --------------------------------------- | -| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| userId | number | No | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | -| callback | AsyncCallback> | Yes | Callback used to return the application information. | +| Name | Type | Mandatory| Description | +| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the application information flags in [BundleFlag](#bundleflag).| +| userId | number | No | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | +| callback | AsyncCallback> | Yes | Callback used to return the application information. | **Example** @@ -926,10 +926,10 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | -------------------------------------- | ---- | --------------------------------------- | -| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. The value must be greater than or equal to 0.| -| callback | AsyncCallback> | Yes | Callback used to return the application information. | +| Name | Type | Mandatory| Description | +| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| bundleFlags | number | Yes | Type of information that will be returned. The default value is **0**. For details on the available enumerated values, see the application information flags in [BundleFlag](#bundleflag).| +| callback | AsyncCallback> | Yes | Callback used to return the application information. | **Example** @@ -959,7 +959,7 @@ SystemCapability.BundleManager.BundleFramework | Name | Type | Mandatory | Description | | ---------- | ------ | ---- | ------------ | | hapFilePath | string | Yes | Path where the HAP file is stored. The path should point to the relative directory of the current application's data directory.| -| bundleFlags | number | Yes | Flags used to specify information contained in the **BundleInfo** object that will be returned. The default value is **0**. The value must be greater than or equal to 0.| +| bundleFlags | number | Yes | Flags used to specify information contained in the **BundleInfo** object that will be returned. The default value is **0**. For details on the available enumerated values, see the bundle information flags in [BundleFlag](#bundleflag).| **Return value** | Type | Description | @@ -994,7 +994,7 @@ SystemCapability.BundleManager.BundleFramework | Name | Type | Mandatory | Description | | ---------- | ------ | ---- | ------------ | | hapFilePath | string | Yes | Path where the HAP file is stored. The path should point to the relative directory of the current application's data directory.| -| bundleFlags | number | Yes | Flags used to specify information contained in the **BundleInfo** object that will be returned. The default value is **0**. The value must be greater than or equal to 0.| +| bundleFlags | number | Yes | Flags used to specify information contained in the **BundleInfo** object that will be returned. The default value is **0**. For details on the available enumerated values, see the bundle information flags in [BundleFlag](#bundleflag).| | callback| AsyncCallback\<[BundleInfo](js-apis-bundle-BundleInfo.md)> | Yes | Callback used to return the information about the bundles.| **Example** @@ -1474,7 +1474,7 @@ SystemCapability.BundleManager.BundleFramework | Name | Type | Mandatory | Description | | ----------- | ------ | ---- | ------------------------------------- | | want | [Want](js-apis-application-Want.md) | Yes | Want that contains the bundle name. | -| bundleFlags | number | Yes | Ability information to be returned. The default value is **0**. The value must be greater than or equal to 0.| +| bundleFlags | number | Yes | Ability information to be returned. The default value is **0**. For details on the available enumerated values, see the ability information flags in [BundleFlag](#bundleflag).| | userId | number | No | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | **Return value** @@ -1518,12 +1518,12 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | ---------------------------------- | ---- | ------------------------------------- | -| want | [Want](js-apis-application-Want.md) | Yes | Want that contains the bundle name. | -| bundleFlags | number | Yes | Ability information to be returned. The default value is **0**. The value must be greater than or equal to 0.| -| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | -| callback | AsyncCallback> | Yes | Callback used to return the ability information. | +| Name | Type | Mandatory| Description | +| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| want | [Want](js-apis-application-Want.md) | Yes | Want that contains the bundle name. | +| bundleFlags | number | Yes | Ability information to be returned. The default value is **0**. For details on the available enumerated values, see the ability information flags in [BundleFlag](#bundleflag).| +| userId | number | Yes | User ID. The default value is the user ID of the caller. The value must be greater than or equal to 0. | +| callback | AsyncCallback> | Yes | Callback used to return the ability information. | **Example** @@ -1559,11 +1559,11 @@ SystemCapability.BundleManager.BundleFramework **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | ---------------------------------- | ---- | ------------------------------------- | -| want | [Want](js-apis-application-Want.md) | Yes | Want that contains the bundle name. | -| bundleFlags | number | Yes | Ability information to be returned. The default value is **0**. The value must be greater than or equal to 0.| -| callback | AsyncCallback> | Yes | Callback used to return the ability information. | +| Name | Type | Mandatory| Description | +| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| want | [Want](js-apis-application-Want.md) | Yes | Want that contains the bundle name. | +| bundleFlags | number | Yes | Ability information to be returned. The default value is **0**. For details on the available enumerated values, see the ability information flags in [BundleFlag](#bundleflag).| +| callback | AsyncCallback> | Yes | Callback used to return the ability information. | **Example** diff --git a/en/application-dev/reference/apis/js-apis-Context.md b/en/application-dev/reference/apis/js-apis-Context.md index ce415ad942510c481755380bdd90adb7eb1c75ae..c432f719593a2aa3f32db509b339b2cc783ea5b4 100644 --- a/en/application-dev/reference/apis/js-apis-Context.md +++ b/en/application-dev/reference/apis/js-apis-Context.md @@ -4,8 +4,7 @@ The **Context** module provides context for abilities or applications. It allows > **NOTE** > -> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> +> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the FA model. ## Usage @@ -30,9 +29,9 @@ If this API is called for the first time, a root directory will be created. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | -------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the local root directory.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the local root directory.| **Example** @@ -58,8 +57,8 @@ If this API is called for the first time, a root directory will be created. **Return value** -| Type | Description | -| ---------------- | ---------------------- | +| Type | Description | +| ---------------- | ----------- | | Promise\ | Promise used to return the local root directory.| **Example** @@ -84,11 +83,11 @@ Verifies whether a specific PID and UID have the given permission. This API uses **Parameters** -| Name | Type | Mandatory| Description | -| ---------- | --------------------------------------- | ---- | ------------------------------------- | -| permission | string | Yes | Name of the permission to verify. | -| options | [PermissionOptions](#permissionoptions) | Yes | Permission options. | -| callback | AsyncCallback\ | Yes | Callback used to return the permission verification result. The value **0** means that the PID and UID have the given permission, and the value **-1** means the opposite.| +| Name | Type | Mandatory | Description | +| ---------- | --------------------------------------- | ---- | -------------------- | +| permission | string | Yes | Name of the permission to verify. | +| options | [PermissionOptions](#permissionoptions) | Yes | Permission options. | +| callback | AsyncCallback\ | Yes | Callback used to return the permission verification result. The value **0** means that the PID and UID have the given permission, and the value **-1** means the opposite.| **Example** @@ -113,10 +112,10 @@ Verifies whether the current PID and UID have the given permission. This API use **Parameters** -| Name | Type | Mandatory| Description | -| ---------- | ---------------------- | ---- | ------------------------------------- | -| permission | string | Yes | Name of the permission to verify. | -| callback | AsyncCallback\ | Yes | Callback used to return the permission verification result. The value **0** means that the PID and UID have the given permission, and the value **-1** means the opposite.| +| Name | Type | Mandatory | Description | +| ---------- | ---------------------- | ---- | -------------------- | +| permission | string | Yes | Name of the permission to verify. | +| callback | AsyncCallback\ | Yes | Callback used to return the permission verification result. The value **0** means that the PID and UID have the given permission, and the value **-1** means the opposite.| **Example** @@ -136,15 +135,15 @@ Verifies whether a specific PID and UID have the given permission. This API uses **Parameters** -| Name | Type | Mandatory| Description | -| ---------- | --------------------------------------- | ---- | ---------------- | -| permission | string | Yes | Name of the permission to verify.| -| options | [PermissionOptions](#permissionoptions) | No | Permission options. | +| Name | Type | Mandatory | Description | +| ---------- | --------------------------------------- | ---- | -------- | +| permission | string | Yes | Name of the permission to verify.| +| options | [PermissionOptions](#permissionoptions) | No | Permission options. | **Return value** -| Type | Description | -| ---------------- | ----------------------------------------------------------- | +| Type | Description | +| ---------------- | ---------------------------------- | | Promise\ | Promise used to return the permission verification result. The value **0** means that the PID and UID have the given permission, and the value **-1** means the opposite.| **Example** @@ -171,11 +170,11 @@ Requests certain permissions from the system. This API uses an asynchronous call **Parameters** -| Name | Type | Mandatory| Description | -| -------------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | -| permissions | Array\ | Yes | Permissions to request. This parameter cannot be **null**. | -| requestCode | number | Yes | Request code to be passed to **PermissionRequestResult**.| -| resultCallback | AsyncCallback<[PermissionRequestResult](#permissionrequestresult)> | Yes | Permission request result. | +| Name | Type | Mandatory | Description | +| -------------- | ---------------------------------------- | ---- | ----------------------------------- | +| permissions | Array\ | Yes | Permissions to request. This parameter cannot be **null**. | +| requestCode | number | Yes | Request code to be passed to **PermissionRequestResult**.| +| resultCallback | AsyncCallback<[PermissionRequestResult](#permissionrequestresult)> | Yes | Permission request result. | **Example** @@ -207,9 +206,9 @@ Obtains information about the current application. This API uses an asynchronous **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------- | ---- | ------------------------ | -| callback | AsyncCallback\ | Yes | Callback used to return the application information.| +| Name | Type | Mandatory | Description | +| -------- | ------------------------------- | ---- | ------------ | +| callback | AsyncCallback\ | Yes | Callback used to return the application information.| **Example** @@ -231,8 +230,8 @@ Obtains information about the current application. This API uses a promise to re **Return value** -| Type | Description | -| ------------------------- | ------------------ | +| Type | Description | +| ------------------------- | --------- | | Promise\ | Promise used to return the application information.| **Example** @@ -258,9 +257,9 @@ Obtains the bundle name of this ability. This API uses an asynchronous callback **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ----------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the bundle name.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ------------------ | +| callback | AsyncCallback\ | Yes | Callback used to return the bundle name.| **Example** @@ -282,8 +281,8 @@ Obtains the bundle name of this ability. This API uses a promise to return the r **Return value** -| Type | Description | -| ---------------- | ------------------------- | +| Type | Description | +| ---------------- | ---------------- | | Promise\ | Promise used to return the bundle name.| **Example** @@ -307,9 +306,9 @@ Obtains the display orientation of this ability. This API uses an asynchronous c **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ----------------------------- | -| callback | AsyncCallback\<[bundle.DisplayOrientation](js-apis-bundle.md#displayorientation)> | Yes | Callback used to return the display orientation.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------ | +| callback | AsyncCallback\<[bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation)> | Yes | Callback used to return the display orientation.| **Example** @@ -329,9 +328,9 @@ Obtains the display orientation of this ability. This API uses a promise to retu **Return value** -| Type | Description | -| ---------------- | ------------------------- | -| Promise\<[bundle.DisplayOrientation](js-apis-bundle.md#displayorientation)> | Promise used to return the display orientation.| +| Type | Description | +| ---------------------------------------- | --------- | +| Promise\<[bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation)> | Promise used to return the display orientation.| **Example** @@ -348,16 +347,16 @@ context.getDisplayOrientation().then((data) => { setDisplayOrientation(orientation: bundle.DisplayOrientation, callback: AsyncCallback\): void -Obtains the display orientation for this ability. This API uses an asynchronous callback to return the result. +Sets the display orientation for this ability. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ----------------------------- | -| orientation | [bundle.DisplayOrientation](js-apis-bundle.md#displayorientation) | Yes | Display orientation to set.| -| callback | AsyncCallback\<[bundle.DisplayOrientation](js-apis-bundle.md#displayorientation)> | Yes | Callback used to return the display orientation.| +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------- | ---- | ------------ | +| orientation | [bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation) | Yes | Display orientation to set.| +| callback | AsyncCallback\<[bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation)> | Yes | Callback used to return the display orientation. | **Example** @@ -375,16 +374,16 @@ context.setDisplayOrientation(orientation, (err) => { setDisplayOrientation(orientation: bundle.DisplayOrientation): Promise\; -Obtains the display orientation for this ability. This API uses a promise to return the result. +Sets the display orientation for this ability. This API uses a promise to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Return value** -| Type | Description | -| ---------------- | ------------------------- | -| orientation | [bundle.DisplayOrientation](js-apis-bundle.md#displayorientation) | Yes | Display orientation to set.| -| Promise\<[bundle.DisplayOrientation](js-apis-bundle.md#displayorientation)> | Promise used to return the display orientation.| +| Type | Description | +| ---------------------------------------- | ---------------------------------------- | +| orientation | [bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation) | +| Promise\<[bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation)> | Promise used to return the display orientation. | **Example** @@ -403,16 +402,16 @@ context.setDisplayOrientation(orientation).then((data) => { setShowOnLockScreen(show: boolean, callback: AsyncCallback\): void -Sets whether to show this feature at the top of the lock screen each time the lock screen is displayed so that the feature remains activated. This API uses an asynchronous callback to return the result. +Sets whether to show this feature at the top of the lock screen so that the feature remains activated. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ----------------------------- | -| show | boolean | Yes | Whether to show this feature at the top of the lock screen. The value **true** means to show this feature at the top of the lock screen, and **false** means the opposite.| -| callback | AsyncCallback\ | Yes | Callback used to return the result.| +| Name | Type | Mandatory | Description | +| -------- | -------------------- | ---- | ---------------------------------------- | +| show | boolean | Yes | Whether to show this feature at the top of the lock screen. The value **true** means to show this feature at the top of the lock screen, and **false** means the opposite.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** @@ -429,21 +428,21 @@ context.setShowOnLockScreen(show, (err) => { setShowOnLockScreen(show: boolean): Promise\; -Sets whether to show this feature at the top of the lock screen each time the lock screen is displayed so that the feature remains activated. This API uses a promise to return the result. +Sets whether to show this feature at the top of the lock screen so that the feature remains activated. This API uses a promise to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ----------------------------- | -| show | boolean | Yes | Whether to show this feature at the top of the lock screen. The value **true** means to show this feature at the top of the lock screen, and **false** means the opposite.| +| Name | Type | Mandatory | Description | +| ---- | ------- | ---- | ---------------------------------------- | +| show | boolean | Yes | Whether to show this feature at the top of the lock screen. The value **true** means to show this feature at the top of the lock screen, and **false** means the opposite.| **Return value** -| Type | Description | -| ---------------- | ------------------------- | -| Promise\| Promise used to return the result.| +| Type | Description | +| -------------- | --------------- | +| Promise\ | Promise used to return the result.| **Example** @@ -467,10 +466,10 @@ Sets whether to wake up the screen when this feature is restored. This API uses **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ----------------------------- | -| wakeUp | boolean | Yes | Whether to wake up the screen. The value **true** means to wake up the screen, and **false** means the opposite.| -| callback | AsyncCallback\ | Yes | Callback used to return the result.| +| Name | Type | Mandatory | Description | +| -------- | -------------------- | ---- | --------------------------------- | +| wakeUp | boolean | Yes | Whether to wake up the screen. The value **true** means to wake up the screen, and **false** means the opposite.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** @@ -493,15 +492,15 @@ Sets whether to wake up the screen when this feature is restored. This API uses **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ----------------------------- | -| wakeUp | boolean | Yes | Whether to wake up the screen. The value **true** means to wake up the screen, and **false** means the opposite.| +| Name | Type | Mandatory | Description | +| ------ | ------- | ---- | --------------------------------- | +| wakeUp | boolean | Yes | Whether to wake up the screen. The value **true** means to wake up the screen, and **false** means the opposite.| **Return value** -| Type | Description | -| ---------------- | ------------------------- | -| Promise\| Promise used to return the result.| +| Type | Description | +| -------------- | --------------- | +| Promise\ | Promise used to return the result.| **Example** @@ -528,9 +527,9 @@ Obtains information about the current process, including the PID and process nam **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | -------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the process information.| +| Name | Type | Mandatory | Description | +| -------- | --------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | Yes | Callback used to return the process information.| **Example** @@ -552,8 +551,8 @@ Obtains information about the current process, including the PID and process nam **Return value** -| Type | Description | -| --------------------- | -------------- | +| Type | Description | +| --------------------- | ------- | | Promise\ | Promise used to return the process information.| **Example** @@ -581,9 +580,9 @@ This API is available only to Page abilities. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ---------------------------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the **ohos.bundle.ElementName** object.| +| Name | Type | Mandatory | Description | +| -------- | --------------------------- | ---- | -------------------------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the **ohos.bundle.ElementName** object.| **Example** @@ -607,8 +606,8 @@ This API is available only to Page abilities. **Return value** -| Type | Description | -| --------------------- | ------------------------------------------ | +| Type | Description | +| --------------------- | ------------------------------------ | | Promise\ | Promise used to return the **ohos.bundle.ElementName** object.| **Example** @@ -632,9 +631,9 @@ Obtains the name of the current process. This API uses an asynchronous callback **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | -------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the process name.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ---------- | +| callback | AsyncCallback\ | Yes | Callback used to return the process name.| **Example** @@ -656,8 +655,8 @@ Obtains the name of the current process. This API uses a promise to return the r **Return value** -| Type | Description | -| ---------------- | -------------------- | +| Type | Description | +| ---------------- | ---------- | | Promise\ | Promise used to return the process name.| **Example** @@ -683,9 +682,9 @@ Obtains the bundle name of the calling ability. This API uses an asynchronous ca **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the bundle name.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ---------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the bundle name.| **Example** @@ -707,8 +706,8 @@ Obtains the bundle name of the calling ability. This API uses a promise to retur **Return value** -| Type | Description | -| --------------- | ------------------------- | +| Type | Description | +| ---------------- | -------------- | | Promise\ | Promise used to return the bundle name.| **Example** @@ -732,9 +731,9 @@ Obtains the cache directory of the application in the internal storage. This API **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the cache directory.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | --------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the cache directory.| **Example** @@ -760,8 +759,8 @@ Obtains the cache directory of the application in the internal storage. This API **Return value** -| Type | Description | -| --------------- | ------------------------- | +| Type | Description | +| ---------------- | --------------- | | Promise\ | Promise used to return the cache directory.| **Example** @@ -785,9 +784,9 @@ Obtains the file directory of the application in the internal storage. This API **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the file directory.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the file directory.| **Example** @@ -813,8 +812,8 @@ Obtains the file directory of the application in the internal storage. This API **Return value** -| Type | Description | -| --------------- | ------------------------- | +| Type | Description | +| ---------------- | ------------------- | | Promise\ | Promise used to return the file directory.| **Example** @@ -840,9 +839,9 @@ If the distributed file path does not exist, the system will create one and retu **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the distributed file path. If the distributed file path does not exist, the system will create one and return the created path.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ---------------------------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the distributed file path. If the distributed file path does not exist, the system will create one and return the created path.| **Example** @@ -870,8 +869,8 @@ If the distributed file path does not exist, the system will create one and retu **Return value** -| Type | Description | -| --------------- | ------------------------- | +| Type | Description | +| ---------------- | ----------------------------------- | | Promise\ | Promise used to return the distributed file path. If this API is called for the first time, a new path will be created.| **Example** @@ -894,9 +893,9 @@ Obtains the application type. This API uses an asynchronous callback to return t **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the application type.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | -------------------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the application type.| **Example** @@ -922,8 +921,8 @@ Obtains the application type. This API uses a promise to return the result. **Return value** -| Type | Description | -| --------------- | ------------------------- | +| Type | Description | +| ---------------- | ------------------ | | Promise\ | Promise used to return the application type.| **Example** @@ -946,9 +945,9 @@ Obtains the **ModuleInfo** object of the application. This API uses an asynchron **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\<[HapModuleInfo](js-apis-bundle-HapModuleInfo.md)> | Yes | Callback used to return the **ModuleInfo** object.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------------------------------------- | +| callback | AsyncCallback\<[HapModuleInfo](js-apis-bundle-HapModuleInfo.md)> | Yes | Callback used to return the **ModuleInfo** object.| **Example** @@ -974,8 +973,8 @@ Obtains the **ModuleInfo** object of the application. This API uses a promise to **Return value** -| Type | Description | -| --------------- | ------------------------- | +| Type | Description | +| ---------------------------------------- | ------------------ | | Promise\<[HapModuleInfo](js-apis-bundle-HapModuleInfo.md)> | Promise used to return the **ModuleInfo** object.| **Example** @@ -998,9 +997,9 @@ Obtains the version information of this application. This API uses an asynchrono **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\<[AppVersionInfo](#appversioninfo)> | Yes | Callback used to return the version information.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------------------------ | +| callback | AsyncCallback\<[AppVersionInfo](#appversioninfo)> | Yes | Callback used to return the version information.| **Example** @@ -1026,8 +1025,8 @@ Obtains the version information of this application. This API uses a promise to **Return value** -| Type | Description | -| --------------- | ------------------------- | +| Type | Description | +| ---------------------------------------- | --------- | | Promise\<[AppVersionInfo](#appversioninfo)> | Promise used to return the version information.| **Example** @@ -1050,9 +1049,9 @@ Obtains information about this ability. This API uses an asynchronous callback t **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\<[AbilityInfo](js-apis-bundle-AbilityInfo.md)> | Yes | Callback used to return the ability information.| +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------------------------------------- | +| callback | AsyncCallback\<[AbilityInfo](js-apis-bundle-AbilityInfo.md)> | Yes | Callback used to return the ability information.| **Example** @@ -1078,8 +1077,8 @@ Obtains information about this ability. This API uses a promise to return the re **Return value** -| Type | Description | -| --------------- | ------------------------- | +| Type | Description | +| ---------------------------------------- | ------------------ | | Promise\<[AbilityInfo](js-apis-bundle-AbilityInfo.md)> | Promise used to return the ability information.| **Example** @@ -1102,9 +1101,9 @@ Obtains the context of the application. **Return value** -| Type | Description | -| --------- |------ | -| Context | Application context.| +| Type | Description | +| ------- | ---------- | +| Context | Application context.| **Example** @@ -1117,15 +1116,15 @@ var context = featureAbility.getContext().getApplicationContext(); isUpdatingConfigurations(callback: AsyncCallback\): void; -Checks whether the configuration of this ability is being changed. This API uses an asynchronous callback to return the result. +Checks whether the configuration of this ability is being updated. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\ | Yes | Returns **true** if the configuration of the capability is being changed; returns **false** otherwise.| +| Name | Type | Mandatory | Description | +| -------- | ----------------------- | ---- | ----------------------------- | +| callback | AsyncCallback\ | Yes | Returns **true** if the configuration of the capability is being updated; returns **false** otherwise.| **Example** @@ -1145,15 +1144,15 @@ context.isUpdatingConfigurations((err, data) => { isUpdatingConfigurations(): Promise\; -Checks whether the configuration of this ability is being changed. This API uses a promise to return the result. +Checks whether the configuration of this ability is being updated. This API uses a promise to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Return value** -| Type | Description | -| --------------- | ------------------------- | -|Promise\ | Returns **true** if the configuration of the capability is being changed; returns **false** otherwise.| +| Type | Description | +| ----------------- | ----------------------------- | +| Promise\ | Returns **true** if the configuration of the capability is being updated; returns **false** otherwise.| **Example** @@ -1175,9 +1174,9 @@ Notifies the system of the time required to draw this page function. This API us **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result.| +| Name | Type | Mandatory | Description | +| -------- | -------------------- | ---- | ----------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| **Example** @@ -1203,9 +1202,9 @@ Notifies the system of the time required to draw this page function. This API us **Return value** -| Type | Description | -| --------------- | ------------------------- | -|Promise\ | Promise used to return the result.| +| Type | Description | +| -------------- | --------------- | +| Promise\ | Promise used to return the result.| **Example** @@ -1222,27 +1221,27 @@ context.printDrawnCompleted().then((data) => { **System capability**: SystemCapability.Ability.AbilityRuntime.Core -| Name| Readable/Writable| Type | Mandatory| Description | -| ---- | -------- | ------ | ---- | ------ | -| pid | Read-only | number | No | Process ID.| -| uid | Read-only | number | No | User ID.| +| Name | Readable/Writable| Type | Mandatory | Description | +| ---- | ---- | ------ | ---- | ----- | +| pid | Read-only | number | No | Process ID.| +| uid | Read-only | number | No | User ID.| ## PermissionRequestResult7+ **System capability**: SystemCapability.Ability.AbilityRuntime.Core -| Name | Readable/Writable| Type | Mandatory| Description | -| ----------- | -------- | -------------- | ---- | ------------------ | -| requestCode | Read-only | number | Yes | Request code passed.| -| permissions | Read-only | Array\ | Yes | Permissions requested. | -| authResults | Read-only | Array\ | Yes | Permission request result. | +| Name | Readable/Writable| Type | Mandatory | Description | +| ----------- | ---- | -------------- | ---- | ---------- | +| requestCode | Read-only | number | Yes | Request code passed.| +| permissions | Read-only | Array\ | Yes | Permissions requested. | +| authResults | Read-only | Array\ | Yes | Permission request result. | ## AppVersionInfo7+ **System capability**: SystemCapability.Ability.AbilityRuntime.Core -| Name | Type| Readable | Writable | Description| -| ------ | ------ | ------| ------ | ------ | -| appName | string | Yes | No | Module name. | -| versionCode | number | Yes | No | Module description. | -| versionName | string | Yes | No | Module description ID. | +| Name | Type | Readable | Writable | Description | +| ----------- | ------ | ---- | ---- | ------- | +| appName | string | Yes | No | Module name. | +| versionCode | number | Yes | No | Module description.| +| versionName | string | Yes | No | Module description ID.| diff --git a/en/application-dev/reference/apis/js-apis-ability-context.md b/en/application-dev/reference/apis/js-apis-ability-context.md index e2333a523a918e229c6a35c4e341df9383bfb26a..3b5d0bba1bb5954d3365d97cde619f5931c0f7a3 100644 --- a/en/application-dev/reference/apis/js-apis-ability-context.md +++ b/en/application-dev/reference/apis/js-apis-ability-context.md @@ -2,7 +2,7 @@ The **AbilityContext** module, inherited from **Context**, implements the context for abilities. -This module provides APIs for accessing ability-specific resources. You can use the APIs to start and terminate an ability, obtain the caller interface, and request permissions from users by displaying a pop-up window. +This module provides APIs for accessing ability-specific resources. You can use the APIs to start and terminate an ability, obtain the caller interface, and request permissions from users by displaying a dialog box. > **NOTE** > @@ -40,13 +40,11 @@ Starts an ability. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core -**System API**: This is a system API and cannot be called by third-party applications. - **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** @@ -71,13 +69,11 @@ Starts an ability with start options specified. This API uses an asynchronous ca **System capability**: SystemCapability.Ability.AbilityRuntime.Core -**System API**: This is a system API and cannot be called by third-party applications. - **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| | options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| @@ -106,13 +102,11 @@ Starts an ability. This API uses a promise to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core -**System API**: This is a system API and cannot be called by third-party applications. - **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| | options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| **Return value** @@ -153,7 +147,7 @@ Starts an ability. This API uses an asynchronous callback to return the result w | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want |[Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want |[Want](js-apis-application-Want.md) | Yes| Information about the target ability.| | callback | AsyncCallback<[AbilityResult](js-apis-featureAbility.md#abilityresult)> | Yes| Callback used to return the result.| @@ -181,7 +175,7 @@ Starts an ability with start options specified. This API uses an asynchronous ca | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want |[Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want |[Want](js-apis-application-Want.md) | Yes| Information about the target ability.| | options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback<[AbilityResult](js-apis-featureAbility.md#abilityresult)> | Yes| Callback used to return the result.| @@ -214,7 +208,7 @@ Starts an ability. This API uses a promise to return the result when the ability | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| | options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| @@ -239,7 +233,7 @@ Starts an ability. This API uses a promise to return the result when the ability ## AbilityContext.startAbilityForResultWithAccount -startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback): void; +startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; Starts an ability. This API uses an asynchronous callback to return the result when the account of the ability is destroyed. @@ -253,8 +247,8 @@ Starts an ability. This API uses an asynchronous callback to return the result w | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** @@ -289,8 +283,8 @@ Starts an ability with start options specified. This API uses an asynchronous ca | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -312,7 +306,7 @@ Starts an ability with start options specified. This API uses an asynchronous ca ``` - ## AbilityContext.startAbilityForResultWithAccount +## AbilityContext.startAbilityForResultWithAccount startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\; @@ -328,8 +322,8 @@ Starts an ability with start options specified. This API uses a promise to retur | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| **Return value** @@ -358,7 +352,271 @@ Starts an ability with start options specified. This API uses a promise to retur console.log('---------- startAbilityForResultWithAccount fail, err: -----------', err); }) ``` +## AbilityContext.startServiceExtensionAbility + +startServiceExtensionAbility(want: Want, callback: AsyncCallback\): void; + +Starts a new Service Extension ability. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "MainAbility" + }; + this.context.startServiceExtensionAbility(want, (err) => { + console.log('---------- startServiceExtensionAbility fail, err: -----------', err); + }); + ``` + +## AbilityContext.startServiceExtensionAbility + +startServiceExtensionAbility(want: Want): Promise\; + +Starts a new Service Extension ability. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "MainAbility" + }; + this.context.startServiceExtensionAbility(want) + .then((data) => { + console.log('---------- startServiceExtensionAbility success, data: -----------', data); + }) + .catch((err) => { + console.log('---------- startServiceExtensionAbility fail, err: -----------', err); + }) + ``` +## AbilityContext.startServiceExtensionAbilityWithAccount + +startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; + +Starts a new Service Extension ability with the account ID specified. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "MainAbility" + }; + var accountId = 100; + this.context.startServiceExtensionAbilityWithAccount(want,accountId, (err) => { + console.log('---------- startServiceExtensionAbilityWithAccount fail, err: -----------', err); + }); + ``` + +## AbilityContext.startServiceExtensionAbilityWithAccount + +startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\; + +Starts a new Service Extension ability with the account ID specified. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "MainAbility" + }; + var accountId = 100; + this.context.startServiceExtensionAbilityWithAccount(want,accountId) + .then((data) => { + console.log('---------- startServiceExtensionAbilityWithAccount success, data: -----------', data); + }) + .catch((err) => { + console.log('---------- startServiceExtensionAbilityWithAccount fail, err: -----------', err); + }) + ``` +## AbilityContext.stopServiceExtensionAbility +stopServiceExtensionAbility(want: Want, callback: AsyncCallback\): void; + +Stops a Service Extension ability in the same application. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "MainAbility" + }; + this.context.stopServiceExtensionAbility(want, (err) => { + console.log('---------- stopServiceExtensionAbility fail, err: -----------', err); + }); + ``` + +## AbilityContext.stopServiceExtensionAbility + +stopServiceExtensionAbility(want: Want): Promise\; + +Stops a Service Extension ability in the same application. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "MainAbility" + }; + this.context.stopServiceExtensionAbility(want) + .then((data) => { + console.log('---------- stopServiceExtensionAbility success, data: -----------', data); + }) + .catch((err) => { + console.log('---------- stopServiceExtensionAbility fail, err: -----------', err); + }) + ``` + +## AbilityContext.stopServiceExtensionAbilityWithAccount + +stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; + +Stops a Service Extension ability in the same application with the account ID specified. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "MainAbility" + }; + var accountId = 100; + this.context.stopServiceExtensionAbilityWithAccount(want,accountId, (err) => { + console.log('---------- stopServiceExtensionAbilityWithAccount fail, err: -----------', err); + }); + ``` + +## AbilityContext.stopServiceExtensionAbilityWithAccount + +stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\; + +Stops a Service Extension ability in the same application with the account ID specified. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "MainAbility" + }; + var accountId = 100; + this.context.stopServiceExtensionAbilityWithAccount(want,accountId) + .then((data) => { + console.log('---------- stopServiceExtensionAbilityWithAccount success, data: -----------', data); + }) + .catch((err) => { + console.log('---------- stopServiceExtensionAbilityWithAccount fail, err: -----------', err); + }) + ``` ## AbilityContext.terminateSelf @@ -412,7 +670,7 @@ Terminates this ability. This API uses a promise to return the result. terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void; -Terminates this ability. This API uses an asynchronous callback to return the information to the caller of **startAbilityForResult**. +Terminates this ability. This API uses an asynchronous callback to return the ability result information. It is used together with **startAbilityForResult**. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -426,11 +684,17 @@ Terminates this ability. This API uses an asynchronous callback to return the in **Example** ```js - this.context.terminateSelfWithResult( - { - want: {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo"}, - resultCode: 100 - }, (error) => { + var want = { + "bundleName": "com.extreme.myapplication", + "abilityName": "SecondAbility" + } + var resultCode = 100; + // AbilityResult information returned to the caller. + var abilityResult = { + want, + resultCode + } + this.context.terminateSelfWithResult(abilityResult, (error) => { console.log("terminateSelfWithResult is called = " + error.code) } ); @@ -441,7 +705,7 @@ Terminates this ability. This API uses an asynchronous callback to return the in terminateSelfWithResult(parameter: AbilityResult): Promise<void>; -Terminates this ability. This API uses a promise to return information to the caller of **startAbilityForResult**. +Terminates this ability. This API uses a promise to return the ability result information. It is used together with **startAbilityForResult**. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -460,11 +724,17 @@ Terminates this ability. This API uses a promise to return information to the ca **Example** ```js - this.context.terminateSelfWithResult( - { - want: {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo"}, - resultCode: 100 - }).then((result) => { + var want = { + "bundleName": "com.extreme.myapplication", + "abilityName": "SecondAbility" + } + var resultCode = 100; + // AbilityResult information returned to the caller. + var abilityResult = { + want, + resultCode + } + this.context.terminateSelfWithResult(abilityResult).then((result) => { console.log("terminateSelfWithResult") } ) @@ -484,8 +754,8 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template to connect this ability to | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | No| Remote object instance.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | No| Parameters for the connection.| **Return value** @@ -515,7 +785,7 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template to connect this ability to connectAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number; -Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect this ability to another ability. +Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect this ability to another ability with the account ID specified. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -527,8 +797,8 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | No| Parameters for the connection.| **Return value** @@ -626,7 +896,7 @@ Obtains the caller interface of the specified ability, and if the specified abil | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to start, including the ability name, bundle name, and device ID. If the device ID is left blank or the default value is used, the local ability will be started.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability, including the ability name, bundle name, and device ID. If the device ID is left blank or the default value is used, it indicates the local device.| **Return value** @@ -671,8 +941,8 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** @@ -706,8 +976,8 @@ Starts an ability with the account ID and start options specified. This API uses | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -745,8 +1015,8 @@ Starts an ability with the account ID specified. This API uses a promise to retu | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| **Example** @@ -774,7 +1044,7 @@ Starts an ability with the account ID specified. This API uses a promise to retu requestPermissionsFromUser(permissions: Array<string>, requestCallback: AsyncCallback<PermissionRequestResult>) : void; -Requests permissions from the user by displaying a pop-up window. This API uses an asynchronous callback to return the result. +Requests permissions from the user by displaying a dialog box. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -783,7 +1053,7 @@ Requests permissions from the user by displaying a pop-up window. This API uses | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | permissions | Array<string> | Yes| Permissions to request.| -| callback | AsyncCallback<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Yes| Callback used to return the permission request result.| +| callback | AsyncCallback<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Yes| Callback used to return the result.| **Example** @@ -800,7 +1070,7 @@ Requests permissions from the user by displaying a pop-up window. This API uses requestPermissionsFromUser(permissions: Array<string>) : Promise<PermissionRequestResult>; -Requests permissions from the user by displaying a pop-up window. This API uses a promise to return the result. +Requests permissions from the user by displaying a dialog box. This API uses a promise to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -814,7 +1084,7 @@ Requests permissions from the user by displaying a pop-up window. This API uses | Type| Description| | -------- | -------- | -| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Promise used to return the permission request result.| +| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Promise used to return the result.| **Example** @@ -1006,7 +1276,7 @@ Checks whether this ability is in the terminating state. | Type| Description| | -------- | -------- | -| bool | The value **true** means that the ability is in terminating state, and **false** means the opposite.| +| boolean| The value **true** means that the ability is in the terminating state, and **false** means the opposite.| **Example** diff --git a/en/application-dev/reference/apis/js-apis-ability-wantConstant.md b/en/application-dev/reference/apis/js-apis-ability-wantConstant.md index c2bb08c5314a44dcf6f4ad9246e6ee08a313ecd8..545da5d468feefce2440a356812356e6206e11e3 100644 --- a/en/application-dev/reference/apis/js-apis-ability-wantConstant.md +++ b/en/application-dev/reference/apis/js-apis-ability-wantConstant.md @@ -1,6 +1,6 @@ # wantConstant -The **wantConstant** module provides the action, entity, and flags used in **Want** objects. +The **wantConstant** module provides the actions, entities, and flags used in **Want** objects. > **NOTE** > @@ -23,15 +23,15 @@ Enumerates the action constants of the **Want** object. | ACTION_HOME | ohos.want.action.home | Action of returning to the home page. | | ACTION_DIAL | ohos.want.action.dial | Action of launching the numeric keypad. | | ACTION_SEARCH | ohos.want.action.search | Action of launching the search function. | -| ACTION_WIRELESS_SETTINGS | ohos.settings.wireless | Action of launching the UI that provides radio network settings, for example, Wi-Fi option. | +| ACTION_WIRELESS_SETTINGS | ohos.settings.wireless | Action of launching the UI that provides wireless network settings, for example, Wi-Fi options. | | ACTION_MANAGE_APPLICATIONS_SETTINGS | ohos.settings.manage.applications | Action of launching the UI for managing installed applications. | | ACTION_APPLICATION_DETAILS_SETTINGS | ohos.settings.application.details | Action of launching the UI that displays the details of an application. | | ACTION_SET_ALARM | ohos.want.action.setAlarm | Action of launching the UI for setting the alarm clock. | -| ACTION_SHOW_ALARMS | ohos.want.action.showAlarms | Action of launching the UI that displays all clock alarms. | +| ACTION_SHOW_ALARMS | ohos.want.action.showAlarms | Action of launching the UI that displays all alarms. | | ACTION_SNOOZE_ALARM | ohos.want.action.snoozeAlarm | Action of launching the UI for snoozing an alarm. | | ACTION_DISMISS_ALARM | ohos.want.action.dismissAlarm | Action of launching the UI for deleting an alarm. | | ACTION_DISMISS_TIMER | ohos.want.action.dismissTimer | Action of launching the UI for dismissing a timer. | -| ACTION_SEND_SMS | ohos.want.action.sendSms | Action of launching the UI for sending an SMS. | +| ACTION_SEND_SMS | ohos.want.action.sendSms | Action of launching the UI for sending an SMS message. | | ACTION_CHOOSE | ohos.want.action.choose | Action of launching the UI for openning a contact or picture. | | ACTION_IMAGE_CAPTURE8+ | ohos.want.action.imageCapture | Action of launching the UI for photographing. | | ACTION_VIDEO_CAPTURE8+ | ohos.want.action.videoCapture | Action of launching the UI for shooting a video. | diff --git a/en/application-dev/reference/apis/js-apis-abilityAccessCtrl.md b/en/application-dev/reference/apis/js-apis-abilityAccessCtrl.md index 2b17d252af9d09d5519f36ece4306834e8085c5a..003a5efd92057dc7127b74aa35553f3220bd890e 100644 --- a/en/application-dev/reference/apis/js-apis-abilityAccessCtrl.md +++ b/en/application-dev/reference/apis/js-apis-abilityAccessCtrl.md @@ -49,7 +49,7 @@ Checks whether an application has been granted the specified permission. This AP | Name | Type | Mandatory| Description | | -------- | ------------------- | ---- | ------------------------------------------ | -| tokenID | number | Yes | ID of the application. | +| tokenID | number | Yes | ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). | | permissionName | string | Yes | Name of the permission to verify.| **Return value** @@ -105,7 +105,7 @@ grantUserGrantedPermission(tokenID: number, permissionName: string, permissionFl Grants a user granted permission to an application. This API uses a promise to return the result. -This is a system API and cannot be called by third-party applications. +This is a system API. **Required permissions**: ohos.permission.GRANT_SENSITIVE_PERMISSIONS @@ -143,7 +143,7 @@ grantUserGrantedPermission(tokenID: number, permissionName: string, permissionFl Grants a user granted permission to an application. This API uses an asynchronous callback to return the result. -This is a system API and cannot be called by third-party applications. +This is a system API. **Required permissions**: ohos.permission.GRANT_SENSITIVE_PERMISSIONS @@ -179,7 +179,7 @@ revokeUserGrantedPermission(tokenID: number, permissionName: string, permissionF Revokes a user granted permission given to an application. This API uses a promise to return the result. -This is a system API and cannot be called by third-party applications. +This is a system API. **Required permissions**: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS @@ -217,7 +217,7 @@ revokeUserGrantedPermission(tokenID: number, permissionName: string, permissionF Revokes a user granted permission given to an application. This API uses an asynchronous callback to return the result. -This is a system API and cannot be called by third-party applications. +This is a system API. **Required permissions**: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS @@ -253,7 +253,7 @@ getPermissionFlags(tokenID: number, permissionName: string): Promise<number&g Obtains the flags of the specified permission of a given application. This API uses a promise to return the result. -This is a system API and cannot be called by third-party applications. +This is a system API. **Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS, ohos.permission.GRANT_SENSITIVE_PERMISSIONS, or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS diff --git a/en/application-dev/reference/apis/js-apis-application-Want.md b/en/application-dev/reference/apis/js-apis-application-Want.md index f51fee8402c98f9c36e81f355df105a3154e0105..43786f3925b5277d3b806cf638ab7238fe40fd6b 100644 --- a/en/application-dev/reference/apis/js-apis-application-Want.md +++ b/en/application-dev/reference/apis/js-apis-application-Want.md @@ -23,23 +23,94 @@ import Want from '@ohos.application.Want'; | abilityName | Read only | string | No | Name of the ability. If both **package** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability. The value of **abilityName** must be unique in an application.| | uri | Read only | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.| | type | Read only | string | No | MIME type, for example, **text/plain** or **image/***. | -| flags | Read only | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](js-apis-featureAbility.md#flags).| +| flags | Read only | number | No | How the **Want** object will be handled. For details, see [flags](js-apis-featureAbility.md#flags).| | action | Read only | string | No | Action option. | -| parameters | Read only | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:
**ohos.aafwk.callerPid**: PID of the caller.
**ohos.aafwk.param.callerToken**: token of the caller.
**ohos.aafwk.param.callerUid**: UID of the caller. The **userId** parameter in the [Bundle](js-apis-Bundle.js) module can be used to obtain application and bundle information. | +| parameters | Read only | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:
**ohos.aafwk.callerPid**: PID of the caller.
**ohos.aafwk.param.callerToken**: token of the caller.
**ohos.aafwk.param.callerUid**: UID of the caller. The **userId** parameter in the [Bundle](js-apis-Bundle.md) module can be used to obtain application and bundle information. | | entities | Read only | Array\ | No | List of entities. | | moduleName9+ | Read only | string | No | Module to which the ability belongs.| **Example** -``` js - var want = { - "deviceId": "", // An empty deviceId indicates the local device. - "bundleName": "com.extreme.test", - "abilityName": "MainAbility", - "moduleName": "entry" // moduleName is optional. - }; - this.context.startAbility(want, (error) => { - // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters uniquely identify an ability. - console.log("error.code = " + error.code) - }) -``` +- Basic usage + + ``` js + var want = { + "deviceId": "", // An empty deviceId indicates the local device. + "bundleName": "com.extreme.test", + "abilityName": "MainAbility", + "moduleName": "entry" // moduleName is optional. + }; + this.context.startAbility(want, (error) => { + // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability. + console.log("error.code = " + error.code) + }) + ``` + +- Passing a file descriptor (FD) + + ``` js + var fd; + try { + fd = fileio.openSync("/data/storage/el2/base/haps/pic.png"); + } catch(e) { + console.log("openSync fail:" + JSON.stringify(e)); + } + var want = { + "deviceId": "", // An empty deviceId indicates the local device. + "bundleName": "com.extreme.test", + "abilityName": "MainAbility", + "moduleName": "entry" // moduleName is optional. + "parameters": { + "keyFd":{"type":"FD", "value":fd} + } + }; + this.context.startAbility(want, (error) => { + // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability. + console.log("error.code = " + error.code) + }) + ``` + +- Passing **RemoteObject** data + + ``` js + class Stub extends rpc.RemoteObject { + constructor(des) { + if (typeof des == 'string') { + super(des); + } else { + return null; + } + } + + onRemoteRequest(code, data, reply, option) { + if (code === 1) { + console.log('onRemoteRequest called') + let token = data.readInterfaceToken(); + let num = data.readInt(); + this.method(); + return true; + } + return false; + } + + method() { + console.log('method called'); + } + } + + var remoteObject = new Stub('want-test'); + var want = { + "deviceId": "", // An empty deviceId indicates the local device. + "bundleName": "com.extreme.test", + "abilityName": "MainAbility", + "moduleName": "entry" // moduleName is optional. + "parameters": { + "keyRemoteObject":{"type":"RemoteObject", "value":remoteObject} + } + }; + this.context.startAbility(want, (error) => { + // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability. + console.log("error.code = " + error.code) + }) + ``` + \ No newline at end of file diff --git a/en/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md b/en/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md index 42974b5fd683af842146b53fec22022edca84de6..54264312fcc88ad0177473a7e4d256f566e6c2d2 100644 --- a/en/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md +++ b/en/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md @@ -1,6 +1,6 @@ # AbilityLifecycleCallback -The **AbilityLifecycleCallback** module provides callbacks, such as **onAbilityCreate**, **onAbilityWindowStageCreate**, and **onAbilityWindowStageDestroy**, to receive lifecycle state changes in the application context. +The **AbilityLifecycleCallback** module provides callbacks, such as **onAbilityCreate**, **onWindowStageCreate**, and **onWindowStageDestroy**, to receive lifecycle state changes in the application context. > **NOTE** > @@ -30,9 +30,9 @@ Called when an ability is created. | ability | [Ability](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| -## AbilityLifecycleCallback.onAbilityWindowStageCreate +## AbilityLifecycleCallback.onWindowStageCreate -onAbilityWindowStageCreate(ability: Ability): void; +onWindowStageCreate(ability: Ability, windowStage: window.WindowStage): void; Called when the window stage of an ability is created. @@ -43,11 +43,44 @@ Called when the window stage of an ability is created. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | ability | [Ability](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + | windowStage | [WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| -## AbilityLifecycleCallback.onAbilityWindowStageDestroy +## AbilityLifecycleCallback.onWindowStageActive -onAbilityWindowStageDestroy(ability: Ability): void; +onWindowStageActive(ability: Ability, windowStage: window.WindowStage): void; + +Called when the window stage of an ability gains focus. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [Ability](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + | windowStage | [WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + + +## AbilityLifecycleCallback.onWindowStageInactive + +onWindowStageInactive(ability: Ability, windowStage: window.WindowStage): void; + +Called when the window stage of an ability loses focus. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [Ability](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + | windowStage | [WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + + +## AbilityLifecycleCallback.onWindowStageDestroy + +onWindowStageDestroy(ability: Ability, windowStage: window.WindowStage): void; Called when the window stage of an ability is destroyed. @@ -58,6 +91,7 @@ Called when the window stage of an ability is destroyed. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | ability | [Ability](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + | windowStage | [WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| ## AbilityLifecycleCallback.onAbilityDestroy @@ -132,12 +166,22 @@ Called when an ability is continued on another device. onAbilityCreate(ability){ console.log("AbilityLifecycleCallback onAbilityCreate ability:" + JSON.stringify(ability)); }, - onAbilityWindowStageCreate(ability){ - console.log("AbilityLifecycleCallback onAbilityWindowStageCreate ability:" + JSON.stringify(ability)); - }, - onAbilityWindowStageDestroy(ability){ - console.log("AbilityLifecycleCallback onAbilityWindowStageDestroy ability:" + JSON.stringify(ability)); - }, + onWindowStageCreate(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageCreate ability:" + JSON.stringify(ability)); + console.log("AbilityLifecycleCallback onWindowStageCreate windowStage:" + JSON.stringify(windowStage)); + }, + onWindowStageActive(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageActive ability:" + JSON.stringify(ability)); + console.log("AbilityLifecycleCallback onWindowStageActive windowStage:" + JSON.stringify(windowStage)); + }, + onWindowStageInactive(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageInactive ability:" + JSON.stringify(ability)); + console.log("AbilityLifecycleCallback onWindowStageInactive windowStage:" + JSON.stringify(windowStage)); + }, + onWindowStageDestroy(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageDestroy ability:" + JSON.stringify(ability)); + console.log("AbilityLifecycleCallback onWindowStageDestroy windowStage:" + JSON.stringify(windowStage)); + }, onAbilityDestroy(ability){ console.log("AbilityLifecycleCallback onAbilityDestroy ability:" + JSON.stringify(ability)); }, diff --git a/en/application-dev/reference/apis/js-apis-application-context.md b/en/application-dev/reference/apis/js-apis-application-context.md index cf5291224477451554ea36e823ecedc0629cbfe0..16d5fd0c3d79d097bc8f78ef24cae8f91869b8e3 100644 --- a/en/application-dev/reference/apis/js-apis-application-context.md +++ b/en/application-dev/reference/apis/js-apis-application-context.md @@ -19,7 +19,7 @@ import AbilityContext from '@ohos.application.Ability' let context = this.context.createBundleContext(test); } } - ``` +``` ## Attributes @@ -53,15 +53,15 @@ Creates a context for a given application. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| bundleName | string | Yes| Application bundle name.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | bundleName | string | Yes| Application bundle name.| **Return value** -| Type| Description| -| -------- | -------- | -| Context | Context created.| + | Type| Description| + | -------- | -------- | + | Context | Context created.| **Example** @@ -87,15 +87,15 @@ Creates a context for a given HAP. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| moduleName | string | Yes| HAP name in the application.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | moduleName | string | Yes| HAP name in the application.| **Return value** -| Type| Description| -| -------- | -------- | -| Context | Context created.| + | Type| Description| + | -------- | -------- | + | Context | Context created.| **Example** @@ -123,16 +123,16 @@ Creates a context for a given HAP in an application. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| bundleName | string | Yes| Application bundle name.| -| moduleName | string | Yes| HAP name in the application.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | bundleName | string | Yes| Application bundle name.| + | moduleName | string | Yes| HAP name in the application.| **Return value** -| Type| Description| -| -------- | -------- | -| Context | Context created.| + | Type| Description| + | -------- | -------- | + | Context | Context created.| **Example** diff --git a/en/application-dev/reference/apis/js-apis-appmanager.md b/en/application-dev/reference/apis/js-apis-appmanager.md index 05ff78e77e6d6d54527148782b18d0dbca007cd6..1b2bd22548deeed3145803c1a3939e59399b904c 100644 --- a/en/application-dev/reference/apis/js-apis-appmanager.md +++ b/en/application-dev/reference/apis/js-apis-appmanager.md @@ -22,9 +22,9 @@ Checks whether this application is undergoing a stability test. This API uses an **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<boolean> | No| Callback used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | No| Callback used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| **Example** @@ -46,9 +46,9 @@ Checks whether this application is undergoing a stability test. This API uses a **Return value** - | Type| Description| - | -------- | -------- | - | Promise<boolean> | Promise used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| **Example** @@ -72,9 +72,9 @@ Checks whether this application is running on a RAM constrained device. This API **Return value** - | Type| Description| - | -------- | -------- | - | Promise<boolean> | Promise used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| **Example** @@ -96,9 +96,9 @@ Checks whether this application is running on a RAM constrained device. This API **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<boolean> | No| Callback used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | No| Callback used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| **Example** @@ -119,9 +119,9 @@ Obtains the memory size of this application. This API uses a promise to return t **Return value** - | Type| Description| - | -------- | -------- | - | Promise<number> | Size of the application memory.| +| Type| Description| +| -------- | -------- | +| Promise<number> | Size of the application memory.| **Example** @@ -143,9 +143,9 @@ Obtains the memory size of this application. This API uses an asynchronous callb **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<number> | No| Size of the application memory.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<number> | No| Size of the application memory.| **Example** @@ -155,7 +155,11 @@ Obtains the memory size of this application. This API uses an asynchronous callb console.log('startAbility result success:' + JSON.stringify(data)); }) ``` -## appManager.getProcessRunningInfos8+ +## appManager.getProcessRunningInfos(deprecated) + +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [appManager.getProcessRunningInformation9+](#appmanagergetprocessrunninginformation9) instead. getProcessRunningInfos(): Promise\>; @@ -181,7 +185,11 @@ Obtains information about the running processes. This API uses a promise to retu }); ``` -## appManager.getProcessRunningInfos8+ +## appManager.getProcessRunningInfos(deprecated) + +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [appManager.getProcessRunningInformation9+](#appmanagergetprocessrunninginformation9-1) instead. getProcessRunningInfos(callback: AsyncCallback\>): void; @@ -206,11 +214,62 @@ Obtains information about the running processes. This API uses an asynchronous c }) ``` +## appManager.getProcessRunningInformation9+ + +getProcessRunningInformation(): Promise\>; + +Obtains information about the running processes. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\> | Promise used to return the process information.| + +**Example** + + ```js + app.getProcessRunningInformation().then((data) => { + console.log('success:' + JSON.stringify(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + +## appManager.getProcessRunningInformation9+ + +getProcessRunningInformation(callback: AsyncCallback\>): void; + +Obtains information about the running processes. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback\> | No| Callback used to return the process information.| + +**Example** + + ```js + app.getProcessRunningInformation((err, data) => { + console.log('startAbility result failed :' + JSON.stringify(err)); + console.log('startAbility result success:' + JSON.stringify(data)); + }) + ``` + ## appManager.registerApplicationStateObserver8+ registerApplicationStateObserver(observer: ApplicationStateObserver): number; -Registers the application state observer. +Registers an observer to listen for the state of all applications. **Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER @@ -222,7 +281,7 @@ Registers the application state observer. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| observer | ApplicationStateObserver | No| Numeric code of the observer.| +| observer | [ApplicationStateObserver](#applicationstateobserver) | No| Numeric code of the observer.| **Example** @@ -244,6 +303,48 @@ Registers the application state observer. const observerCode = app.registerApplicationStateObserver(applicationStateObserver); console.log('-------- observerCode: ---------', observerCode); + ``` + +## appManager.registerApplicationStateObserver9+ + +registerApplicationStateObserver(observer: ApplicationStateObserver, bundleNameList: Array): number; + +Registers an observer to listen for the state of a specified application. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| observer | [ApplicationStateObserver](#applicationstateobserver) | No| Numeric code of the observer.| +| bundleNameList | Array | No| **bundleName** array to be registered for listening. The maximum value is 128.| + +**Example** + + ```js + var applicationStateObserver = { + onForegroundApplicationChanged(appStateData) { + console.log('------------ onForegroundApplicationChanged -----------', appStateData); + }, + onAbilityStateChanged(abilityStateData) { + console.log('------------ onAbilityStateChanged -----------', abilityStateData); + }, + onProcessCreated(processData) { + console.log('------------ onProcessCreated -----------', processData); + }, + onProcessDied(processData) { + console.log('------------ onProcessDied -----------', processData); + } + } + var bundleNameList = ['bundleName1', 'bundleName2']; + const observerCode = app.registerApplicationStateObserver(applicationStateObserver, bundleNameList); + console.log('-------- observerCode: ---------', observerCode); + ``` ## appManager.unregisterApplicationStateObserver8+ @@ -258,7 +359,7 @@ Deregisters the application state observer. This API uses an asynchronous callba **System API**: This is a system API and cannot be called by third-party applications. **Parameters** - + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | observerId | number | No| Numeric code of the observer.| @@ -319,7 +420,7 @@ Deregisters the application state observer. This API uses a promise to return th getForegroundApplications(callback: AsyncCallback\>): void; -Obtains applications that run in the foreground. This API uses an asynchronous callback to return the result. +Obtains applications that are running in the foreground. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.GET_RUNNING_INFO @@ -350,7 +451,7 @@ Obtains applications that run in the foreground. This API uses an asynchronous c getForegroundApplications(): Promise\>; -Obtains applications that run in the foreground. This API uses a promise to return the result. +Obtains applications that are running in the foreground. This API uses a promise to return the result. **Required permissions**: ohos.permission.GET_RUNNING_INFO @@ -380,7 +481,7 @@ Obtains applications that run in the foreground. This API uses a promise to retu killProcessWithAccount(bundleName: string, accountId: number): Promise\ -Kills the process by bundle name and account ID. This API uses a promise to return the result. +Kills a process by bundle name and account ID. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES @@ -390,10 +491,10 @@ Kills the process by bundle name and account ID. This API uses a promise to retu **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | bundleName | string | Yes| Bundle name of an application.| - | accountId | number | Yes| Account ID.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| **Example** @@ -414,7 +515,7 @@ app.killProcessWithAccount(bundleName, accountId) killProcessWithAccount(bundleName: string, accountId: number, callback: AsyncCallback\): void -Kills the process by bundle name and account ID. This API uses an asynchronous callback to return the result. +Kills a process by bundle name and account ID. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -424,11 +525,11 @@ Kills the process by bundle name and account ID. This API uses an asynchronous c **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | bundleName | string | Yes| Bundle name of an application.| - | accountId | number | Yes| Account ID.| - | callback | AsyncCallback\ | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** @@ -708,7 +809,7 @@ console.log('-------- processDiedInfo: ---------', processDiedInfo); | bundleName8+ | string | Yes | No | Bundle name of an application. | | abilityName8+ | string | Yes | No | Ability name. | | uid8+ | number | Yes | No | User ID. | -| state8+ | number | Yes | No | Application information. | +| state8+ | number | Yes | No | Ability state. | | moduleName9+ | string | Yes | No | Name of the HAP file to which the ability belongs. | | abilityType8+ | string | Yes | No | Ability type. | @@ -736,3 +837,16 @@ console.log('-------- processDiedInfo: ---------', processDiedInfo); | uid9+ | Read only | number | No | User ID.| | processName9+ | Read only | string | No | Process name.| | bundleNames9+ | Read only | Array\ | No | **bundleName** array in the running processes.| + +## ApplicationStateObserver + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name | Type | Readable| Writable| Description | +| ----------------------- | ---------| ---- | ---- | ------------------------- | +| [onForegroundApplicationChanged8+](#applicationstateobserveronforegroundapplicationchanged8) | AsyncCallback\ | Yes | No | Callback invoked when the foreground or background state of an application changes. | +| [onAbilityStateChanged8+](#applicationstateobserveronabilitystatechanged8) | AsyncCallback\ | Yes | No | Callback invoked when the ability state changes. | +| [onProcessCreated8+](#applicationstateobserveronprocesscreated8) | AsyncCallback\ | Yes | No | Callback invoked when a process is created. | +| [onProcessDied8+](#applicationstateobserveronprocessdied8) | AsyncCallback\ | Yes | No | Callback invoked when a process is destroyed. | diff --git a/en/application-dev/reference/apis/js-apis-backgroundTaskManager.md b/en/application-dev/reference/apis/js-apis-backgroundTaskManager.md index cbb0ff47c767fd26e499913f44ba88d7e6187f17..67b4a955e1cfe2d9bd557cc47fdc938b010a8de6 100644 --- a/en/application-dev/reference/apis/js-apis-backgroundTaskManager.md +++ b/en/application-dev/reference/apis/js-apis-backgroundTaskManager.md @@ -1,6 +1,6 @@ -# BackgroundTaskManager +# Background Task Management -This module provides background task management. +The **BackgroundTaskManager** module provides APIs to manage background tasks. If a service needs to be continued when the application or service module is running in the background (not visible to users), the application or service module can request a transient task or continuous task for delayed suspension based on the service type. @@ -15,7 +15,7 @@ If an application has a service that can be intuitively perceived by users and n ## Modules to Import -``` +```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; ``` @@ -144,12 +144,12 @@ Requests a continuous task from the system. This API uses an asynchronous callba **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **Parameters** -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------- | ---- | ------------------------ | -| context | [Context](js-apis-Context.md) | Yes | Application context. | -| bgMode | [BackgroundMode](#backgroundmode8) | Yes | Background mode requested. | -| wantAgent | [WantAgent](js-apis-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked.| -| callback | AsyncCallback<void> | Yes | Callback used to return the result. | +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------- | ---- | ---------------------------------------- | +| context | Context | Yes | Application context.
For the application context of the FA model, see [Context](js-apis-Context.md).
For the application context of the stage model, see [Context](js-apis-ability-context.md).| +| bgMode | [BackgroundMode](#backgroundmode8) | Yes | Background mode requested. | +| wantAgent | [WantAgent](js-apis-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** ```js @@ -196,11 +196,11 @@ Requests a continuous task from the system. This API uses a promise to return th **Parameters** -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------- | ---- | ----------------------- | -| context | [Context](js-apis-Context.md) | Yes | Application context. | -| bgMode | [BackgroundMode](#backgroundmode8) | Yes | Background mode requested. | -| wantAgent | [WantAgent](js-apis-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked.| +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------- | ---- | ---------------------------------------- | +| context | Context | Yes | Application context.
For the application context of the FA model, see [Context](js-apis-Context.md).
For the application context of the stage model, see [Context](js-apis-ability-context.md).| +| bgMode | [BackgroundMode](#backgroundmode8) | Yes | Background mode requested. | +| wantAgent | [WantAgent](js-apis-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. | **Return value** | Type | Description | @@ -245,10 +245,10 @@ Requests to cancel a continuous task. This API uses an asynchronous callback to **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ----------------------------- | ---- | ---------------------- | -| context | [Context](js-apis-Context.md) | Yes | Application context. | -| callback | AsyncCallback<void> | Yes | Callback used to return the result.| +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | ---- | ---------------------------------------- | +| context | Context | Yes | Application context.
For the application context of the FA model, see [Context](js-apis-Context.md).
For the application context of the stage model, see [Context](js-apis-ability-context.md).| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** ```js @@ -276,9 +276,9 @@ Requests to cancel a continuous task. This API uses a promise to return the resu **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **Parameters** -| Name | Type | Mandatory | Description | -| ------- | ----------------------------- | ---- | --------- | -| context | [Context](js-apis-Context.md) | Yes | Application context.| +| Name | Type | Mandatory | Description | +| ------- | ------- | ---- | ---------------------------------------- | +| context | Context | Yes | Application context.
For the application context of the FA model, see [Context](js-apis-Context.md).
For the application context of the stage model, see [Context](js-apis-ability-context.md).| **Return value** | Type | Description | @@ -314,14 +314,14 @@ Provides the information about the suspension delay. **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask -| Name | Value| Description | -| ----------------------- | ------ | ------------------------------------------------------------ | -| DATA_TRANSFER | 1 | Data transfer. | -| AUDIO_PLAYBACK | 2 | Audio playback. | -| AUDIO_RECORDING | 3 | Audio recording. | -| LOCATION | 4 | Positioning and navigation. | -| BLUETOOTH_INTERACTION | 5 | Bluetooth-related task. | -| MULTI_DEVICE_CONNECTION | 6 | Multi-device connection. | -| WIFI_INTERACTION | 7 | WLAN-related.
This is a system API and cannot be called by third-party applications.| -| VOIP | 8 | Audio and video calls.
This is a system API and cannot be called by third-party applications.| -| TASK_KEEPING | 9 | Computing task (effective only for specific devices). | +| Name | Value | Description | +| ----------------------- | ---- | --------------------- | +| DATA_TRANSFER | 1 | Data transfer. | +| AUDIO_PLAYBACK | 2 | Audio playback. | +| AUDIO_RECORDING | 3 | Audio recording. | +| LOCATION | 4 | Positioning and navigation. | +| BLUETOOTH_INTERACTION | 5 | Bluetooth-related task. | +| MULTI_DEVICE_CONNECTION | 6 | Multi-device connection. | +| WIFI_INTERACTION | 7 | WLAN-related.
This is a system API.| +| VOIP | 8 | Audio and video calls.
This is a system API. | +| TASK_KEEPING | 9 | Computing task (effective only for specific devices). | diff --git a/en/application-dev/reference/apis/js-apis-bundle-AbilityInfo.md b/en/application-dev/reference/apis/js-apis-bundle-AbilityInfo.md index 74ba45c52450241572aff5ab9cba2a55debd9124..3cb5f2792733b4ad88914023b7debb7354fa74b4 100644 --- a/en/application-dev/reference/apis/js-apis-bundle-AbilityInfo.md +++ b/en/application-dev/reference/apis/js-apis-bundle-AbilityInfo.md @@ -1,16 +1,11 @@ # AbilityInfo - +Unless otherwise specified, ability information is obtained through **GET_BUNDLE_DEFAULT**. > **NOTE** -> > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. - - -Provides the ability information. - - +## AbilityInfo **System capability**: SystemCapability.BundleManager.BundleFramework @@ -25,24 +20,24 @@ Provides the ability information. | iconId | number | Yes | No | Ability icon ID. | | moduleName | string | Yes | No | Name of the HAP file to which the ability belongs. | | process | string | Yes | No | Process in which the ability runs. If this parameter is not set, the bundle name is used.| -| targetAbility | string | Yes | No | Target ability that the ability alias points to. | -| backgroundModes | number | Yes | No | Background service mode of the ability. | +| targetAbility | string | Yes | No | Target ability that the ability alias points to.
This attribute can be used only in the FA model.| +| backgroundModes | number | Yes | No | Background service mode of the ability.
This attribute can be used only in the FA model. | | isVisible | boolean | Yes | No | Whether the ability can be called by other applications. | -| formEnabled | boolean | Yes | No | Whether the ability provides the service widget capability. | -| type | AbilityType | Yes | No | Ability type. | +| formEnabled | boolean | Yes | No | Whether the ability provides the service widget capability.
This attribute can be used only in the FA model.| +| type | AbilityType | Yes | No | Ability type.
This attribute can be used only in the FA model. | | orientation | DisplayOrientation | Yes | No | Ability display orientation. | | launchMode | LaunchMode | Yes | No | Ability launch mode. | -| permissions | Array\ | Yes | No | Permissions required for other applications to call the ability.| +| permissions | Array\ | Yes | No | Permissions required for other applications to call the ability.
The value is obtained by passing **GET_ABILITY_INFO_WITH_PERMISSION**.| | deviceTypes | Array\ | Yes | No | Device types supported by the ability. | | deviceCapabilities | Array\ | Yes | No | Device capabilities required for the ability. | -| readPermission | string | Yes | No | Permission required for reading the ability data. | -| writePermission | string | Yes | No | Permission required for writing data to the ability. | -| applicationInfo | [ApplicationInfo](js-apis-bundle-ApplicationInfo.md) | Yes | No | Application configuration information. | -| uri | string | Yes | No | URI of the ability. | +| readPermission | string | Yes | No | Permission required for reading the ability data.
This attribute can be used only in the FA model.| +| writePermission | string | Yes | No | Permission required for writing data to the ability.
This attribute can be used only in the FA model.| +| applicationInfo | [ApplicationInfo](js-apis-bundle-ApplicationInfo.md) | Yes | No | Application configuration information.
The value is obtained by passing **GET_ABILITY_INFO_WITH_APPLICATION**.| +| uri | string | Yes | No | URI of the ability.
This attribute can be used only in the FA model.| | labelId | number | Yes | No | Ability label ID. | -| subType | AbilitySubType | Yes | No | Subtype of the template that can be used by the ability. | -| metaData8+ | Array\<[CustomizeData](js-apis-bundle-CustomizeData.md)> | Yes | No | Custom metadata of the ability. | -| metadata9+ | Array\<[Metadata](js-apis-bundle-Metadata.md)> | Yes | No | Metadata of the ability. | +| subType | AbilitySubType | Yes | No | Subtype of the template that can be used by the ability.
This attribute can be used only in the FA model.| +| metaData8+ | Array\<[CustomizeData](js-apis-bundle-CustomizeData.md)> | Yes | No | Custom metadata of the ability.
The value is obtained by passing **GET_ABILITY_INFO_WITH_METADATA**.| +| metadata9+ | Array\<[Metadata](js-apis-bundle-Metadata.md)> | Yes | No | Metadata of the ability.
The value is obtained by passing **GET_ABILITY_INFO_WITH_METADATA**.| | enabled8+ | boolean | Yes | No | Whether the ability is enabled. | | supportWindowMode9+ | Array\<[SupportWindowMode](js-apis-Bundle.md)> | Yes | No | Window modes supported by the ability. | | maxWindowRatio9+ | number | Yes | No | Maximum window ratio supported by the ability. | diff --git a/en/application-dev/reference/apis/js-apis-bundle-BundleInstaller.md b/en/application-dev/reference/apis/js-apis-bundle-BundleInstaller.md new file mode 100644 index 0000000000000000000000000000000000000000..7c86528db55ea364316caaa927b29a90f88b253c --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-bundle-BundleInstaller.md @@ -0,0 +1,100 @@ +# BundleInstaller + +The **BundleInstaller** module provides APIs for installing, updating, and deleting bundles on devices. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## System Capability + +SystemCapability.BundleManager.BundleFramework + +## BundleInstaller.install + +install(bundleFilePaths: Array<string>, param: InstallParam, callback: AsyncCallback<InstallStatus>): void; + +Installs bundles. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.INSTALL_BUNDLE + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | +| bundleFilePaths | Array<string> | Yes | Paths where the bundles are stored. Each path should point to a relative directory of the current application's data directory.| +| param | [InstallParam](#installparam) | Yes | Parameters required for the installation or uninstall. | +| callback | AsyncCallback<[InstallStatus](#installstatus)> | Yes | Callback used to return the installation status. | + +## BundleInstaller.uninstall + +uninstall(bundleName: string, param: InstallParam, callback: AsyncCallback<InstallStatus>): void; + +Uninstalls a bundle. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.INSTALL_BUNDLE + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ---------------------------------------------------- | ---- | ---------------------------------------------- | +| bundleName | string | Yes | Bundle name. | +| param | [InstallParam](#installparam) | Yes | Parameters required for the installation or uninstall. | +| callback | AsyncCallback<[InstallStatus](#installstatus)> | Yes | Callback used to return the installation status.| + +## BundleInstaller.recover + +recover(bundleName: string, param: InstallParam, callback: AsyncCallback<InstallStatus>): void; + +Recovers a bundle. This API uses an asynchronous callback to return the result. + +**Required permissions** + +ohos.permission.INSTALL_BUNDLE + +**System capability** + +SystemCapability.BundleManager.BundleFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ---------------------------------------------------- | ---- | ---------------------------------------------- | +| bundleName | string | Yes | Bundle name. | +| param | [InstallParam](#installparam) | Yes | Parameters required for the installation or uninstall. | +| callback | AsyncCallback<[InstallStatus](#installstatus)> | Yes | Callback used to return the installation status.| + +## InstallParam + +Describes the parameters required for bundle installation or uninstall. + + **System capability**: SystemCapability.BundleManager.BundleFramework + +| Name | Type | Description | +| ----------- | ------- | ------------------ | +| userId | number | User ID. | +| installFlag | number | Installation flag. | +| isKeepData | boolean | Whether data is kept.| + +## InstallStatus + +Describes the bundle installation status. + + **System capability**: SystemCapability.BundleManager.BundleFramework + +| Name | Type | Readable| Writable| Description | +| ------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------ | +| status | bundle.[InstallErrorCode](js-apis-Bundle.md#installerrorcode) | Yes | No | Installation or uninstall error code. | +| statusMessage | string | Yes | No | Installation or uninstall status message.| diff --git a/en/application-dev/reference/apis/js-apis-bundle-ElementName.md b/en/application-dev/reference/apis/js-apis-bundle-ElementName.md index ede83cd6de76637220005f0821471c0141c9721f..205c9f15192c4c2c9abfcb08b1f1ae156d7baf75 100644 --- a/en/application-dev/reference/apis/js-apis-bundle-ElementName.md +++ b/en/application-dev/reference/apis/js-apis-bundle-ElementName.md @@ -1,14 +1,14 @@ # ElementName +The **ElementName** module provides the element name information. + > **NOTE** > > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. -Provides the element name information. - ## ElementName - **System capability**: SystemCapability.BundleManager.BundleFramework +**System capability**: SystemCapability.BundleManager.BundleFramework | Name | Type | Readable| Writable| Description | | ----------------------- | ---------| ---- | ---- | ------------------------- | diff --git a/en/application-dev/reference/apis/js-apis-bundle-LauncherAbilityInfo.md b/en/application-dev/reference/apis/js-apis-bundle-LauncherAbilityInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..7b932cacbc2195e8c52976aa80e71bd3b638921d --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-bundle-LauncherAbilityInfo.md @@ -0,0 +1,20 @@ +# LauncherAbilityInfo + +The **LauncherAbilityInfo** module provides information about a launcher ability. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## LauncherAbilityInfo + +**System capability**: SystemCapability.BundleManager.BundleFramework + +| Name | Type | Readable| Writable| Description | +| --------------- | ---------------------------------------------------- | ---- | ---- | ------------------------------------ | +| applicationInfo | [ApplicationInfo](js-apis-bundle-ApplicationInfo.md) | Yes | No | Application information of the launcher ability.| +| elementName | [ElementName](js-apis-bundle-ElementName.md) | Yes | No | Element name of the launcher ability. | +| labelId | number | Yes | No | Label ID of the launcher ability. | +| iconId | number | Yes | No | Icon ID of the launcher ability. | +| userId | number | Yes | No | User ID of the launcher ability. | +| installTime | number | Yes | No | Time when the launcher ability is installed. | diff --git a/en/application-dev/reference/apis/js-apis-bundle-PermissionDef.md b/en/application-dev/reference/apis/js-apis-bundle-PermissionDef.md new file mode 100644 index 0000000000000000000000000000000000000000..4ebc8d40516c596de2977ea19583e019cce2ac1f --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-bundle-PermissionDef.md @@ -0,0 +1,19 @@ +# PermissionDef + +The **PermissionDef** module provides permission details defined in the configuration file. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## **PermissionDef** + +**System capability**: SystemCapability.BundleManager.BundleFramework + +| Name | Type | Readable| Writable| Description | +| -------------- | ------ | ---- | ---- | -------------- | +| permissionName | string | Yes | No | Name of the permission. | +| grantMode | number | Yes | No | Grant mode of the permission.| +| labelId | number | Yes | No | Label ID of the permission. | +| descriptionId | number | Yes | No | Description ID of the permission. | + diff --git a/en/application-dev/reference/apis/js-apis-bundle-ShortcutInfo.md b/en/application-dev/reference/apis/js-apis-bundle-ShortcutInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..8b2cf350047aa0d4c8e165b71b030f3816f6f75f --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-bundle-ShortcutInfo.md @@ -0,0 +1,41 @@ +# ShortcutInfo + +The **ShortcutInfo** module provides shortcut information defined in the configuration file. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## ShortcutWant + +Describes the information about the target to which the shortcut points. + +**System capability**: SystemCapability.BundleManager.BundleFramework + +| Name | Type | Readable| Writable| Description | +| ------------------------- | ------ | ---- | ---- | -------------------- | +| targetBundle | string | Yes | No | Target bundle of the shortcut.| +| targetModule9+ | string | Yes | No | Target module of the shortcut. | +| targetClass | string | Yes | No | Target class required by the shortcut.| + +## ShortcutInfo + +Describes the shortcut attribute information. + +**System capability**: SystemCapability.BundleManager.BundleFramework + +| Name | Type | Readable| Writable| Description | +| ----------------------- | ------------------------------------------ | ---- | ---- | ---------------------------- | +| id | string | Yes | No | ID of the application to which the shortcut belongs. | +| bundleName | string | Yes | No | Name of the bundle that contains the shortcut. | +| hostAbility | string | Yes | No | Local ability information of the shortcut. | +| icon | string | Yes | No | Icon of the shortcut. | +| iconId8+ | number | Yes | No | Icon ID of the shortcut. | +| label | string | Yes | No | Label of the shortcut. | +| labelId8+ | number | Yes | No | Label ID of the shortcut. | +| disableMessage | string | Yes | No | Message displayed when the shortcut is disabled. | +| wants | Array<[ShortcutWant](#shortcutwant)> | Yes | No | Want information required for the shortcut. | +| isStatic | boolean | Yes | No | Whether the shortcut is static. | +| isHomeShortcut | boolean | Yes | No | Whether the shortcut is a home shortcut.| +| isEnabled | boolean | Yes | No | Whether the shortcut is enabled. | +| moduleName9+ | string | Yes | No | Module name of the shortcut. | diff --git a/en/application-dev/reference/apis/js-apis-bundle-remoteAbilityInfo.md b/en/application-dev/reference/apis/js-apis-bundle-remoteAbilityInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..4210ac52230c5e86855c8afacd7c442999efdea6 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-bundle-remoteAbilityInfo.md @@ -0,0 +1,17 @@ +# RemoteAbilityInfo + +The **RemoteAbilityInfo** module provides information about a remote ability. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## RemoteAbilityInfo + +**System capability**: SystemCapability.BundleManager.BundleFramework + +| Name | Type | Readable| Writable| Description | +| ----------- | -------------------------------------------- | ---- | ---- | ----------------------- | +| elementName | [ElementName](js-apis-bundle-ElementName.md) | Yes | No | Element name of the ability. | +| label | string | Yes | No | Label of the ability. | +| icon | string | Yes | No | Icon of the ability.| diff --git a/en/application-dev/reference/apis/js-apis-bytrace.md b/en/application-dev/reference/apis/js-apis-bytrace.md index 72fcfaca8fb39e4345c2392e761b19b364922499..544a4ba0d27e6c39794e063fc63282ba5455bf5e 100644 --- a/en/application-dev/reference/apis/js-apis-bytrace.md +++ b/en/application-dev/reference/apis/js-apis-bytrace.md @@ -19,6 +19,10 @@ startTrace(name: string, taskId: number, expectedTime?: number): void Marks the start of a timeslice trace task. +> **NOTE** +> +> If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be performed multiple times concurrently, different task IDs must be specified in **startTrace**. If the trace tasks with the same name are not performed at the same time, the same taskId can be used. For details, see the bytrace.finishTrace example. + **System capability**: SystemCapability.Developtools.Bytrace **Parameters** @@ -29,9 +33,6 @@ Marks the start of a timeslice trace task. | taskId | number | Yes| ID of a timeslice trace task.| | expectedTime | number | No| Expected duration of the trace, in ms.| -> **NOTE** -> -> If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be performed multiple times concurrently, different task IDs must be specified in **startTrace**. If the trace tasks with the same name are not performed at the same time, the same taskId can be used. For details, see the bytrace.finishTrace example. **Example** @@ -47,6 +48,10 @@ finishTrace(name: string, taskId: number): void Marks the end of a timeslice trace task. +> **NOTE** +> +> To stop a trace task, the values of name and task ID in **finishTrace** must be the same as those in **startTrace**. + **System capability**: SystemCapability.Developtools.Bytrace **Parameters** @@ -56,9 +61,6 @@ Marks the end of a timeslice trace task. | name | string | Yes| Name of a timeslice trace task.| | taskId | number | Yes| ID of a timeslice trace task.| -> **NOTE** -> -> To stop a trace task, the values of name and task ID in **finishTrace** must be the same as those in **startTrace**. **Example** @@ -95,7 +97,7 @@ traceByValue(name: string, count: number): void Defines the variable that indicates the number of timeslice trace tasks. -**System capability**: SystemCapability.Developtools.Bytrace +**System capability**: SystemCapability.HiviewDFX.HiTrace **Parameters** | Name| Type| Mandatory| Description| diff --git a/en/application-dev/reference/apis/js-apis-call.md b/en/application-dev/reference/apis/js-apis-call.md index bb320e0c8b61e2259aa8c31a6d8efa5866c780fa..381796969cdc260896b9ea4857d0461eebf7d519 100644 --- a/en/application-dev/reference/apis/js-apis-call.md +++ b/en/application-dev/reference/apis/js-apis-call.md @@ -44,7 +44,7 @@ call.dial("138xxxxxxxx", (err, data) => { dial\(phoneNumber: string, options: DialOptions, callback: AsyncCallback\): void -Initiates a call. You can set call options as needed. This API uses an asynchronous callback to return the result. +Initiates a call based on the specified options. This API uses an asynchronous callback to return the result. **Required permission**: ohos.permission.PLACE\_CALL (a system permission) @@ -73,7 +73,7 @@ call.dial("138xxxxxxxx", { dial\(phoneNumber: string, options?: DialOptions\): Promise -Initiates a call. You can set call options as needed. This API uses a promise to return the result. +Initiates a call based on the specified options. This API uses a promise to return the result. **Required permission**: ohos.permission.PLACE\_CALL (a system permission) @@ -304,7 +304,7 @@ call.isEmergencyPhoneNumber("138xxxxxxxx", (err, data) => { isEmergencyPhoneNumber\(phoneNumber: string, options: EmergencyNumberOptions, callback: AsyncCallback\): void -Checks whether the called number is an emergency number based on the phone number. This API uses an asynchronous callback to return the result. +Checks whether the called number is an emergency number based on the specified phone number options. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Telephony.CallManager @@ -313,7 +313,7 @@ Checks whether the called number is an emergency number based on the phone numbe | Name | Type | Mandatory | Description | | ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | | phoneNumber | string | Yes | Phone number. | -| options | [EmergencyNumberOptions](#emergencynumberoptions7) | Yes | Phone number option. | +| options | [EmergencyNumberOptions](#emergencynumberoptions7) | Yes | Phone number options. | | callback | AsyncCallback<boolean> | Yes | Callback used to return the result.
- **true**: The called number is an emergency number.
- **false**: The called number is not an emergency number. | **Example** @@ -329,7 +329,7 @@ call.isEmergencyPhoneNumber("112", {slotId: 1}, (err, value) => { isEmergencyPhoneNumber\(phoneNumber: string, options?: EmergencyNumberOptions\): Promise -Checks whether the called number is an emergency number based on the phone number. This API uses a promise to return the result. +Checks whether the called number is an emergency number based on the specified phone number options. This API uses a promise to return the result. **System capability**: SystemCapability.Telephony.CallManager @@ -338,7 +338,7 @@ Checks whether the called number is an emergency number based on the phone numbe | Name | Type | Mandatory | Description | | ----------- | -------------------------------------------------- | ---- | -------------- | | phoneNumber | string | Yes | Phone number. | -| options | [EmergencyNumberOptions](#emergencynumberoptions7) | Yes | Phone number option. | +| options | [EmergencyNumberOptions](#emergencynumberoptions7) | Yes | Phone number options. | **Return value** @@ -386,7 +386,7 @@ call.formatPhoneNumber("138xxxxxxxx", (err, data) => { formatPhoneNumber\(phoneNumber: string, options: NumberFormatOptions, callback: AsyncCallback\): void -Formats a phone number based on specified formatting options. This API uses an asynchronous callback to return the result. +Formats a phone number based on the specified formatting options. This API uses an asynchronous callback to return the result. A formatted phone number is a standard numeric string, for example, 555 0100. @@ -397,7 +397,7 @@ A formatted phone number is a standard numeric string, for example, 555 0100. | Name | Type | Mandatory | Description | | ----------- | -------------------------------------------- | ---- | ------------------------------------ | | phoneNumber | string | Yes | Phone number. | -| options | [NumberFormatOptions](#numberformatoptions7) | Yes | Number formatting option, for example, country code. | +| options | [NumberFormatOptions](#numberformatoptions7) | Yes | Number formatting options, for example, country code. | | callback | AsyncCallback<string> | Yes | Callback used to return the result. | **Example** @@ -415,7 +415,7 @@ call.formatPhoneNumber("138xxxxxxxx",{ formatPhoneNumber\(phoneNumber: string, options?: NumberFormatOptions\): Promise -Formats a phone number based on specified formatting options. This API uses a promise to return the result. +Formats a phone number based on the specified formatting options. This API uses a promise to return the result. A formatted phone number is a standard numeric string, for example, 555 0100. @@ -426,7 +426,7 @@ A formatted phone number is a standard numeric string, for example, 555 0100. | Name | Type | Mandatory | Description | | ----------- | -------------------------------------------- | ---- | ---------------------- | | phoneNumber | string | Yes | Phone number. | -| options | [NumberFormatOptions](#numberformatoptions7) | Yes | Number formatting option, for example, country code. | +| options | [NumberFormatOptions](#numberformatoptions7) | Yes | Number formatting options, for example, country code. | **Return value** @@ -514,15 +514,2242 @@ promise.then(data => { }); ``` +## call.muteRinger8+ + +muteRinger\(callback: AsyncCallback\): void + +Mutes the ringtone while it is playing. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.muteRinger((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.muteRinger8+ + +muteRinger\(\): Promise + +Mutes the ringtone while it is playing. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CallManager + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.muteRinger(); +promise.then(data => { + console.log(`muteRinger success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`muteRinger fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.answer7+ + +answer\(callback: AsyncCallback\): void + +Answers a call. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.ANSWER_CALL + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.answer((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.answer7+ + +answer\(callId: number, callback: AsyncCallback\): void + +Answers a call based on the specified call ID. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.ANSWER_CALL + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ----------------------------------------------- | +| callId | number | Yes | Call ID. You can obtain the value by subscribing to **callDetailsChange** events.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +call.answer(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.answer7+ + +answer(callId?: number\): Promise + +Answers a call based on the specified call ID. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.ANSWER_CALL + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| callId | number | No | Call ID. You can obtain the value by subscribing to **callDetailsChange** events. This parameter is optional from API version 9.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.answer(1); +promise.then(data => { + console.log(`answer success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`answer fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.hangup7+ + +hangup\(callback: AsyncCallback\): void + +Ends a call. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.hangup((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.hangup7+ + +hangup\(callId: number, callback: AsyncCallback\): void + +Ends a call based on the specified call ID. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ----------------------------------------------- | +| callId | number | Yes | Call ID. You can obtain the value by subscribing to **callDetailsChange** events.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +call.hangup(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.hangup7+ + +hangup\(callId?: number\): Promise + +Ends a call based on the specified call ID. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| callId | number | No | Call ID. You can obtain the value by subscribing to **callDetailsChange** events. This parameter is optional from API version 9.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.hangup(1); +promise.then(data => { + console.log(`hangup success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`hangup fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.reject7+ + +reject\(callback: AsyncCallback\): void + +Rejects a call. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.reject((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.reject7+ + +reject\(options: RejectMessageOptions, callback: AsyncCallback\): void + +Rejects a call based on the specified options. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------------- | ---- | -------------- | +| options | [RejectMessageOptions](#rejectmessageoptions7) | Yes | Options for the call rejection message.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +let rejectMessageOptions={ + messageContent: "Unknown number blocked" +} +call.reject(rejectMessageOptions, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.reject7+ + +reject(callId: number, callback: AsyncCallback): + +Rejects a call based on the specified call ID. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ----------------------------------------------- | +| callId | number | Yes | Call ID. You can obtain the value by subscribing to **callDetailsChange** events.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.reject(1); +promise.then(data => { + console.log(`reject success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`reject fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.reject7+ + +reject\(callId: number, options: RejectMessageOption, callback: AsyncCallback\): void + +Rejects a call based on the specified call ID and options. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------------- | ---- | ----------------------------------------------- | +| callId | number | Yes | Call ID. You can obtain the value by subscribing to **callDetailsChange** events.| +| options | [RejectMessageOptions](#rejectmessageoptions7) | Yes | Options for the call rejection message. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +let rejectMessageOptions={ + messageContent: "Unknown number blocked" +} +call.reject(1, rejectMessageOptions, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.reject7+ + +reject(callId?: number, options?: RejectMessageOptions\): Promise + +Rejects a call based on the specified call ID and options. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------------------------------------- | ---- | ------------------------------------------------------------ | +| callId | number | No | Call ID. You can obtain the value by subscribing to **callDetailsChange** events. This parameter is optional from API version 9.| +| options | [RejectMessageOptions](#rejectmessageoptions7) | No | Options for the call rejection message. | + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let rejectMessageOptions={ + messageContent: "Unknown number blocked" +} +let promise = call.reject(1, rejectMessageOptions); +promise.then(data => { + console.log(`reject success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`reject fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.holdCall7+ + +holdCall\(callId: number, callback: AsyncCallback\): void + +Holds a call based on the specified call ID. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callId | number | Yes | Call ID. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.holdCall(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.holdCall7+ + +holdCall\(callId: number\): Promise + +Holds a call based on the specified call ID. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.holdCall(1); +promise.then(data => { + console.log(`holdCall success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`holdCall fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.unHoldCall7+ + +unHoldCall\(callId: number, callback: AsyncCallback\): void + +Unholds a call based on the specified call ID. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callId | number | Yes | Call ID. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.unHoldCall(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.unHoldCall7+ + +unHoldCall\(callId: number\): Promise + +Unholds a call based on the specified call ID. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.unHoldCall(1); +promise.then(data => { + console.log(`unHoldCall success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`unHoldCall fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.switchCall7+ + +switchCall\(callId: number, callback: AsyncCallback\): void + +Switches a call. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callId | number | Yes | Call ID. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.switchCall(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.switchCall7+ + +switchCall\(callId: number\): Promise + +Switches a call. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.switchCall(1); +promise.then(data => { + console.log(`switchCall success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`switchCall fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.combineConference7+ + +combineConference\(callId: number, callback: AsyncCallback\): void + +Combines two calls into a conference call. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callId | number | Yes | Call ID. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.combineConference(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.combineConference7+ + +combineConference\(callId: number\): Promise + +Combines two calls into a conference call. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.combineConference(1); +promise.then(data => { + console.log(`combineConference success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`combineConference fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.getMainCallId7+ + +getMainCallId\(callId: number, callback: AsyncCallback\): void + +Obtains the main call ID. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------- | ---- | ------------------------ | +| callId | number | Yes | Call ID. | +| callback | AsyncCallback<number> | Yes | Callback used to return the result. | + +**Example** + +```js +call.getMainCallId(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.getMainCallId7+ + +getMainCallId\(callId: number\): Promise + +Obtains the main call ID. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.getMainCallId(1); +promise.then(data => { + console.log(`getMainCallId success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getMainCallId fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.getSubCallIdList7+ + +getSubCallIdList\(callId: number, callback: AsyncCallback\>\): void + +Obtains the list of subcall IDs. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------ | ---- | ---------------------------- | +| callId | number | Yes | Call ID. | +| callback | AsyncCallback\> | Yes | Callback used to return the result. | + +**Example** + +```js +call.getSubCallIdList(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.getSubCallIdList7+ + +getSubCallIdList\(callId: number\): Promise\> + +Obtains the list of subcall IDs. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| + +**Return value** + +| Type | Description | +| ----------------------------- | ----------------------------------- | +| Promise<Array> | Promise used to return the result.| + +**Example** + +```js +let promise = call.getSubCallIdList(1); +promise.then(data => { + console.log(`getSubCallIdList success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getSubCallIdList fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.getCallIdListForConference7+ + +getCallIdListForConference\(callId: number, callback: AsyncCallback>\): void + +Obtains the list of call IDs in a conference. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------- | ---- | -------------------------------- | +| callId | number | Yes | Call ID. | +| callback | AsyncCallback<Array> | Yes | Callback used to return the result. | + +**Example** + +```js +call.getCallIdListForConference(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.getCallIdListForConference7+ + +getCallIdListForConference\(callId: number\): Promise\> + +Obtains the list of call IDs in a conference. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| + +**Return value** + +| Type | Description | +| ----------------------------- | --------------------------------------- | +| Promise<Array> | Promise used to return the result.| + +**Example** + +```js +let promise = call.getCallIdListForConference(1); +promise.then(data => { + console.log(`getCallIdListForConference success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getCallIdListForConference fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.getCallWaitingStatus7+ + +getCallWaitingStatus\(slotId: number, callback: AsyncCallback\): void + +Obtains the call waiting status. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| callback | AsyncCallback<[CallWaitingStatus](#callwaitingstatus7)\> | Yes | Callback used to return the result.

- **0**: Call waiting is disabled.
- **1**: Call waiting is enabled.| + +**Example** + +```js +call.getCallWaitingStatus(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.getCallWaitingStatus7+ + +getCallWaitingStatus\(slotId: number\): Promise + +Obtains the call waiting status. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ------------------------------------------------------- | ------------------------------------------------------------ | +| Promise<[CallWaitingStatus](#callwaitingstatus7)> | Promise used to return the result.
- **0**: Call waiting is disabled.
- **1**: Call waiting is enabled.| + +**Example** + +```js +let promise = call.getCallWaitingStatus(0); +promise.then(data => { + console.log(`getCallWaitingStatus success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getCallWaitingStatus fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.setCallWaiting7+ + +setCallWaiting\(slotId: number, activate: boolean, callback: AsyncCallback\): void + +Sets the call waiting switch. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------------------------------------------ | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| activate | boolean | Yes | Whether to enable call waiting.
- **false**: Disable call waiting.
- **true**: Enable call waiting.| +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +call.setCallWaiting(0, true, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.setCallWaiting7+ + +setCallWaiting\(slotId: number, activate: boolean\): Promise + +Sets the call waiting switch. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------- | ---- | ------------------------------------------------------------ | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| activate | boolean | Yes | Whether to enable call waiting.
- **false**: Disable call waiting.
- **true**: Enable call waiting.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.setCallWaiting(0, true); +promise.then(data => { + console.log(`setCallWaiting success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`setCallWaiting fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.startDTMF7+ + +startDTMF\(callId: number, character: string, callback: AsyncCallback\): void + +Enables dual-tone multifrequency (DTMF). This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | -------------------- | ---- | ---------- | +| callId | number | Yes | Call ID. | +| character | string | Yes | DTMF code. | +| callback | AsyncCallback | Yes | Callback used to return the result.| + +**Example** + +```js +call.startDTMF(1, "0", (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.startDTMF7+ + +startDTMF\(callId: number, character: string\): Promise + +Enables DTMF. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| +| character | string | Yes | DTMF code.| + +**Return value** + +| Type | Description | +| ------------------- | ----------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.startDTMF(1, "0"); +promise.then(data => { + console.log(`startDTMF success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`startDTMF fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.stopDTMF7+ + +stopDTMF\(callId: number, callback: AsyncCallback\): void + +Stops DTMF. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callId | number | Yes | Call ID. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.stopDTMF(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.stopDTMF7+ + +stopDTMF\(callId: number\): Promise + +Stops DTMF. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.stopDTMF(1); +promise.then(data => { + console.log(`stopDTMF success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`stopDTMF fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.isInEmergencyCall7+ + +isInEmergencyCall\(callback: AsyncCallback\): void + +Checks whether a call is an emergency call. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ---------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.| + +**Example** + +```js +call.isInEmergencyCall((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.isInEmergencyCall7+ + +isInEmergencyCall\(\): Promise + +Checks whether a call is an emergency call. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CallManager + +**Return value** + +| Type | Description | +| ---------------------- | --------------------------- | +| Promise<boolean> | Promise used to return the result.| + +**Example** + +```js +let promise = call.isInEmergencyCall(); +promise.then(data => { + console.log(`isInEmergencyCall success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`isInEmergencyCall fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.on('callDetailsChange')7+ + +on\(type: 'callDetailsChange', callback: Callback\): void + +Subscribes to **callDetailsChange** events. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------- | ---- | -------------------------- | +| type | string | Yes | Call details change during a call.| +| callback | Callback<[CallAttributeOptions](#callattributeoptions7)> | Yes | Callback used to return the result. | + +**Example** + +```js +call.on('callDetailsChange', (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.on('callEventChange')8+ + +on\(type: 'callEventChange', callback: Callback\): void + +Subscribes to **callEventChange** events. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------ | ---- | -------------------------- | +| type | string | Yes | Call event change during a call.| +| callback | Callback<[CallEventOptions](#calleventoptions8)> | Yes | Callback used to return the result. | + +**Example** + +```js +call.on('callEventChange', (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.on('callDisconnectedCause')8+ + +on\(type: 'callDisconnectedCause', callback: Callback): void + +Subscribes to **callDisconnectedCause** events. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------ | ---- | -------------------------- | +| type | string | Yes | Cause of the call disconnection.| +| callback | Callback<[DisconnectedDetails](#disconnecteddetails8)> | Yes | Callback used to return the result. | + +**Example** + +```js +call.on('callDisconnectedCause', (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.on('mmiCodeResult')9+ + +on\(type: 'mmiCodeResult', callback: Callback\): void + +Subscribes to **mmiCodeResult** events. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------------------------------- | ---- | --------------------- | +| type | string | Yes | Man-machine interface (MMI) code result.| +| callback | Callback<[MmiCodeResults](#mmicoderesults9)> | Yes | Callback used to return the result. | + +**Example** + +```js +isNewCallAllowedcall.on('mmiCodeResult', (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.off('callDetailsChange')7+ + +off\(type: 'callDetailsChange', callback?: Callback\): void + +Unsubscribes from **callDetailsChange** events. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------------------------------------------- | ---- | ---------------------------------- | +| type | string | Yes | Unsubscription from call details changes when a call ends.| +| callback | Callback<[CallAttributeOptions](#callattributeoptions7)> | No | Callback used to return the result. | + +**Example** + +```js +call.off('callDetailsChange', (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.off('callEventChange')8+ + +off\(type: 'callEventChange', callback?: Callback\): void + +Unsubscribes from **callEventChange** events. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------ | ---- | ---------------------------------- | +| type | string | Yes | Unsubscription from call event changes when a call ends.| +| callback | Callback<[CallEventOptions](#calleventoptions8)> | No | Callback used to return the result. | + +**Example** + +```js +call.off('callEventChange', (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.off('callDisconnectedCause')8+ + +off\(type: 'callDisconnectedCause', callback?: Callback\): void + +Unsubscribes from **callDisconnectedCause** events. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------------------------- | ---- | -------------------- | +| type | 'callDisconnectedCause' | Yes | Unsubscription from the call disconnection cause when a call ends.| +| callback | Callback**<**[DisconnectedDetails](#disconnecteddetails8)> | No | Callback used to return the result. | + +**Example** + +```js +call.off('callDisconnectedCause', (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.off('mmiCodeResult')9+ + +off\(type: 'mmiCodeResult', callback?: Callback\): void + +Unsubscribes from **mmiCodeResult** events. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------ | ---- | ----------- | +| type | 'mmiCodeResult' | Yes | MMI code result.| +| callback | Callback<[MmiCodeResults](#mmicoderesults9)> | No | Callback used to return the result. | + +**Example** + +```js +call.off('mmiCodeResult', (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.isNewCallAllowed8+ + +isNewCallAllowed\(callback: AsyncCallback\): void + +Checks whether a new call is allowed. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ---------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.| + +**Example** + +```js +call.isNewCallAllowed((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.isNewCallAllowed8+ + +isNewCallAllowed\(\): Promise + +Checks whether a new call is allowed. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Return value** + +| Type | Description | +| ---------------------- | --------------------------- | +| Promise<boolean> | Promise used to return the result.| + +**Example** + +```js +let promise = call.isNewCallAllowed(); +promise.then(data => { + console.log(`isNewCallAllowed success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`isNewCallAllowed fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.separateConference8+ + +separateConference\(callId: number, callback: AsyncCallback\): void + +Separates a conference call. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callId | number | Yes | Call ID. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.separateConference(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.separateConference8+ + +separateConference\(callId: number\): Promise + +Separates a conference call. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------- | +| callId | number | Yes | Call ID.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.separateConference(1); +promise.then(data => { + console.log(`separateConference success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`separateConference fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.getCallRestrictionStatus8+ + +getCallRestrictionStatus\(slotId: number, type: CallRestrictionType, callback: AsyncCallback\): void + +Obtains the call restriction status. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| type | [CallRestrictionType](#callrestrictiontype8) | Yes | Call restriction type. | +| callback | AsyncCallback<[RestrictionStatus](#restrictionstatus8)> | Yes | Callback used to return the result. | + +**Example** + +```js +call.getCallRestrictionStatus(0, 1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.getCallRestrictionStatus8+ + +getCallRestrictionStatus\(slotId: number, type: CallRestrictionType\): Promise + +Obtains the call restriction status. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | -------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| type | [CallRestrictionType](#callrestrictiontype8) | Yes | Call restriction type. | + +**Return value** + +| Type | Description | +| ------------------------------------------------------- | --------------------------- | +| Promise<[RestrictionStatus](#restrictionstatus8)> | Promise used to return the result.| + +**Example** + +```js +let promise = call.getCallRestrictionStatus(0, 1); +promise.then(data => { + console.log(`getCallRestrictionStatus success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getCallRestrictionStatus fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.setCallRestriction8+ + +setCallRestriction\(slotId: number, info: CallRestrictionInfo, callback: AsyncCallback\): void + +Sets the call restriction status. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| info | [CallRestrictionInfo](#callrestrictioninfo8) | Yes | Call restriction information. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +let callRestrictionInfo={ + type: 1, + password: "123456", + mode: 1 +} +call.setCallRestriction(0, callRestrictionInfo, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.setCallRestriction8+ + +setCallRestriction\(slotId: number, info: CallRestrictionInfo\): Promise + +Sets the call restriction status. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | -------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| info | [CallRestrictionInfo](#callrestrictioninfo8) | Yes | Call restriction information. | + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let callRestrictionInfo={ + type: 1, + password: "123456", + mode: 1 +} +let promise = call.setCallRestriction(0, callRestrictionInfo); +promise.then(data => { + console.log(`setCallRestriction success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`setCallRestriction fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.getCallTransferInfo8+ + +getCallTransferInfo\(slotId: number, type: CallTransferType, callback: AsyncCallback\): void + +Obtains call transfer information. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| type | [CallTransferType](#calltransfertype8) | Yes | Call transfer type. | +| callback | AsyncCallback<[CallTransferResult](#calltransferresult8)> | Yes | Callback used to return the result. | + +**Example** + +```js +let callTransferTyp={ + CallTransferType: 1 +} +call.getCallTransferInfo(0, callTransferTyp, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.getCallTransferInfo8+ + +getCallTransferInfo\(slotId: number, type: CallTransferType): Promise + +Obtains call transfer information. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | -------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| type | [CallTransferType](#calltransfertype8) | Yes | Call transfer type. | + +**Return value** + +| Type | Description | +| --------------------------------------------------------- | --------------------------- | +| Promise<[CallTransferResult](#calltransferresult8)> | Promise used to return the result.| + +**Example** + +```js +let callTransferTyp={ + CallTransferType: 1 +} +let promise = call.getCallTransferInfo(0, callTransferTyp); +promise.then(data => { + console.log(`getCallTransferInfo success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getCallTransferInfo fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.setCallTransfer8+ + +setCallTransfer\(slotId: number, info: CallTransferInfo, callback: AsyncCallback\): void + +Sets call transfer information. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| info | [CallTransferInfo](#calltransferinfo8) | Yes | Call transfer information. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +let callTransferInfo={ + transferNum: "111", + type: 1, + settingType: 1 +} +call.setCallTransfer(0, callTransferInfo, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.setCallTransfer8+ + +setCallTransfer\(slotId: number, info: CallTransferInfo): Promise + +Sets call transfer information. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| info | [CallTransferInfo](#calltransferinfo8) | Yes | Call transfer information. | + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let callTransferInfo={ + transferNum: "111", + type: 1, + settingType: 1 +} +let promise = call.setCallTransfer(0, callTransferInfo); +promise.then(data => { + console.log(`setCallTransfer success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`setCallTransfer fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.isRinging8+ + +isRinging\(callback: AsyncCallback\): void + +Checks whether the ringtone is playing. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ---------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.| + +**Example** + +```js +call.isRinging((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.isRinging8+ + +isRinging\(\): Promise + +Checks whether the ringtone is playing. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CallManager + +**Return value** + +| Type | Description | +| ---------------------- | --------------------------- | +| Promise<boolean> | Promise used to return the result.| + +**Example** + +```js +let promise = call.isRinging(); +promise.then(data => { + console.log(`isRinging success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`isRinging fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.setMuted8+ + +setMuted\(callback: AsyncCallback\): void + +Sets call muting. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.setMuted((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.setMuted8+ + +setMuted\(\): Promise + +Sets call muting. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.setMuted(); +promise.then(data => { + console.log(`setMuted success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`setMuted fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.cancelMuted8+ + +cancelMuted(callback: AsyncCallback): void + +Cancels call muting. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.cancelMuted((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.cancelMuted8+ + +cancelMuted(): Promise + +Cancels call muting. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.cancelMuted(); +promise.then(data => { + console.log(`cancelMuted success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`cancelMuted fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.setAudioDevice8+ + +setAudioDevice\(device: AudioDevice, callback: AsyncCallback\): void + +Sets the audio device for a call. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ---------- | +| device | [AudioDevice](#audiodevice8) | Yes | Audio device.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +call.setAudioDevice(1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.setAudioDevice8+ + +setAudioDevice\(device: AudioDevice, options: AudioDeviceOptions, callback: AsyncCallback\): void + +Sets the audio device for a call based on the specified options. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------ | ---- | -------------- | +| device | [AudioDevice](#audiodevice8) | Yes | Audio device. | +| options | [AudioDeviceOptions](#audiodeviceoptions9) | Yes | Audio device parameters.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +let audioDeviceOptions={ + bluetoothAddress: "IEEE 802-2014" +} +call.setAudioDevice(1, bluetoothAddress, (err, value) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.setAudioDevice8+ + +setAudioDevice(device: AudioDevice, options?: AudioDeviceOptions): Promise + +Sets the audio device for a call based on the specified options. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------------------ | ---- | ------------------ | +| device | [AudioDevice](#audiodevice8) | Yes | Audio device. | +| options | [AudioDeviceOptions](#audiodeviceoptions9) | No | Audio device parameters.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let audioDeviceOptions={ + bluetoothAddress: "IEEE 802-2014" +} +let promise = call.setAudioDevice(1, audioDeviceOptions); +promise.then(data => { + console.log(`setAudioDevice success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`setAudioDevice fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.joinConference8+ + +joinConference(mainCallId: number, callNumberList: Array, callback: AsyncCallback): void + +Joins a conference call. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ------------------------- | ---- | --------------- | +| mainCallId | number | Yes | Main call ID. | +| callNumberList | Array | Yes | List of call numbers.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +call.joinConference(1, "138XXXXXXXX", (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.joinConference8+ + +joinConference(mainCallId: number, callNumberList: Array): Promise + +Joins a conference call. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | -------------- | ---- | --------------- | +| mainCallId | number | Yes | Main call ID. | +| callNumberList | Array | Yes | List of call numbers.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.joinConference(1, "138XXXXXXXX"); +promise.then(data => { + console.log(`joinConference success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`joinConference fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.updateImsCallMode8+ + +updateImsCallMode(callId: number, mode: ImsCallMode, callback: AsyncCallback): void + +Updates the IMS call mode. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | -------------- | +| callId | number | Yes | Call ID. | +| mode | [ImsCallMode](#imscallmode8) | Yes | IMS call mode.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +call.updateImsCallMode(1, 1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.updateImsCallMode8+ + +updateImsCallMode(callId: number, mode: ImsCallMode): Promise + +Updates the IMS call mode. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------------------- | ---- | -------------- | +| callId | number | Yes | Call ID. | +| mode | [ImsCallMode](#imscallmode8) | Yes | IMS call mode.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.updateImsCallMode(1, 1); +promise.then(data => { + console.log(`updateImsCallMode success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`updateImsCallMode fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.enableImsSwitch8+ + +enableImsSwitch(slotId: number, callback: AsyncCallback): void + +Enables the IMS switch. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +call.enableImsSwitch(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.enableImsSwitch8+ + +enableImsSwitch(slotId: number): Promise + +Enables the IMS switch. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.enableImsSwitch(0); +promise.then(data => { + console.log(`enableImsSwitch success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`enableImsSwitch fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.disableImsSwitch8+ + +disableImsSwitch(slotId: number, callback: AsyncCallback): void + +Disables the IMS switch. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +call.disableImsSwitch(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.disableImsSwitch8+ + +disableImsSwitch(slotId: number): Promise + +Disables the IMS switch. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.disableImsSwitch(0); +promise.then(data => { + console.log(`disableImsSwitch success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`disableImsSwitch fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## call.isImsSwitchEnabled8+ + +isImsSwitchEnabled(slotId: number, callback: AsyncCallback): void + +Checks whether the IMS switch is enabled. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. | + +**Example** + +```js +call.isImsSwitchEnabled(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## call.isImsSwitchEnabled8+ + +isImsSwitchEnabled(slotId: number): Promise + +Checks whether the IMS switch is enabled. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ------------------- | --------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let promise = call.isImsSwitchEnabled(0); +promise.then(data => { + console.log(`isImsSwitchEnabled success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`isImsSwitchEnabled fail, promise: err->${JSON.stringify(err)}`); +}); +``` + + ## DialOptions -Provides an option for determining whether a call is a video call. +Defines the dialup options. **System capability**: SystemCapability.Telephony.CallManager -| Name| Type | Mandatory | Description | -| ------ | ------- | ---- | ------------------------------------------------------------ | -| extras | boolean | No | Indication of a video call.
- **true**: video call
- **false** (default): voice call| +| Name | Type | Mandatory| Description | +| ---------- | ---------------------------------- | ---- | ------------------------------------------------------------ | +| extras | boolean | No | Indication of a video call.
- **true**: video call
- **false** (default): voice call| +| accountId | number | No | Account ID. This API is supported since API version 8. It is a system API. | +| videoState | [VideoStateType](#videostatetype7) | No | Video state type. This API is supported since API version 8. It is a system API. | +| dialScene | [DialScene](#dialscene8) | No | Dialup scenario. This API is supported since API version 8. It is a system API. | +| dialType | [DialType](#dialtype8) | No | Dialup type. This API is supported since API version 8. It is a system API. | ## CallState @@ -539,7 +2766,7 @@ Enumerates call states. ## EmergencyNumberOptions7+ -Provides an option for determining whether a number is an emergency number for the SIM card in the specified slot. +Defines options for determining whether a number is an emergency number. **System capability**: SystemCapability.Telephony.CallManager @@ -549,10 +2776,401 @@ Provides an option for determining whether a number is an emergency number for t ## NumberFormatOptions7+ -Provides an option for number formatting. +Defines the number formatting options. **System capability**: SystemCapability.Telephony.CallManager | Name | Type | Mandatory | Description | | ----------- | ------ | ---- | ---------------------------------------------------------- | | countryCode | string | No | Country code, for example, **CN** (China). All country codes are supported. The default value is **CN**. | + +## ImsCallMode8+ + +Enumerates IMS call modes. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ---------------------- | ---- | ------------------ | +| CALL_MODE_AUDIO_ONLY | 0 | Audio call only. | +| CALL_MODE_SEND_ONLY | 1 | Sending calls only. | +| CALL_MODE_RECEIVE_ONLY | 2 | Receiving calls only. | +| CALL_MODE_SEND_RECEIVE | 3 | Sending and receiving calls.| +| CALL_MODE_VIDEO_PAUSED | 4 | Pausing video calls. | + +## AudioDevice8+ + +Enumerates audio devices. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| -------------------- | ---- | ------------ | +| DEVICE_EARPIECE | 0 | Headset device. | +| DEVICE_SPEAKER | 1 | Speaker device.| +| DEVICE_WIRED_HEADSET | 2 | Wired headset device.| +| DEVICE_BLUETOOTH_SCO | 3 | Bluetooth SCO device. | + +## CallRestrictionType8+ + +Enumerates call restriction types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| --------------------------------------------- | ---- | -------------------------- | +| RESTRICTION_TYPE_ALL_INCOMING | 0 | Barring of all incoming calls. | +| RESTRICTION_TYPE_ALL_OUTGOING | 1 | Barring of all outgoing calls. | +| RESTRICTION_TYPE_INTERNATIONAL | 2 | Barring of international calls. | +| RESTRICTION_TYPE_INTERNATIONAL_EXCLUDING_HOME | 3 | Barring of international calls except those in the home country.| +| RESTRICTION_TYPE_ROAMING_INCOMING | 4 | Barring of incoming roaming calls. | +| RESTRICTION_TYPE_ALL_CALLS | 5 | Barring of all calls. | +| RESTRICTION_TYPE_OUTGOING_SERVICES | 6 | Barring of outgoing services. | +| RESTRICTION_TYPE_INCOMING_SERVICES | 7 | Barring of incoming services. | + +## CallTransferInfo8+ + +Defines the call transfer information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Type | Mandatory| Description | +| ----------- | ---------------------------------------------------- | ---- | ---------------- | +| transferNum | string | Yes | Call transfer number. | +| type | [CallTransferType](#calltransfertype8) | Yes | Call transfer type. | +| settingType | [CallTransferSettingType](#calltransfersettingtype8) | Yes | Call transfer setting type.| + +## CallTransferType8+ + +Enumerates call transfer types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| --------------------------- | ---- | ------------ | +| TRANSFER_TYPE_UNCONDITIONAL | 0 | Call forwarding unconditional. | +| TRANSFER_TYPE_BUSY | 1 | Call forwarding busy. | +| TRANSFER_TYPE_NO_REPLY | 2 | Call forwarding on no reply. | +| TRANSFER_TYPE_NOT_REACHABLE | 3 | Call forwarding on no user not reachable.| + +## CallTransferSettingType8+ + +Enumerates call transfer setting types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| -------------------------- | ---- | ------------ | +| CALL_TRANSFER_DISABLE | 0 | Disabling of call transfer.| +| CALL_TRANSFER_ENABLE | 1 | Enabling of call transfer.| +| CALL_TRANSFER_REGISTRATION | 3 | Registration of call transfer.| +| CALL_TRANSFER_ERASURE | 4 | Erasing of call transfer.| + +## CallAttributeOptions7+ + +Defines the call attribute options. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Type | Mandatory| Description | +| --------------- | ---------------------------------------- | ---- | -------------- | +| accountNumber | string | Yes | Account number. | +| speakerphoneOn | boolean | Yes | Speakerphone on.| +| accountId | number | Yes | Account ID. | +| videoState | [VideoStateType](#videostatetype7) | Yes | Video state type. | +| startTime | number | Yes | Start time. | +| isEcc | boolean | Yes | Whether the call is an ECC. | +| callType | [CallType](#calltype7) | Yes | Call type. | +| callId | number | Yes | Call ID. | +| callState | [DetailedCallState](#detailedcallstate7) | Yes | Detailed call state. | +| conferenceState | [ConferenceState](#conferencestate7) | Yes | Conference state. | + +## ConferenceState7+ + +Enumerates conference states. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ---------------------------- | ---- | -------------- | +| TEL_CONFERENCE_IDLE | 0 | Idle state. | +| TEL_CONFERENCE_ACTIVE | 1 | Active state. | +| TEL_CONFERENCE_DISCONNECTING | 2 | Disconnecting state. | +| TEL_CONFERENCE_DISCONNECTED | 3 | Disconnected state.| + +## CallType7+ + +Enumerates call types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ------------- | ---- | ------------ | +| TYPE_CS | 0 | CS call. | +| TYPE_IMS | 1 | IMS call. | +| TYPE_OTT | 2 | OTT call. | +| TYPE_ERR_CALL | 3 | Error call type.| + +## VideoStateType7+ + +Enumerates video state types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ---------- | ---- | -------- | +| TYPE_VOICE | 0 | Voice state.| +| TYPE_VIDEO | 1 | Video state.| + +## DetailedCallState7+ + +Enumerates detailed call states. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ------------------------- | ---- | -------------- | +| CALL_STATUS_ACTIVE | 0 | Active state. | +| CALL_STATUS_HOLDING | 1 | Hold state. | +| CALL_STATUS_DIALING | 2 | Dialing state. | +| CALL_STATUS_ALERTING | 3 | Alerting state. | +| CALL_STATUS_INCOMING | 4 | Incoming state. | +| CALL_STATUS_WAITING | 5 | Waiting state. | +| CALL_STATUS_DISCONNECTED | 6 | Disconnected state.| +| CALL_STATUS_DISCONNECTING | 7 | Disconnecting state. | +| CALL_STATUS_IDLE | 8 | Idle state. | + +## CallRestrictionInfo8+ + +Defines the call restriction information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Type | Mandatory| Description | +| -------- | -------------------------------------------- | ---- | ------------ | +| type | [CallRestrictionType](#callrestrictiontype8) | Yes | Call restriction type.| +| password | string | Yes | Password. | +| mode | [CallRestrictionMode](#callrestrictionmode8) | Yes | Call restriction mode.| + +## CallRestrictionMode8+ + +Enumerates call restriction modes. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ----------------------------- | ---- | ------------ | +| RESTRICTION_MODE_DEACTIVATION | 0 | Call restriction deactivated.| +| RESTRICTION_MODE_ACTIVATION | 1 | Call restriction activated.| + +## CallEventOptions8+ + +Defines the call event options. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------------------ | ---- | -------------- | +| eventId | [CallAbilityEventId](#callabilityeventid8) | Yes | Call ability event ID.| + +## CallAbilityEventId8+ + +Enumerates call ability event IDs. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ------------------------ | ---- | --------------- | +| EVENT_DIAL_NO_CARRIER | 1 | No available carrier during dialing. | +| EVENT_INVALID_FDN_NUMBER | 2 | Invalid FDN.| + +## DialScene8+ + +Enumerates dialup scenarios. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| --------------- | ---- | ------------ | +| CALL_NORMAL | 0 | Common call. | +| CALL_PRIVILEGED | 1 | Privileged call. | +| CALL_EMERGENCY | 2 | Emergency call.| + +## DialType8+ + +Enumerates dialup types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| -------------------- | ---- | ---------------- | +| DIAL_CARRIER_TYPE | 0 | Carrier. | +| DIAL_VOICE_MAIL_TYPE | 1 | Voice mail.| +| DIAL_OTT_TYPE | 2 | OTT. | + +## RejectMessageOptions7+ + +Defines options for the call rejection message. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Type | Mandatory| Description | +| -------------- | ------ | ---- | -------- | +| messageContent | string | Yes | Message content.| + +## CallTransferResult8+ + +Defines the call transfer result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------- | ---- | -------- | +| status | [TransferStatus](#transferstatus8) | Yes | Transfer status.| +| number | string | Yes | Number. | + +## CallWaitingStatus7+ + +Enumerates call waiting states. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| -------------------- | ---- | ------------ | +| CALL_WAITING_DISABLE | 0 | Call waiting disabled.| +| CALL_WAITING_ENABLE | 1 | Call waiting enabled.| + +## RestrictionStatus8+ + +Enumerates call restriction states. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ------------------- | ---- | -------- | +| RESTRICTION_DISABLE | 0 | Call restriction disabled.| +| RESTRICTION_ENABLE | 1 | Call restriction enabled.| + +## TransferStatus8+ + +Enumerates call transfer states. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ---------------- | ---- | -------- | +| TRANSFER_DISABLE | 0 | Call transfer disabled.| +| TRANSFER_ENABLE | 1 | Call transfer enabled.| + +## DisconnectedDetails8+ + +Enumerates causes of call disconnection. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| --------------------------- | ---- | ---------------------- | +| UNASSIGNED_NUMBER | 1 | Unallocated number. | +| NO_ROUTE_TO_DESTINATION | 3 | No route to the destination. | +| CHANNEL_UNACCEPTABLE | 6 | Unacceptable channel. | +| OPERATOR_DETERMINED_BARRING | 8 | Operator determined barring (ODB). | +| NORMAL_CALL_CLEARING | 16 | Normal call clearing. | +| USER_BUSY | 17 | User busy. | +| NO_USER_RESPONDING | 18 | No user response. | +| USER_ALERTING_NO_ANSWER | 19 | Alerting but no answer.| +| CALL_REJECTED | 21 | Call rejected. | +| NUMBER_CHANGED | 22 | Number changed. | +| DESTINATION_OUT_OF_ORDER | 27 | Destination fault. | +| INVALID_NUMBER_FORMAT | 28 | Invalid number format. | +| NETWORK_OUT_OF_ORDER | 38 | Network fault. | +| TEMPORARY_FAILURE | 41 | Temporary fault. | +| INVALID_PARAMETER | 1025 | Invalid parameter. | +| SIM_NOT_EXIT | 1026 | SIM card not exit. | +| SIM_PIN_NEED | 1027 | SIM card PIN required. | +| CALL_NOT_ALLOW | 1029 | Call not allowed. | +| SIM_INVALID | 1045 | Invalid SIM card. | +| UNKNOWN | 1279 | Unknown reason. | + +## MmiCodeResults9+ + +Defines the MMI code result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Type | Mandatory| Description | +| ------- | -------------------------------- | ---- | --------------- | +| result | [MmiCodeResult](#mmicoderesult9) | Yes | MMI code result.| +| message | string | Yes | MMI code message.| + +## MmiCodeResult9+ + +Enumerates MMI code results. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Value | Description | +| ---------------- | ---- | ------------- | +| MMI_CODE_SUCCESS | 0 | Success.| +| MMI_CODE_FAILED | 1 | Failure.| + +## AudioDeviceOptions9+ + +Defines audio device options. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CallManager + +| Name | Type | Mandatory| Description | +| ---------------- | ------ | ---- | -------- | +| bluetoothAddress | string | No | Bluetooth address.| diff --git a/en/application-dev/reference/apis/js-apis-cardEmulation.md b/en/application-dev/reference/apis/js-apis-cardEmulation.md index 18a6a78deee9eabdd16c06d244ca975ef186d67c..9168a42e978c20caaface2523337d8c413a2296e 100644 --- a/en/application-dev/reference/apis/js-apis-cardEmulation.md +++ b/en/application-dev/reference/apis/js-apis-cardEmulation.md @@ -1,9 +1,9 @@ # Standard NFC Card Emulation -The cardEmulation module implements Near-Field Communication (NFC) card emulation. +The **cardEmulation** module implements Near-Field Communication (NFC) card emulation. > **NOTE**
-> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -19,7 +19,7 @@ isSupported(feature: number): boolean Checks whether a certain type of card emulation is supported. -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Return value** @@ -27,11 +27,11 @@ Checks whether a certain type of card emulation is supported. | -------- | -------- | | boolean | Returns **true** if the card emulation is supported; returns **false** otherwise.| -## HceService +## HceService8+ Implements Host-based Card Emulation (HCE). Before calling any API in **HceService**, you must use **new cardEmulation.HceService()** to create an **HceService** instance. -### startHCE +### startHCE8+ startHCE(aidList: string[]): boolean @@ -39,7 +39,7 @@ Starts HCE. **Required permissions**: ohos.permission.NFC_CARD_EMULATION -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Parameters** @@ -47,7 +47,7 @@ Starts HCE. | ------- | -------- | ---- | ----------------------- | | aidList | string[] | Yes | Application ID (AID) list to be registered for card emulation.| -### stopHCE +### stopHCE8+ stopHCE(): boolean @@ -55,9 +55,9 @@ Stops HCE. **Required permissions**: ohos.permission.NFC_CARD_EMULATION -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core -### on +### on8+ on(type: "hceCmd", callback: AsyncCallback): void; @@ -65,7 +65,7 @@ Subscribes to messages from the peer device after **startHCE()**. **Required permissions**: ohos.permission.NFC_CARD_EMULATION -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Parameters** @@ -74,7 +74,7 @@ Subscribes to messages from the peer device after **startHCE()**. | type | string | Yes | Event type to subscribe to. The value is **hceCmd**. | | callback | AsyncCallback | Yes | Callback invoked to return the subscribed event. The input parameter is a data array that complies with the Application Protocol Data Unit (APDU).| -### sendResponse +### sendResponse8+ sendResponse(responseApdu: number[]): void; @@ -82,7 +82,7 @@ Sends a response to the peer device. **Required permissions**: ohos.permission.NFC_CARD_EMULATION -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Parameters** diff --git a/en/application-dev/reference/apis/js-apis-commonEvent.md b/en/application-dev/reference/apis/js-apis-commonEvent.md index 7ba00ae8710ffb3a313d9bc337dc705c9cb60ff0..d0702995d7955ccf0b7a9907ab09b79efd6268ec 100644 --- a/en/application-dev/reference/apis/js-apis-commonEvent.md +++ b/en/application-dev/reference/apis/js-apis-commonEvent.md @@ -1,163 +1,10 @@ # CommonEvent -> **NOTE** -> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +The **CommonEvent** module provides common event capabilities, including the capabilities to publish, subscribe to, and unsubscribe from common events, as well obtaining and setting the common event result code and result data. -## Required Permissions - -| Common Event Macro | Common Event Name | Subscriber Permissions | -| ------------ | ------------------ | ---------------------- | -| COMMON_EVENT_BOOT_COMPLETED | usual.event.BOOT_COMPLETED | ohos.permission.RECEIVER_STARTUP_COMPLETED | -| COMMON_EVENT_LOCKED_BOOT_COMPLETED | usual.event.LOCKED_BOOT_COMPLETED | ohos.permission.RECEIVER_STARTUP_COMPLETED | -| COMMON_EVENT_SHUTDOWN | usual.event.SHUTDOWN | - | -| COMMON_EVENT_BATTERY_CHANGED | usual.event.BATTERY_CHANGED | - | -| COMMON_EVENT_BATTERY_LOW | usual.event.BATTERY_LOW | - | -| COMMON_EVENT_BATTERY_OKAY | usual.event.BATTERY_OKAY | - | -| COMMON_EVENT_POWER_CONNECTED | usual.event.POWER_CONNECTED | - | -| COMMON_EVENT_POWER_DISCONNECTED | usual.event.POWER_DISCONNECTED | - | -| COMMON_EVENT_SCREEN_OFF | usual.event.SCREEN_OFF | - | -| COMMON_EVENT_SCREEN_ON | usual.event.SCREEN_ON | - | -| COMMON_EVENT_THERMAL_LEVEL_CHANGED | usual.event.THERMAL_LEVEL_CHANGED | - | -| COMMON_EVENT_USER_PRESENT | usual.event.USER_PRESENT | - | -| COMMON_EVENT_TIME_TICK | usual.event.TIME_TICK | - | -| COMMON_EVENT_TIME_CHANGED | usual.event.TIME_CHANGED | - | -| COMMON_EVENT_DATE_CHANGED | usual.event.DATE_CHANGED | - | -| COMMON_EVENT_TIMEZONE_CHANGED | usual.event.TIMEZONE_CHANGED | - | -| COMMON_EVENT_CLOSE_SYSTEM_DIALOGS | usual.event.CLOSE_SYSTEM_DIALOGS | - | -| COMMON_EVENT_PACKAGE_ADDED | usual.event.PACKAGE_ADDED | - | -| COMMON_EVENT_PACKAGE_REPLACED | usual.event.PACKAGE_REPLACED | - | -| COMMON_EVENT_MY_PACKAGE_REPLACED | usual.event.MY_PACKAGE_REPLACED | - | -| COMMON_EVENT_PACKAGE_REMOVED | usual.event.PACKAGE_REMOVED | - | -| COMMON_EVENT_BUNDLE_REMOVED | usual.event.BUNDLE_REMOVED | - | -| COMMON_EVENT_PACKAGE_FULLY_REMOVED | usual.event.PACKAGE_FULLY_REMOVED | - | -| COMMON_EVENT_PACKAGE_CHANGED | usual.event.PACKAGE_CHANGED | - | -| COMMON_EVENT_PACKAGE_RESTARTED | usual.event.PACKAGE_RESTARTED | - | -| COMMON_EVENT_PACKAGE_DATA_CLEARED | usual.event.PACKAGE_DATA_CLEARED | - | -| COMMON_EVENT_PACKAGES_SUSPENDED | usual.event.PACKAGES_SUSPENDED | - | -| COMMON_EVENT_PACKAGES_UNSUSPENDED | usual.event.PACKAGES_UNSUSPENDED | - | -| COMMON_EVENT_MY_PACKAGE_SUSPENDED | usual.event.MY_PACKAGE_SUSPENDED | - | -| COMMON_EVENT_MY_PACKAGE_UNSUSPENDED | usual.event.MY_PACKAGE_UNSUSPENDED | - | -| COMMON_EVENT_UID_REMOVED | usual.event.UID_REMOVED | - | -| COMMON_EVENT_PACKAGE_FIRST_LAUNCH | usual.event.PACKAGE_FIRST_LAUNCH | - | -| COMMON_EVENT_PACKAGE_NEEDS_VERIFICATION | usual.event.PACKAGE_NEEDS_VERIFICATION | - | -| COMMON_EVENT_PACKAGE_VERIFIED | usual.event.PACKAGE_VERIFIED | - | -| COMMON_EVENT_EXTERNAL_APPLICATIONS_AVAILABLE | usual.event.EXTERNAL_APPLICATIONS_AVAILABLE | - | -| COMMON_EVENT_EXTERNAL_APPLICATIONS_UNAVAILABLE | usual.event.EXTERNAL_APPLICATIONS_UNAVAILABLE | - | -| COMMON_EVENT_CONFIGURATION_CHANGED | usual.event.CONFIGURATION_CHANGED | - | -| COMMON_EVENT_LOCALE_CHANGED | usual.event.LOCALE_CHANGED | - | -| COMMON_EVENT_MANAGE_PACKAGE_STORAGE | usual.event.MANAGE_PACKAGE_STORAGE | - | -| COMMON_EVENT_DRIVE_MODE | common.event.DRIVE_MODE | - | -| COMMON_EVENT_HOME_MODE | common.event.HOME_MODE | - | -| COMMON_EVENT_OFFICE_MODE | common.event.OFFICE_MODE | - | -| COMMON_EVENT_USER_STARTED | usual.event.USER_STARTED | - | -| COMMON_EVENT_USER_BACKGROUND | usual.event.USER_BACKGROUND | - | -| COMMON_EVENT_USER_FOREGROUND | usual.event.USER_FOREGROUND | - | -| COMMON_EVENT_USER_SWITCHED | usual.event.USER_SWITCHED | ohos.permission.MANAGE_USERS | -| COMMON_EVENT_USER_STARTING | usual.event.USER_STARTING | ohos.permission.INTERACT_ACROSS_USERS | -| COMMON_EVENT_USER_UNLOCKED | usual.event.USER_UNLOCKED | - | -| COMMON_EVENT_USER_STOPPING | usual.event.USER_STOPPING | ohos.permission.INTERACT_ACROSS_USERS | -| COMMON_EVENT_USER_STOPPED | usual.event.USER_STOPPED | - | -| COMMON_EVENT_HWID_LOGIN | common.event.HWID_LOGIN | - | -| COMMON_EVENT_HWID_LOGOUT | common.event.HWID_LOGOUT | - | -| COMMON_EVENT_HWID_TOKEN_INVALID | common.event.HWID_TOKEN_INVALID | - | -| COMMON_EVENT_HWID_LOGOFF | common.event.HWID_LOGOFF | - | -| COMMON_EVENT_WIFI_POWER_STATE | usual.event.wifi.POWER_STATE | - | -| COMMON_EVENT_WIFI_SCAN_FINISHED | usual.event.wifi.SCAN_FINISHED | ohos.permission.LOCATION | -| COMMON_EVENT_WIFI_RSSI_VALUE | usual.event.wifi.RSSI_VALUE | ohos.permission.GET_WIFI_INFO | -| COMMON_EVENT_WIFI_CONN_STATE | usual.event.wifi.CONN_STATE | - | -| COMMON_EVENT_WIFI_HOTSPOT_STATE | usual.event.wifi.HOTSPOT_STATE | - | -| COMMON_EVENT_WIFI_AP_STA_JOIN | usual.event.wifi.WIFI_HS_STA_JOIN | ohos.permission.GET_WIFI_INFO | -| COMMON_EVENT_WIFI_AP_STA_LEAVE | usual.event.wifi.WIFI_HS_STA_LEAVE | ohos.permission.GET_WIFI_INFO | -| COMMON_EVENT_WIFI_MPLINK_STATE_CHANGE | usual.event.wifi.mplink.STATE_CHANGE | ohos.permission.MPLINK_CHANGE_STATE | -| COMMON_EVENT_WIFI_P2P_CONN_STATE | usual.event.wifi.p2p.CONN_STATE_CHANGE | ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION | -| COMMON_EVENT_WIFI_P2P_STATE_CHANGED | usual.event.wifi.p2p.STATE_CHANGE | ohos.permission.GET_WIFI_INFO | -| COMMON_EVENT_WIFI_P2P_PEERS_STATE_CHANGED | usual.event.wifi.p2p.DEVICES_CHANGE | ohos.permission.GET_WIFI_INFO | -| COMMON_EVENT_WIFI_P2P_PEERS_DISCOVERY_STATE_CHANGED | usual.event.wifi.p2p.PEER_DISCOVERY_STATE_CHANGE | ohos.permission.GET_WIFI_INFO | -| COMMON_EVENT_WIFI_P2P_CURRENT_DEVICE_STATE_CHANGED | usual.event.wifi.p2p.CURRENT_DEVICE_CHANGE | ohos.permission.GET_WIFI_INFO | -| COMMON_EVENT_WIFI_P2P_GROUP_STATE_CHANGED | usual.event.wifi.p2p.GROUP_STATE_CHANGED | ohos.permission.GET_WIFI_INFO | -| COMMON_EVENT_BLUETOOTH_HANDSFREE_AG_CONNECT_STATE_UPDATE | usual.event.bluetooth.handsfree.ag.CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_HANDSFREE_AG_CURRENT_DEVICE_UPDATE | usual.event.bluetooth.handsfree.ag.CURRENT_DEVICE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_HANDSFREE_AG_AUDIO_STATE_UPDATE | usual.event.bluetooth.handsfree.ag.AUDIO_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_CONNECT_STATE_UPDATE | usual.event.bluetooth.a2dpsource.CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_CURRENT_DEVICE_UPDATE | usual.event.bluetooth.a2dpsource.CURRENT_DEVICE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_PLAYING_STATE_UPDATE | usual.event.bluetooth.a2dpsource.PLAYING_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_AVRCP_CONNECT_STATE_UPDATE | usual.event.bluetooth.a2dpsource.AVRCP_CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_CODEC_VALUE_UPDATE | usual.event.bluetooth.a2dpsource.CODEC_VALUE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_DISCOVERED | usual.event.bluetooth.remotedevice.DISCOVERED | ohos.permission.LOCATION and ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CLASS_VALUE_UPDATE | usual.event.bluetooth.remotedevice.CLASS_VALUE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_ACL_CONNECTED | usual.event.bluetooth.remotedevice.ACL_CONNECTED | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_ACL_DISCONNECTED | usual.event.bluetooth.remotedevice.ACL_DISCONNECTED | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_NAME_UPDATE | usual.event.bluetooth.remotedevice.NAME_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_PAIR_STATE | usual.event.bluetooth.remotedevice.PAIR_STATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_BATTERY_VALUE_UPDATE | usual.event.bluetooth.remotedevice.BATTERY_VALUE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_SDP_RESULT | usual.event.bluetooth.remotedevice.SDP_RESULT | - | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_UUID_VALUE | usual.event.bluetooth.remotedevice.UUID_VALUE | ohos.permission.DISCOVER_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_PAIRING_REQ | usual.event.bluetooth.remotedevice.PAIRING_REQ | ohos.permission.DISCOVER_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_PAIRING_CANCEL | usual.event.bluetooth.remotedevice.PAIRING_CANCEL | - | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CONNECT_REQ | usual.event.bluetooth.remotedevice.CONNECT_REQ | - | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CONNECT_REPLY | usual.event.bluetooth.remotedevice.CONNECT_REPLY | - | -| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CONNECT_CANCEL | usual.event.bluetooth.remotedevice.CONNECT_CANCEL | - | -| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_CONNECT_STATE_UPDATE | usual.event.bluetooth.handsfreeunit.CONNECT_STATE_UPDATE | - | -| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_AUDIO_STATE_UPDATE | usual.event.bluetooth.handsfreeunit.AUDIO_STATE_UPDATE | - | -| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_AG_COMMON_EVENT | usual.event.bluetooth.handsfreeunit.AG_COMMON_EVENT | - | -| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_AG_CALL_STATE_UPDATE | usual.event.bluetooth.handsfreeunit.AG_CALL_STATE_UPDATE | - | -| COMMON_EVENT_BLUETOOTH_HOST_STATE_UPDATE | usual.event.bluetooth.host.STATE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_HOST_REQ_DISCOVERABLE | usual.event.bluetooth.host.REQ_DISCOVERABLE | - | -| COMMON_EVENT_BLUETOOTH_HOST_REQ_ENABLE | usual.event.bluetooth.host.REQ_ENABLE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_HOST_REQ_DISABLE | usual.event.bluetooth.host.REQ_DISABLE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_HOST_SCAN_MODE_UPDATE | usual.event.bluetooth.host.SCAN_MODE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_HOST_DISCOVERY_STARTED | usual.event.bluetooth.host.DISCOVERY_STARTED | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_HOST_DISCOVERY_FINISHED | usual.event.bluetooth.host.DISCOVERY_FINISHED | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_HOST_NAME_UPDATE | usual.event.bluetooth.host.NAME_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_A2DPSINK_CONNECT_STATE_UPDATE | usual.event.bluetooth.a2dpsink.CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_A2DPSINK_PLAYING_STATE_UPDATE | usual.event.bluetooth.a2dpsink.PLAYING_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_BLUETOOTH_A2DPSINK_AUDIO_STATE_UPDATE | usual.event.bluetooth.a2dpsink.AUDIO_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | -| COMMON_EVENT_NFC_ACTION_ADAPTER_STATE_CHANGED | usual.event.nfc.action.ADAPTER_STATE_CHANGED | - | -| COMMON_EVENT_NFC_ACTION_RF_FIELD_ON_DETECTED | usual.event.nfc.action.RF_FIELD_ON_DETECTED | ohos.permission.MANAGE_SECURE_SETTINGS | -| COMMON_EVENT_NFC_ACTION_RF_FIELD_OFF_DETECTED | usual.event.nfc.action.RF_FIELD_OFF_DETECTED | ohos.permission.MANAGE_SECURE_SETTINGS | -| COMMON_EVENT_DISCHARGING | usual.event.DISCHARGING | - | -| COMMON_EVENT_CHARGING | usual.event.CHARGING | - | -| COMMON_EVENT_DEVICE_IDLE_MODE_CHANGED | usual.event.DEVICE_IDLE_MODE_CHANGED | - | -| COMMON_EVENT_POWER_SAVE_MODE_CHANGED | usual.event.POWER_SAVE_MODE_CHANGED | - | -| COMMON_EVENT_USER_ADDED | usual.event.USER_ADDED | ohos.permission.MANAGE_USERS | -| COMMON_EVENT_USER_REMOVED | usual.event.USER_REMOVED | ohos.permission.MANAGE_USERS | -| COMMON_EVENT_ABILITY_ADDED | usual.event.ABILITY_ADDED | ohos.permission.LISTEN_BUNDLE_CHANGE | -| COMMON_EVENT_ABILITY_REMOVED | usual.event.ABILITY_REMOVED | ohos.permission.LISTEN_BUNDLE_CHANGE | -| COMMON_EVENT_ABILITY_UPDATED | usual.event.ABILITY_UPDATED | ohos.permission.LISTEN_BUNDLE_CHANGE | -| COMMON_EVENT_LOCATION_MODE_STATE_CHANGED | usual.event.location.MODE_STATE_CHANGED | - | -| COMMON_EVENT_IVI_SLEEP | common.event.IVI_SLEEP | - | -| COMMON_EVENT_IVI_PAUSE | common.event.IVI_PAUSE | - | -| COMMON_EVENT_IVI_STANDBY | common.event.IVI_STANDBY | - | -| COMMON_EVENT_IVI_LASTMODE_SAVE | common.event.IVI_LASTMODE_SAVE | - | -| COMMON_EVENT_IVI_VOLTAGE_ABNORMAL | common.event.IVI_VOLTAGE_ABNORMAL | - | -| COMMON_EVENT_IVI_HIGH_TEMPERATURE | common.event.IVI_HIGH_TEMPERATURE | - | -| COMMON_EVENT_IVI_EXTREME_TEMPERATURE | common.event.IVI_EXTREME_TEMPERATURE | - | -| COMMON_EVENT_IVI_TEMPERATURE_ABNORMAL | common.event.IVI_TEMPERATURE_ABNORMAL | - | -| COMMON_EVENT_IVI_VOLTAGE_RECOVERY | common.event.IVI_VOLTAGE_RECOVERY | - | -| COMMON_EVENT_IVI_TEMPERATURE_RECOVERY | common.event.IVI_TEMPERATURE_RECOVERY | - | -| COMMON_EVENT_IVI_ACTIVE | common.event.IVI_ACTIVE | - | -|COMMON_EVENT_USB_STATE9+ | usual.event.hardware.usb.action.USB_STATE | - | -|COMMON_EVENT_USB_PORT_CHANGED9+ | usual.event.hardware.usb.action.USB_PORT_CHANGED | - | -| COMMON_EVENT_USB_DEVICE_ATTACHED | usual.event.hardware.usb.action.USB_DEVICE_ATTACHED | - | -| COMMON_EVENT_USB_DEVICE_DETACHED | usual.event.hardware.usb.action.USB_DEVICE_DETACHED | - | -| COMMON_EVENT_USB_ACCESSORY_ATTACHED | usual.event.hardware.usb.action.USB_ACCESSORY_ATTACHED | - | -| COMMON_EVENT_USB_ACCESSORY_DETACHED | usual.event.hardware.usb.action.USB_ACCESSORY_DETACHED | - | -| COMMON_EVENT_DISK_REMOVED | usual.event.data.DISK_REMOVED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_DISK_UNMOUNTED | usual.event.data.DISK_UNMOUNTED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_DISK_MOUNTED | usual.event.data.DISK_MOUNTED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_DISK_BAD_REMOVAL | usual.event.data.DISK_BAD_REMOVAL | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_DISK_UNMOUNTABLE | usual.event.data.DISK_UNMOUNTABLE | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_DISK_EJECT | usual.event.data.DISK_EJECT | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_VOLUME_REMOVED | usual.event.data.VOLUME_REMOVED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_VOLUME_UNMOUNTED | usual.event.data.VOLUME_UNMOUNTED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_VOLUME_MOUNTED | usual.event.data.VOLUME_MOUNTED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_VOLUME_BAD_REMOVAL | usual.event.data.VOLUME_BAD_REMOVAL | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_VOLUME_EJECT | usual.event.data.VOLUME_EJECT | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| -| COMMON_EVENT_VISIBLE_ACCOUNTS_UPDATED | usual.event.data.VISIBLE_ACCOUNTS_UPDATED | ohos.permission.GET_APP_ACCOUNTS | -| COMMON_EVENT_ACCOUNT_DELETED | usual.event.data.ACCOUNT_DELETED | ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS | -| COMMON_EVENT_FOUNDATION_READY | usual.event.data.FOUNDATION_READY | ohos.permission.RECEIVER_STARTUP_COMPLETED | -| COMMON_EVENT_AIRPLANE_MODE_CHANGED | usual.event.AIRPLANE_MODE | - | -| COMMON_EVENT_SPLIT_SCREEN | usual.event.SPLIT_SCREEN | ohos.permission.RECEIVER_SPLIT_SCREEN | +> **NOTE**
+> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -165,6 +12,170 @@ import CommonEvent from '@ohos.commonEvent'; ``` +## Support + +Provides the event types supported by the **CommonEvent** module. The name and value indicate the macro and name of a common event, respectively. + +**System capability**: SystemCapability.Notification.CommonEvent + +| Name | Value | Subscriber Permissions | Description | +| ------------ | ------------------ | ---------------------- | -------------------- | +| COMMON_EVENT_BOOT_COMPLETED | usual.event.BOOT_COMPLETED | ohos.permission.RECEIVER_STARTUP_COMPLETED | Indicates the common event that the user has finished booting and the system has been loaded. | +| COMMON_EVENT_LOCKED_BOOT_COMPLETED | usual.event.LOCKED_BOOT_COMPLETED | ohos.permission.RECEIVER_STARTUP_COMPLETED | Indicates the common event that the user has finished booting and the system has been loaded but the screen is still locked. | +| COMMON_EVENT_SHUTDOWN | usual.event.SHUTDOWN | - | Indicates the common event that the device is being shut down and the final shutdown will proceed. | +| COMMON_EVENT_BATTERY_CHANGED | usual.event.BATTERY_CHANGED | - | Indicates the common event that the charging state, level, and other information about the battery have changed. | +| COMMON_EVENT_BATTERY_LOW | usual.event.BATTERY_LOW | - | Indicates the common event that the battery level is low. | +| COMMON_EVENT_BATTERY_OKAY | usual.event.BATTERY_OKAY | - | Indicates the common event that the battery exits the low state. | +| COMMON_EVENT_POWER_CONNECTED | usual.event.POWER_CONNECTED | - | Indicates the common event that the device is connected to an external power supply. | +| COMMON_EVENT_POWER_DISCONNECTED | usual.event.POWER_DISCONNECTED | - | Indicates the common event that the device is disconnected from the external power supply. | +| COMMON_EVENT_SCREEN_OFF | usual.event.SCREEN_OFF | - | Indicates the common event that the device screen is off and the device is sleeping. | +| COMMON_EVENT_SCREEN_ON | usual.event.SCREEN_ON | - | Indicates the common event that the device screen is on and the device is in interactive state. | +| COMMON_EVENT_THERMAL_LEVEL_CHANGED8+ | usual.event.THERMAL_LEVEL_CHANGED | - | Indicates the common event that the device's thermal level has changed. | +| COMMON_EVENT_USER_PRESENT | usual.event.USER_PRESENT | - | Indicates the common event that the user unlocks the device. | +| COMMON_EVENT_TIME_TICK | usual.event.TIME_TICK | - | Indicates the common event that the system time has changed. | +| COMMON_EVENT_TIME_CHANGED | usual.event.TIME_CHANGED | - | Indicates the common event that the system time is set. | +| COMMON_EVENT_DATE_CHANGED | usual.event.DATE_CHANGED | - | Indicates the common event that the system time has changed. | +| COMMON_EVENT_TIMEZONE_CHANGED | usual.event.TIMEZONE_CHANGED | - | Indicates the common event that the system time zone has changed. | +| COMMON_EVENT_CLOSE_SYSTEM_DIALOGS | usual.event.CLOSE_SYSTEM_DIALOGS | - | Indicates the common event that a user closes a temporary system dialog box. | +| COMMON_EVENT_PACKAGE_ADDED | usual.event.PACKAGE_ADDED | - | Indicates the common event that a new application package has been installed on the device. | +| COMMON_EVENT_PACKAGE_REPLACED | usual.event.PACKAGE_REPLACED | - | Indicates the common event that a later version of an installed application package has replaced the previous one on the device. | +| COMMON_EVENT_MY_PACKAGE_REPLACED | usual.event.MY_PACKAGE_REPLACED | - | Indicates the common event that a later version of your application package has replaced the previous one. | +| COMMON_EVENT_PACKAGE_REMOVED | usual.event.PACKAGE_REMOVED | - | Indicates the common event that an installed application has been uninstalled from the device with the application data retained. | +| COMMON_EVENT_BUNDLE_REMOVED | usual.event.BUNDLE_REMOVED | - | Indicates the common event that an installed bundle has been uninstalled from the device with the application data retained. | +| COMMON_EVENT_PACKAGE_FULLY_REMOVED | usual.event.PACKAGE_FULLY_REMOVED | - | Indicates the common event that an installed application, including both the application data and code, has been completely uninstalled from the device. | +| COMMON_EVENT_PACKAGE_CHANGED | usual.event.PACKAGE_CHANGED | - | Indicates the common event that an application package has been changed (for example, a component in the package has been enabled or disabled). | +| COMMON_EVENT_PACKAGE_RESTARTED | usual.event.PACKAGE_RESTARTED | - | Indicates the common event that the user has restarted the application package and killed all its processes. | +| COMMON_EVENT_PACKAGE_DATA_CLEARED | usual.event.PACKAGE_DATA_CLEARED | - | Indicates the common event that the user has cleared the application package data. | +| COMMON_EVENT_PACKAGE_CACHE_CLEARED9+ | usual.event.PACKAGE_CACHE_CLEARED | - | Indicates the common event that the user clears the application package cache. | +| COMMON_EVENT_PACKAGES_SUSPENDED | usual.event.PACKAGES_SUSPENDED | - | Indicates the common event that application packages have been suspended. | +| COMMON_EVENT_PACKAGES_UNSUSPENDED | usual.event.PACKAGES_UNSUSPENDED | - | Indicates the common event that application packages have not been suspended. | +| COMMON_EVENT_MY_PACKAGE_SUSPENDED | usual.event.MY_PACKAGE_SUSPENDED | - | Indicates the common event that an application package has been suspended. | +| COMMON_EVENT_MY_PACKAGE_UNSUSPENDED | usual.event.MY_PACKAGE_UNSUSPENDED | - | Indicates the common event that application package has not been suspended. | +| COMMON_EVENT_UID_REMOVED | usual.event.UID_REMOVED | - | Indicates the common event that a user ID has been removed from the system. | +| COMMON_EVENT_PACKAGE_FIRST_LAUNCH | usual.event.PACKAGE_FIRST_LAUNCH | - | Indicates the common event that an installed application is started for the first time. | +| COMMON_EVENT_PACKAGE_NEEDS_VERIFICATION | usual.event.PACKAGE_NEEDS_VERIFICATION | - | Indicates the common event that an application requires system verification. | +| COMMON_EVENT_PACKAGE_VERIFIED | usual.event.PACKAGE_VERIFIED | - | Indicates the common event that an application has been verified by the system. | +| COMMON_EVENT_EXTERNAL_APPLICATIONS_AVAILABLE | usual.event.EXTERNAL_APPLICATIONS_AVAILABLE | - | Indicates the common event that applications installed on the external storage become available for the system. | +| COMMON_EVENT_EXTERNAL_APPLICATIONS_UNAVAILABLE | usual.event.EXTERNAL_APPLICATIONS_UNAVAILABLE | - | Indicates the common event that applications installed on the external storage become unavailable for the system. | +| COMMON_EVENT_CONFIGURATION_CHANGED | usual.event.CONFIGURATION_CHANGED | - | Indicates the common event that the device state (for example, orientation and locale) has changed. | +| COMMON_EVENT_LOCALE_CHANGED | usual.event.LOCALE_CHANGED | - | Indicates the common event that the device locale has changed. | +| COMMON_EVENT_MANAGE_PACKAGE_STORAGE | usual.event.MANAGE_PACKAGE_STORAGE | - | Indicates the common event that the device storage is insufficient. | +| COMMON_EVENT_DRIVE_MODE | common.event.DRIVE_MODE | - | Indicates the common event that the system is in driving mode. | +| COMMON_EVENT_HOME_MODE | common.event.HOME_MODE | - | Indicates the common event that the system is in home mode. | +| COMMON_EVENT_OFFICE_MODE | common.event.OFFICE_MODE | - | Indicates the common event that the system is in office mode. | +| COMMON_EVENT_USER_STARTED | usual.event.USER_STARTED | - | Indicates the common event that the user has been started. | +| COMMON_EVENT_USER_BACKGROUND | usual.event.USER_BACKGROUND | - | Indicates the common event that the user has been brought to the background. | +| COMMON_EVENT_USER_FOREGROUND | usual.event.USER_FOREGROUND | - | Indicates the common event that the user has been brought to the foreground. | +| COMMON_EVENT_USER_SWITCHED | usual.event.USER_SWITCHED | ohos.permission.MANAGE_USERS | Indicates the common event that user switching is happening. | +| COMMON_EVENT_USER_STARTING | usual.event.USER_STARTING | ohos.permission.INTERACT_ACROSS_USERS | Indicates the common event that the user is going to be started. | +| COMMON_EVENT_USER_UNLOCKED | usual.event.USER_UNLOCKED | - | Indicates the common event that the credential-encrypted storage has been unlocked for the current user when the device is unlocked after being restarted. | +| COMMON_EVENT_USER_STOPPING | usual.event.USER_STOPPING | ohos.permission.INTERACT_ACROSS_USERS | Indicates the common event that the user is going to be stopped. | +| COMMON_EVENT_USER_STOPPED | usual.event.USER_STOPPED | - | Indicates the common event that the user has been stopped. | +| COMMON_EVENT_HWID_LOGIN | common.event.HWID_LOGIN | - | Indicates the common event about a HUAWEI ID login. | +| COMMON_EVENT_HWID_LOGOUT | common.event.HWID_LOGOUT | - | Indicates the common event about a HUAWEI ID logout. | +| COMMON_EVENT_HWID_TOKEN_INVALID | common.event.HWID_TOKEN_INVALID | - | Indicates the common event that the HUAWEI ID is invalid. | +| COMMON_EVENT_HWID_LOGOFF | common.event.HWID_LOGOFF | - | Indicates the common event about a HUAWEI ID logoff. | +| COMMON_EVENT_WIFI_POWER_STATE | usual.event.wifi.POWER_STATE | - | Indicates the common event about the Wi-Fi network state, such as enabled and disabled. | +| COMMON_EVENT_WIFI_SCAN_FINISHED | usual.event.wifi.SCAN_FINISHED | ohos.permission.LOCATION | Indicates the common event that the Wi-Fi access point has been scanned and proven to be available. | +| COMMON_EVENT_WIFI_RSSI_VALUE | usual.event.wifi.RSSI_VALUE | ohos.permission.GET_WIFI_INFO | Indicates the common event that the Wi-Fi signal strength (RSSI) has changed. | +| COMMON_EVENT_WIFI_CONN_STATE | usual.event.wifi.CONN_STATE | - | Indicates the common event that the Wi-Fi connection state has changed. | +| COMMON_EVENT_WIFI_HOTSPOT_STATE | usual.event.wifi.HOTSPOT_STATE | - | Indicates the common event about the Wi-Fi hotspot state, such as enabled or disabled. | +| COMMON_EVENT_WIFI_AP_STA_JOIN | usual.event.wifi.WIFI_HS_STA_JOIN | ohos.permission.GET_WIFI_INFO | Indicates the common event that a client has joined the Wi-Fi hotspot of the current device. | +| COMMON_EVENT_WIFI_AP_STA_LEAVE | usual.event.wifi.WIFI_HS_STA_LEAVE | ohos.permission.GET_WIFI_INFO |Indicates the common event that a client has disconnected from the Wi-Fi hotspot of the current device. | +| COMMON_EVENT_WIFI_MPLINK_STATE_CHANGE | usual.event.wifi.mplink.STATE_CHANGE | ohos.permission.MPLINK_CHANGE_STATE | Indicates the common event that the state of MPLINK (an enhanced Wi-Fi feature) has changed. | +| COMMON_EVENT_WIFI_P2P_CONN_STATE | usual.event.wifi.p2p.CONN_STATE_CHANGE | ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION | Indicates the common event that the Wi-Fi P2P connection state has changed. | +| COMMON_EVENT_WIFI_P2P_STATE_CHANGED | usual.event.wifi.p2p.STATE_CHANGE | ohos.permission.GET_WIFI_INFO | Indicates the common event about the Wi-Fi P2P state, such as enabled and disabled. | +| COMMON_EVENT_WIFI_P2P_PEERS_STATE_CHANGED | usual.event.wifi.p2p.DEVICES_CHANGE | ohos.permission.GET_WIFI_INFO | Indicates the common event about the status change of Wi-Fi P2P peer devices. | +| COMMON_EVENT_WIFI_P2P_PEERS_DISCOVERY_STATE_CHANGED | usual.event.wifi.p2p.PEER_DISCOVERY_STATE_CHANGE | ohos.permission.GET_WIFI_INFO | Indicates the common event about the Wi-Fi P2P discovery status change. | +| COMMON_EVENT_WIFI_P2P_CURRENT_DEVICE_STATE_CHANGED | usual.event.wifi.p2p.CURRENT_DEVICE_CHANGE | ohos.permission.GET_WIFI_INFO | Indicates the common event about the status change of the Wi-Fi P2P local device. | +| COMMON_EVENT_WIFI_P2P_GROUP_STATE_CHANGED | usual.event.wifi.p2p.GROUP_STATE_CHANGED | ohos.permission.GET_WIFI_INFO | Indicates the common event that the Wi-Fi P2P group information has changed. | +| COMMON_EVENT_BLUETOOTH_HANDSFREE_AG_CONNECT_STATE_UPDATE | usual.event.bluetooth.handsfree.ag.CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event about the connection state of Bluetooth handsfree communication. | +| COMMON_EVENT_BLUETOOTH_HANDSFREE_AG_CURRENT_DEVICE_UPDATE | usual.event.bluetooth.handsfree.ag.CURRENT_DEVICE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the device connected to the Bluetooth handsfree is active. | +| COMMON_EVENT_BLUETOOTH_HANDSFREE_AG_AUDIO_STATE_UPDATE | usual.event.bluetooth.handsfree.ag.AUDIO_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the connection state of Bluetooth A2DP has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_CONNECT_STATE_UPDATE | usual.event.bluetooth.a2dpsource.CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event about the connection state of Bluetooth A2DP. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_CURRENT_DEVICE_UPDATE | usual.event.bluetooth.a2dpsource.CURRENT_DEVICE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the device connected using Bluetooth A2DP is active. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_PLAYING_STATE_UPDATE | usual.event.bluetooth.a2dpsource.PLAYING_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the playing state of Bluetooth A2DP has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_AVRCP_CONNECT_STATE_UPDATE | usual.event.bluetooth.a2dpsource.AVRCP_CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the AVRCP connection state of Bluetooth A2DP has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_CODEC_VALUE_UPDATE | usual.event.bluetooth.a2dpsource.CODEC_VALUE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the audio codec state of Bluetooth A2DP has changed. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_DISCOVERED | usual.event.bluetooth.remotedevice.DISCOVERED | ohos.permission.LOCATION and ohos.permission.USE_BLUETOOTH | Indicates the common event that a remote Bluetooth device is discovered. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CLASS_VALUE_UPDATE | usual.event.bluetooth.remotedevice.CLASS_VALUE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth class of a remote Bluetooth device has changed. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_ACL_CONNECTED | usual.event.bluetooth.remotedevice.ACL_CONNECTED | ohos.permission.USE_BLUETOOTH | Indicates the common event that a low-ACL connection has been established with a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_ACL_DISCONNECTED | usual.event.bluetooth.remotedevice.ACL_DISCONNECTED | ohos.permission.USE_BLUETOOTH | Indicates the common event that a low-ACL connection has been disconnected from a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_NAME_UPDATE | usual.event.bluetooth.remotedevice.NAME_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the friendly name of a remote Bluetooth device is retrieved for the first time or is changed since the last retrieval. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_PAIR_STATE | usual.event.bluetooth.remotedevice.PAIR_STATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the connection state of a remote Bluetooth device has changed. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_BATTERY_VALUE_UPDATE | usual.event.bluetooth.remotedevice.BATTERY_VALUE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the battery level of a remote Bluetooth device is retrieved for the first time or is changed since the last retrieval. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_SDP_RESULT | usual.event.bluetooth.remotedevice.SDP_RESULT | - | Indicates the common event about the SDP state of a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_UUID_VALUE | usual.event.bluetooth.remotedevice.UUID_VALUE | ohos.permission.DISCOVER_BLUETOOTH | Indicates the common event about the UUID connection state of a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_PAIRING_REQ | usual.event.bluetooth.remotedevice.PAIRING_REQ | ohos.permission.DISCOVER_BLUETOOTH | Indicates the common event about the pairing request from a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_PAIRING_CANCEL | usual.event.bluetooth.remotedevice.PAIRING_CANCEL | - | Indicates the common event that Bluetooth pairing is canceled. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CONNECT_REQ | usual.event.bluetooth.remotedevice.CONNECT_REQ | - | Indicates the common event about the connection request from a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CONNECT_REPLY | usual.event.bluetooth.remotedevice.CONNECT_REPLY | - | Indicates the common event about the response to the connection request from a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CONNECT_CANCEL | usual.event.bluetooth.remotedevice.CONNECT_CANCEL | - | Indicates the common event that the connection to a remote Bluetooth device has been canceled. | +| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_CONNECT_STATE_UPDATE | usual.event.bluetooth.handsfreeunit.CONNECT_STATE_UPDATE | - | Indicates the common event that the connection state of a Bluetooth handsfree has changed. | +| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_AUDIO_STATE_UPDATE | usual.event.bluetooth.handsfreeunit.AUDIO_STATE_UPDATE | - | Indicates the common event that the audio state of a Bluetooth handsfree has changed. | +| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_AG_COMMON_EVENT | usual.event.bluetooth.handsfreeunit.AG_COMMON_EVENT | - | Indicates the common event that the audio gateway state of a Bluetooth handsfree has changed. | +| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_AG_CALL_STATE_UPDATE | usual.event.bluetooth.handsfreeunit.AG_CALL_STATE_UPDATE | - | Indicates the common event that the calling state of a Bluetooth handsfree has changed. | +| COMMON_EVENT_BLUETOOTH_HOST_STATE_UPDATE | usual.event.bluetooth.host.STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the state of a Bluetooth adapter has been changed, for example, Bluetooth has been enabled or disabled. | +| COMMON_EVENT_BLUETOOTH_HOST_REQ_DISCOVERABLE | usual.event.bluetooth.host.REQ_DISCOVERABLE | - | Indicates the common event about the request for the user to allow Bluetooth device scanning. | +| COMMON_EVENT_BLUETOOTH_HOST_REQ_ENABLE | usual.event.bluetooth.host.REQ_ENABLE | ohos.permission.USE_BLUETOOTH | Indicates the common event about the request for the user to enable Bluetooth. | +| COMMON_EVENT_BLUETOOTH_HOST_REQ_DISABLE | usual.event.bluetooth.host.REQ_DISABLE | ohos.permission.USE_BLUETOOTH | Indicates the common event about the request for the user to disable Bluetooth. | +| COMMON_EVENT_BLUETOOTH_HOST_SCAN_MODE_UPDATE | usual.event.bluetooth.host.SCAN_MODE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth scanning mode of a device has changed. | +| COMMON_EVENT_BLUETOOTH_HOST_DISCOVERY_STARTED | usual.event.bluetooth.host.DISCOVERY_STARTED | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth scanning has been started on the device. | +| COMMON_EVENT_BLUETOOTH_HOST_DISCOVERY_FINISHED | usual.event.bluetooth.host.DISCOVERY_FINISHED | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth scanning is finished on the device. | +| COMMON_EVENT_BLUETOOTH_HOST_NAME_UPDATE | usual.event.bluetooth.host.NAME_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth adapter name of the device has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSINK_CONNECT_STATE_UPDATE | usual.event.bluetooth.a2dpsink.CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the connection state of Bluetooth A2DP Sink has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSINK_PLAYING_STATE_UPDATE | usual.event.bluetooth.a2dpsink.PLAYING_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the playing state of Bluetooth A2DP Sink has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSINK_AUDIO_STATE_UPDATE | usual.event.bluetooth.a2dpsink.AUDIO_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the audio state of Bluetooth A2DP Sink has changed. | +| COMMON_EVENT_NFC_ACTION_ADAPTER_STATE_CHANGED | usual.event.nfc.action.ADAPTER_STATE_CHANGED | - | Indicates the common event that the state of the device's NFC adapter has changed. | +| COMMON_EVENT_NFC_ACTION_RF_FIELD_ON_DETECTED | usual.event.nfc.action.RF_FIELD_ON_DETECTED | ohos.permission.MANAGE_SECURE_SETTINGS | Indicates the common event that the NFC RF field is detected to be in the enabled state. | +| COMMON_EVENT_NFC_ACTION_RF_FIELD_OFF_DETECTED | usual.event.nfc.action.RF_FIELD_OFF_DETECTED | ohos.permission.MANAGE_SECURE_SETTINGS | Indicates the common event that the NFC RF field is detected to be in the disabled state. | +| COMMON_EVENT_DISCHARGING | usual.event.DISCHARGING | - | Indicates the common event that the system stops charging the battery. | +| COMMON_EVENT_CHARGING | usual.event.CHARGING | - | Indicates the common event that the system starts charging the battery. | +| COMMON_EVENT_DEVICE_IDLE_MODE_CHANGED | usual.event.DEVICE_IDLE_MODE_CHANGED | - | Indicates the common event that the system idle mode has changed. | +| COMMON_EVENT_POWER_SAVE_MODE_CHANGED | usual.event.POWER_SAVE_MODE_CHANGED | - | Indicates the common event that the power saving mode of the system has changed. | +| COMMON_EVENT_USER_ADDED | usual.event.USER_ADDED | ohos.permission.MANAGE_USERS | Indicates the common event that a user has been added to the system. | +| COMMON_EVENT_USER_REMOVED | usual.event.USER_REMOVED | ohos.permission.MANAGE_USERS | Indicates the common event that a user has been removed from the system. | +| COMMON_EVENT_ABILITY_ADDED | usual.event.ABILITY_ADDED | ohos.permission.LISTEN_BUNDLE_CHANGE | Indicates the common event that an ability has been added. | +| COMMON_EVENT_ABILITY_REMOVED | usual.event.ABILITY_REMOVED | ohos.permission.LISTEN_BUNDLE_CHANGE | Indicates the common event that an ability has been removed. | +| COMMON_EVENT_ABILITY_UPDATED | usual.event.ABILITY_UPDATED | ohos.permission.LISTEN_BUNDLE_CHANGE | Indicates the common event that an ability has been updated. | +| COMMON_EVENT_LOCATION_MODE_STATE_CHANGED | usual.event.location.MODE_STATE_CHANGED | - | Indicates the common event that the location mode of the system has changed. | +| COMMON_EVENT_IVI_SLEEP | common.event.IVI_SLEEP | - | Indicates the common event that the in-vehicle infotainment (IVI) system of a vehicle is sleeping. | +| COMMON_EVENT_IVI_PAUSE | common.event.IVI_PAUSE | - | Indicates the common event that the IVI system of a vehicle has entered sleep mode and the playing application is instructed to stop playback. | +| COMMON_EVENT_IVI_STANDBY | common.event.IVI_STANDBY | - | Indicates the common event that a third-party application is instructed to pause the current work. | +| COMMON_EVENT_IVI_LASTMODE_SAVE | common.event.IVI_LASTMODE_SAVE | - | Indicates the common event that a third-party application is instructed to save its last mode. | +| COMMON_EVENT_IVI_VOLTAGE_ABNORMAL | common.event.IVI_VOLTAGE_ABNORMAL | - | Indicates the common event that the voltage of the vehicle's power system is abnormal. | +| COMMON_EVENT_IVI_HIGH_TEMPERATURE | common.event.IVI_HIGH_TEMPERATURE | - | Indicates the common event that the temperature of the IVI system is high. | +| COMMON_EVENT_IVI_EXTREME_TEMPERATURE | common.event.IVI_EXTREME_TEMPERATURE | - | Indicates the common event that the temperature of the IVI system is extremely high. | +| COMMON_EVENT_IVI_TEMPERATURE_ABNORMAL | common.event.IVI_TEMPERATURE_ABNORMAL | - | Indicates the common event that the IVI system has an extreme temperature. | +| COMMON_EVENT_IVI_VOLTAGE_RECOVERY | common.event.IVI_VOLTAGE_RECOVERY | - | Indicates the common event that the voltage of the vehicle's power system is restored to normal. | +| COMMON_EVENT_IVI_TEMPERATURE_RECOVERY | common.event.IVI_TEMPERATURE_RECOVERY | - | Indicates the common event that the temperature of the IVI system is restored to normal. | +| COMMON_EVENT_IVI_ACTIVE | common.event.IVI_ACTIVE | - | Indicates the common event that the battery service is active. | +|COMMON_EVENT_USB_STATE9+ | usual.event.hardware.usb.action.USB_STATE | - | Indicates the common event that the USB device status has changed. | +|COMMON_EVENT_USB_PORT_CHANGED9+ | usual.event.hardware.usb.action.USB_PORT_CHANGED | - | Indicates the common event that the USB port status of the user device has changed. | +| COMMON_EVENT_USB_DEVICE_ATTACHED | usual.event.hardware.usb.action.USB_DEVICE_ATTACHED | - | Indicates the common event that a USB device has been attached when the user device functions as a USB host. | +| COMMON_EVENT_USB_DEVICE_DETACHED | usual.event.hardware.usb.action.USB_DEVICE_DETACHED | - | Indicates the common event that a USB device has been detached when the user device functions as a USB host. | +| COMMON_EVENT_USB_ACCESSORY_ATTACHED | usual.event.hardware.usb.action.USB_ACCESSORY_ATTACHED | - | Indicates the common event that a USB accessory was attached. | +| COMMON_EVENT_USB_ACCESSORY_DETACHED | usual.event.hardware.usb.action.USB_ACCESSORY_DETACHED | - | Indicates the common event that a USB accessory was detached. | +| COMMON_EVENT_DISK_REMOVED | usual.event.data.DISK_REMOVED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was removed. | +| COMMON_EVENT_DISK_UNMOUNTED | usual.event.data.DISK_UNMOUNTED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was unmounted. | +| COMMON_EVENT_DISK_MOUNTED | usual.event.data.DISK_MOUNTED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was mounted. | +| COMMON_EVENT_DISK_BAD_REMOVAL | usual.event.data.DISK_BAD_REMOVAL | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was removed without being unmounted. | +| COMMON_EVENT_DISK_UNMOUNTABLE | usual.event.data.DISK_UNMOUNTABLE | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device becomes unmountable. | +| COMMON_EVENT_DISK_EJECT | usual.event.data.DISK_EJECT | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was ejected. | +| COMMON_EVENT_VOLUME_REMOVED9+ | usual.event.data.VOLUME_REMOVED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was removed. | +| COMMON_EVENT_VOLUME_UNMOUNTED9+ | usual.event.data.VOLUME_UNMOUNTED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was unmounted. | +| COMMON_EVENT_VOLUME_MOUNTED9+ | usual.event.data.VOLUME_MOUNTED | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was mounted. | +| COMMON_EVENT_VOLUME_BAD_REMOVAL9+ | usual.event.data.VOLUME_BAD_REMOVAL | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was removed without being unmounted. | +| COMMON_EVENT_VOLUME_EJECT9+ | usual.event.data.VOLUME_EJECT | ohos.permission.WRITE_USER_STORAGE or ohos.permission.READ_USER_STORAGE| Indicates the common event that an external storage device was ejected. | +| COMMON_EVENT_VISIBLE_ACCOUNTS_UPDATED | usual.event.data.VISIBLE_ACCOUNTS_UPDATED | ohos.permission.GET_APP_ACCOUNTS | Indicates the common event that the account visibility changed. | +| COMMON_EVENT_ACCOUNT_DELETED | usual.event.data.ACCOUNT_DELETED | ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS | Indicates the common event that the account was deleted. | +| COMMON_EVENT_FOUNDATION_READY | usual.event.data.FOUNDATION_READY | ohos.permission.RECEIVER_STARTUP_COMPLETED | Indicates the common event that the foundation is ready. | +| COMMON_EVENT_AIRPLANE_MODE_CHANGED | usual.event.AIRPLANE_MODE | - | Indicates the common event that the airplane mode of the device has changed. | +| COMMON_EVENT_SPLIT_SCREEN8+ | usual.event.SPLIT_SCREEN | ohos.permission.RECEIVER_SPLIT_SCREEN | Indicates the common event of screen splitting. | +| COMMON_EVENT_SLOT_CHANGE9+ | usual.event.SLOT_CHANGE | ohos.permission.NOTIFICATION_CONTROLLER | Indicates the common event that the notification slot has changed. | +| COMMON_EVENT_SPN_INFO_CHANGED9+ | usual.event.SPN_INFO_CHANGED | - | Indicates the common event that the SPN displayed has been updated. | + + ## CommonEvent.publish publish(event: string, callback: AsyncCallback\): void @@ -183,7 +194,7 @@ Publishes a common event. This API uses a callback to return the result. **Example** ```js -// Callback for common event publication. +// Callback for common event publication function PublishCallBack(err) { if (err.code) { console.error("publish failed " + JSON.stringify(err)); @@ -220,8 +231,8 @@ Publishes a common event with given attributes. This API uses a callback to retu ```js // Attributes of a common event. var options = { - code: 0, // Result code of the common event - data: "initial data",// Result data of the common event + code: 0, // Result code of the common event. + data: "initial data";// Result data of the common event. isOrdered: true // The common event is an ordered one. } @@ -248,6 +259,8 @@ Publishes a common event to a specific user. This API uses a callback to return **System capability**: SystemCapability.Notification.CommonEvent +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name | Readable/Writable| Type | Mandatory| Description | @@ -259,7 +272,7 @@ Publishes a common event to a specific user. This API uses a callback to return **Example** ```js -// Callback for common event publication. +// Callback for common event publication function PublishAsUserCallBack(err) { if (err.code) { console.error("publishAsUser failed " + JSON.stringify(err)); @@ -285,6 +298,8 @@ Publishes a common event with given attributes to a specific user. This API uses **System capability**: SystemCapability.Notification.CommonEvent +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name | Readable/Writable| Type | Mandatory| Description | @@ -300,8 +315,8 @@ Publishes a common event with given attributes to a specific user. This API uses ```js // Attributes of a common event. var options = { - code: 0, // Result code of the common event - data: "initial data",// Result data of the common event + code: 0, // Result code of the common event. + data: "initial data";// Result data of the common event } // Callback for common event publication @@ -562,7 +577,7 @@ Obtains the result code of this common event. This API uses a promise to return | Type | Description | | ---------------- | -------------------- | -| Promise\ | Promise used to return the result code.| +| Promise\ | Promise used to return the result.| **Example** @@ -625,7 +640,7 @@ Sets the result code for this common event. This API uses a promise to return th | Type | Description | | ---------------- | -------------------- | -| Promise\ | Promise used to return the result code.| +| Promise\ | Promise used to return the result.| **Example** @@ -744,7 +759,7 @@ Sets the result data for this common event. This API uses a promise to return th | Type | Description | | ---------------- | -------------------- | -| Promise\ | Promise used to return the result data.| +| Promise\ | Promise used to return the result.| **Example** diff --git a/en/application-dev/reference/apis/js-apis-connectedTag.md b/en/application-dev/reference/apis/js-apis-connectedTag.md index f351fb3148f0e216af608b6222b8c32a0805a3cb..57cf8eadb5a07bcd3038c67d4d582ab4359d2ea2 100644 --- a/en/application-dev/reference/apis/js-apis-connectedTag.md +++ b/en/application-dev/reference/apis/js-apis-connectedTag.md @@ -1,5 +1,7 @@ # Active Tag +The **connectedTag** module provides methods for using active tags. You can use the APIs provided by this module to initialize the active tag chip and read and write active tags. + > **NOTE**
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -22,9 +24,9 @@ Initializes the active tag chip. **System capability**: SystemCapability.Communication.ConnectedTag - Return value - | **Type** | **Description** | - | -------- | -------- | - | boolean | Returns **true** if the initialization is successful; returns **false** otherwise. | + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the initialization is successful; returns **false** otherwise.| ## connectedTag.uninit @@ -38,9 +40,9 @@ Uninitializes the active tag resources. **System capability**: SystemCapability.Communication.ConnectedTag - Return value - | **Type** | **Description** | - | -------- | -------- | - | boolean | Returns **true** if the operation is successful; returns **false** otherwise. | + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| ## connectedTag.readNdefTag @@ -54,14 +56,14 @@ Reads the content of this active tag. This method uses a promise to return the r **System capability**: SystemCapability.Communication.ConnectedTag - Return value - | **Type** | **Description** | - | -------- | -------- | - | Promise<string> | Promise used to return the content of the active tag. | + | **Type**| **Description**| + | -------- | -------- | + | Promise<string> | Promise used to return the content of the active tag.| - Example ``` import connectedTag from '@ohos.connectedTag'; - + connectedTag.readNdefTag().then(result => { console.log("promise recv ndef response: " + result); }); @@ -78,9 +80,9 @@ Reads the content of this active tag. This method uses an asynchronous callback **System capability**: SystemCapability.Communication.ConnectedTag - Parameters - | **Name** | **Type** | **Mandatory** | **Description** | - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<string> | Yes | Callback invoked to return the active tag content obtained. | + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<string> | Yes| Callback invoked to return the active tag content obtained.| - Example ``` @@ -102,14 +104,14 @@ Writes data to this active tag. This method uses a promise to return the result. **System capability**: SystemCapability.Communication.ConnectedTag - Parameters - | **Name** | **Type** | **Mandatory** | **Description** | - | -------- | -------- | -------- | -------- | - | data | string | Yes | Data to write. The maximum length is 1024 bytes. | + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | data | string | Yes| Data to write. The maximum length is 1024 bytes.| - Return value - | **Type** | **Description** | - | -------- | -------- | - | Promise<void> | Promise used to return the result. This method returns no value. | + | **Type**| **Description**| + | -------- | -------- | + | Promise<void> | Promise used to return the result. This method returns no value.| - Example ``` @@ -127,7 +129,7 @@ Writes data to this active tag. This method uses a promise to return the result. ## connectedTag.writeNdefTag -writeNdefTag(data: string, callback: AsyncCallback<string>): void +writeNdefTag(data: string, callback: AsyncCallback<void>): void Writes data to this active tag. This method uses an asynchronous callback to return the result. @@ -136,10 +138,10 @@ Writes data to this active tag. This method uses an asynchronous callback to ret **System capability**: SystemCapability.Communication.ConnectedTag - Parameters - | **Name** | **Type** | **Mandatory** | **Description** | - | -------- | -------- | -------- | -------- | - | data | string | Yes | Data to write. The maximum length is 1024 bytes. | - | callback | AsyncCallback<string> | Yes | Callback invoked to return the operation result. | + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | data | string | Yes| Data to write. The maximum length is 1024 bytes.| + | callback | AsyncCallback<string> | Yes| Callback invoked to return the active tag content obtained.| - Example ``` @@ -151,7 +153,7 @@ Writes data to this active tag. This method uses an asynchronous callback to ret console.error(`failed to write event because ${err.code}`); return; } - + // Data is written to the tag. console.log(`success to write event: ${value}`); }); @@ -168,16 +170,16 @@ Registers the NFC field strength state events. **System capability**: SystemCapability.Communication.ConnectedTag - Parameters - | **Name** | **Type** | **Mandatory** | **Description** | - | -------- | -------- | -------- | -------- | - | type | string | Yes | Event type. The value is **notify**. | - | callback | Callback<number> | Yes | Callback invoked to return the field strength state. | + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **notify**.| + | callback | Callback<number> | Yes| Callback invoked to return the field strength state.| - Enumerates the field strength states. - | **Value** | **Description** | - | -------- | -------- | - | 0 | Field off. | - | 1 | Field on. | + | **Value**| **Description**| + | -------- | -------- | + | 0 | Field off.| + | 1 | Field on.| ## connectedTag.off('notify') @@ -191,10 +193,10 @@ Unregisters the NFC field strength state events. **System capability**: SystemCapability.Communication.ConnectedTag - Parameters - | **Name** | **Type** | **Mandatory** | **Description** | - | -------- | -------- | -------- | -------- | - | type | string | Yes | Event type. The value is **notify**. | - | callback | Callback<number> | No | Callback used to return the field strength state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered. | + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **notify**.| + | callback | Callback<number> | No| Callback used to return the field strength state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| - Example ``` @@ -206,10 +208,10 @@ Unregisters the NFC field strength state events. console.info("nfc rf receive state: " + result); } - // Register event notification + // Register event notification. connectedTag.on(NFC_RF_NOTIFY, recvNfcRfNotifyFunc); - // Unregister event notification + // Unregister event notification. connectedTag.off(NFC_RF_NOTIFY, recvNfcRfNotifyFunc); ``` @@ -217,7 +219,9 @@ Unregisters the NFC field strength state events. Enumerates the NFC states. - | Name | Default Value | Description | - | -------- | -------- | -------- | - | NFC_RF_LEAVE | 0 | Field off. | - | NFC_RF_ENTER | 1 | Field on. | +**System capability**: SystemCapability.Communication.ConnectedTag + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| NFC_RF_LEAVE | 0 | Field on.| +| NFC_RF_ENTER | 1 | Field on.| diff --git a/en/application-dev/reference/apis/js-apis-data-rdb.md b/en/application-dev/reference/apis/js-apis-data-rdb.md index adf54efbe8e95058c353a049211cec7c20e72ae3..296b8a58c2e89677eed23ee377c7568603429646 100644 --- a/en/application-dev/reference/apis/js-apis-data-rdb.md +++ b/en/application-dev/reference/apis/js-apis-data-rdb.md @@ -4,7 +4,7 @@ The relational database (RDB) manages data based on relational models. With the This module provides the following RDB-related functions: -- [RdbPredicates](#rdbpredicates): predicates indicating the nature, feature, or relationship of a data entity in an RDB store. It is used to define the operation conditions for an RDB store. +- [RdbPredicates](#rdbpredicates): provides predicates indicating the nature, feature, or relationship of a data entity in an RDB store. It is used to define the operation conditions for an RDB store. - [RdbStore](#rdbstore): provides APIs for managing an RDB store. > **NOTE**
@@ -166,14 +166,14 @@ let predicates = new data_rdb.RdbPredicates("EMPLOYEE") inDevices(devices: Array<string>): RdbPredicates -Specifies a remote device on the network during distributed database synchronization. +Connects to the specified remote devices on the network during distributed database synchronization. **System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| devices | Array<string> | Yes| ID of the remote device to specify.| +| devices | Array<string> | Yes| IDs of the remote devices in the same network.| **Return value** | Type| Description| @@ -948,6 +948,8 @@ predicates.notIn("NAME", ["Lisa", "Rose"]) Provides methods to manage an RDB store. +Before using the following APIs, use [executeSql](#executesql) to initialize the database table structure and related data. For details, see [RDB Development](../../database/database-relational-guidelines.md). + ### insert @@ -977,7 +979,7 @@ rdbStore.insert("EMPLOYEE", valueBucket, function (status, rowId) { console.log("Failed to insert data"); return; } - console.log("Inserted data, rowId = " + rowId); + console.log("Inserted data successfully, rowId = " + rowId); }) ``` @@ -1011,7 +1013,7 @@ const valueBucket = { } let promise = rdbStore.insert("EMPLOYEE", valueBucket) promise.then((rowId) => { - console.log("Inserted data, rowId = " + rowId); + console.log("Inserted data successfully, rowId = " + rowId); }).catch((status) => { console.log("Failed to insert data"); }) @@ -1056,10 +1058,10 @@ const valueBucket3 = { var valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); rdbStore.batchInsert("EMPLOYEE", valueBuckets, function(status, insertNum) { if (status) { - console.log("bathInsert failed, status = " + status); + console.log("Failed to batch insert data, status = " + status); return; } - console.log("bathInsert is successful, the number of values that were inserted = " + insertNum); + console.log("Batch inserted data successfully. The number of values that were inserted = " + insertNum); }) ``` @@ -1106,9 +1108,9 @@ const valueBucket3 = { var valueBuckets = new Array(valueBucket1, valueBucket2, valueBucket3); let promise = rdbStore.batchInsert("EMPLOYEE", valueBuckets); promise.then((insertNum) => { - console.log("bathInsert is successful, the number of values that were inserted = " + insertNum); + console.log("Batch inserted data successfully. The number of values that were inserted = " + insertNum); }).catch((status) => { - console.log("bathInsert failed, status = " + status); + console.log("Failed to batch insert data, status = " + status); }) ``` @@ -1116,14 +1118,14 @@ promise.then((insertNum) => { update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback<number>):void -Updates data based on the specified **RdbPredicates** object. This API uses an asynchronous callback to return the result. +Updates data in the RDB store based on the specified **RdbPredicates** object. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| values | [ValuesBucket](#valuesbucket) | Yes| Rows of data to update in the RDB store. The key-value pair is associated with the column name in the target table.| +| values | [ValuesBucket](#valuesbucket) | Yes| Data to update. The key-value pair is associated with the column name in the target table.| | predicates | [RdbPredicates](#rdbpredicates) | Yes| Update conditions specified by the **RdbPredicates** object.| | callback | AsyncCallback<number> | Yes| Callback invoked to return the number of rows updated.| @@ -1158,7 +1160,7 @@ Updates data based on the specified **RdbPredicates** object. This API uses a pr **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| values | [ValuesBucket](#valuesbucket) | Yes| Rows of data to update in the RDB store. The key-value pair is associated with the column name in the target table.| +| values | [ValuesBucket](#valuesbucket) | Yes| Data to update. The key-value pair is associated with the column name in the target table.| | predicates | [RdbPredicates](#rdbpredicates) | Yes| Update conditions specified by the **RdbPredicates** object.| **Return value** @@ -1187,7 +1189,7 @@ promise.then(async (ret) => { ### update9+ update(table: string, values: ValuesBucket, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>):void -Updates data based on the specified **DataSharePredicates** object. This API uses an asynchronous callback to return the result. +Updates data in the RDB store based on the specified **DataSharePredicates** object. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core @@ -1222,7 +1224,7 @@ rdbStore.update("EMPLOYEE", valueBucket, predicates, function (err, ret) { update(table: string, values: ValuesBucket, predicates: dataSharePredicates.DataSharePredicates):Promise<number> -Updates data based on the specified **DataSharePredicates** object. This API uses a promise to return the result. +Updates data in the RDB store based on the specified **DataSharePredicates** object. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core @@ -1520,7 +1522,7 @@ Queries data from the RDB store of a remote device based on specified conditions | -------- | -------- | -------- | -------- | | device | string | Yes| Network ID of the remote device.| | table | string | Yes| Name of the target table.| -| predicates | [RdbPredicates](#rdbpredicates) | Yes| Conditions for querying data.| +| predicates | [RdbPredicates](#rdbpredicates) | Yes| Query conditions specified by the **RdbPredicates** object.| | columns | Array<string> | Yes| Columns to query. If this parameter is not specified, the query applies to all columns.| | callback | AsyncCallback<[ResultSet](js-apis-data-resultset.md#resultset)> | Yes| Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.| @@ -1553,7 +1555,7 @@ Queries data from the RDB store of a remote device based on specified conditions | -------- | -------- | -------- | -------- | | device | string | Yes| Network ID of the remote device.| | table | string | Yes| Name of the target table.| -| predicates | [RdbPredicates](#rdbpredicates) | Yes| Conditions for querying data.| +| predicates | [RdbPredicates](#rdbpredicates) | Yes| Query conditions specified by the **RdbPredicates** object.| | columns | Array<string> | No| Columns to query. If this parameter is not specified, the query applies to all columns.| **Return value** @@ -1580,7 +1582,7 @@ promise.then((resultSet) => { querySql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<ResultSet>):void -Queries data using the specified SQL statement. This API uses an asynchronous callback to return the result. +Queries data in the RDB store using the specified SQL statement. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core @@ -1588,7 +1590,7 @@ Queries data using the specified SQL statement. This API uses an asynchronous ca | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | sql | string | Yes| SQL statement to run.| -| bindArgs | Array<[ValueType](#valuetype)> | Yes| Values of the parameters in the SQL statement.| +| bindArgs | Array<[ValueType](#valuetype)> | Yes| Arguments in the SQL statement.| | callback | AsyncCallback<[ResultSet](js-apis-data-resultset.md)> | Yes| Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.| **Example** @@ -1608,7 +1610,7 @@ rdbStore.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = ?", querySql(sql: string, bindArgs?: Array<ValueType>):Promise<ResultSet> -Queries data using the specified SQL statement. This API uses a promise to return the result. +Queries data in the RDB store using the specified SQL statement. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core @@ -1616,7 +1618,7 @@ Queries data using the specified SQL statement. This API uses a promise to retur | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | sql | string | Yes| SQL statement to run.| -| bindArgs | Array<[ValueType](#valuetype)> | No| Values of the parameters in the SQL statement.| +| bindArgs | Array<[ValueType](#valuetype)> | No| Arguments in the SQL statement.| **Return value** | Type| Description| @@ -1648,7 +1650,7 @@ Executes an SQL statement that contains specified arguments but returns no value | -------- | -------- | -------- | -------- | | sql | string | Yes| SQL statement to run.| | bindArgs | Array<[ValueType](#valuetype)> | Yes| Arguments in the SQL statement.| -| callback | AsyncCallback<void> | Yes| Callback that returns no value.| +| callback | AsyncCallback<void> | Yes| Callback invoked to return the result.| **Example** ```js @@ -1658,7 +1660,7 @@ rdbStore.executeSql(SQL_CREATE_TABLE, null, function(err) { console.info("Failed to execute SQL, err: " + err) return } - console.info('Create table done.') + console.info('Created table successfully.') }) ``` @@ -1680,14 +1682,14 @@ Executes an SQL statement that contains specified arguments but returns no value **Return value** | Type| Description| | -------- | -------- | -| Promise<void> | Promise that returns no value.| +| Promise<void> | Promise used to return the result.| **Example** ```js const SQL_CREATE_TABLE = "CREATE TABLE IF NOT EXISTS EMPLOYEE (ID INTEGER PRIMARY KEY AUTOINCREMENT, NAME TEXT NOT NULL, AGE INTEGER, SALARY REAL, CODES BLOB)" let promise = rdbStore.executeSql(SQL_CREATE_TABLE) promise.then(() => { - console.info('Create table done.') + console.info('Created table successfully.') }).catch((err) => { console.info("Failed to execute SQL, err: " + err) }) @@ -1785,7 +1787,7 @@ rdbStore.backup("dbBackup.db", function(err) { console.info('Failed to back up data, err: ' + err) return } - console.info('Backup successful.') + console.info('Backed up data successfully.') }) ``` @@ -1811,7 +1813,7 @@ Backs up an RDB store. This API uses a promise to return the result. ```js let promiseBackup = rdbStore.backup("dbBackup.db") promiseBackup.then(()=>{ - console.info('Backup successful.') + console.info('Backed up data successfully.') }).catch((err)=>{ console.info('Failed to back up data, err: ' + err) }) @@ -1838,7 +1840,7 @@ rdbStore.restore("dbBackup.db", function(err) { console.info('Failed to restore data, err: ' + err) return } - console.info('Restore successful.') + console.info('Restored data successfully.') }) ``` @@ -1864,7 +1866,7 @@ Restores an RDB store from a backup file. This API uses a promise to return the ```js let promiseRestore = rdbStore.restore("dbBackup.db") promiseRestore.then(()=>{ - console.info('Restore successful.') + console.info('Restored data successfully.') }).catch((err)=>{ console.info('Failed to restore data, err: ' + err) }) @@ -1924,7 +1926,7 @@ let promise = rdbStore.setDistributedTables(["EMPLOYEE"]) promise.then(() => { console.info("Set distributed tables successfully.") }).catch((err) => { - console.info("Failed to set distributed tables, err: " + err) + console.info('Failed to set distributed tables, err: ' + err) }) ``` @@ -1932,7 +1934,7 @@ promise.then(() => { obtainDistributedTableName(device: string, table: string, callback: AsyncCallback<string>): void -Obtains the distributed table name for a remote device based on the local table name. The distributed table name is required when the RDB store of a remote device is queried. This API uses an asynchronous callback to return the result. +Obtains the distributed table name for a remote device based on the local table name. This API uses an asynchronous callback to return the result. The distributed table name is required when the RDB store of a remote device is queried. **Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC @@ -1961,7 +1963,7 @@ rdbStore.obtainDistributedTableName("12345678abcde", "EMPLOYEE", function (err, obtainDistributedTableName(device: string, table: string): Promise<string> -Obtains the distributed table name for a remote device based on the local table name. The distributed table name is required when the RDB store of a remote device is queried. This API uses a promise to return the result. +Obtains the distributed table name for a remote device based on the local table name. This API uses a promise to return the result. The distributed table name is required when the RDB store of a remote device is queried. **Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC @@ -2003,7 +2005,7 @@ Synchronizes data between devices. This API uses an asynchronous callback to ret | -------- | -------- | -------- | -------- | | mode | [SyncMode](#syncmode8) | Yes| Data synchronization mode. The value can be **push** or **pull**.| | predicates | [RdbPredicates](#rdbpredicates) | Yes| **RdbPredicates** object that specifies the data and devices to synchronize.| -| callback | AsyncCallback<Array<[string, number]>> | Yes| Callback invoked to send the synchronization result to the caller.
**string** indicates the device ID.
**number** indicates the synchronization status of each device. The value **0** indicates a successful synchronization. Other values indicate a synchronization failure. | +| callback | AsyncCallback<Array<[string, number]>> | Yes| Callback invoked to send the synchronization result to the caller.
**string** indicates the device ID.
**number** indicates the synchronization status of that device. The value **0** indicates a successful synchronization. Other values indicate a synchronization failure. | **Example** ```js @@ -2042,7 +2044,7 @@ Synchronizes data between devices. This API uses a promise to return the result. | Type| Description| | -------- | -------- | -| Promise<Array<[string, number]>> | Promise used to return the synchronization result to the caller.
**string** indicates the device ID.
**number** indicates the synchronization status of each device. The value **0** indicates a successful synchronization. Other values indicate a synchronization failure. | +| Promise<Array<[string, number]>> | Promise used to return the synchronization result to the caller.
**string** indicates the device ID.
**number** indicates the synchronization status of that device. The value **0** indicates a successful synchronization. Other values indicate a synchronization failure. | **Example** ```js diff --git a/en/application-dev/reference/apis/js-apis-data-storage.md b/en/application-dev/reference/apis/js-apis-data-storage.md index 45465710a587c51fea60e7c59f2b804c80888043..cd1535b43bfe4e5d13a6460b066a082e31db8020 100644 --- a/en/application-dev/reference/apis/js-apis-data-storage.md +++ b/en/application-dev/reference/apis/js-apis-data-storage.md @@ -3,7 +3,7 @@ Lightweight storage provides applications with data processing capability and allows applications to perform lightweight data storage and query. Data is stored in key-value (KV) pairs. Keys are of the string type, and values can be of the number, string, or Boolean type. -> **NOTE**
+> **NOTE** > > - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. > @@ -20,10 +20,10 @@ import data_storage from '@ohos.data.storage'; **System capability**: SystemCapability.DistributedDataManager.Preferences.Core -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| MAX_KEY_LENGTH | string | Yes| No| Maximum length of a key. It must be less than 80 bytes.| -| MAX_VALUE_LENGTH | string | Yes| No| Maximum length of a value. It must be less than 8192 bytes.| +| Name | Type | Readable | Writable | Description | +| ---------------- | ------ | -------- | -------- | ----------------------------------------------------------- | +| MAX_KEY_LENGTH | string | Yes | No | Maximum length of a key. It must be less than 80 bytes. | +| MAX_VALUE_LENGTH | string | Yes | No | Maximum length of a value. It must be less than 8192 bytes. | ## data_storage.getStorageSync @@ -35,25 +35,33 @@ Reads the specified file and loads its data to the **Storage** instance for data **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | path | string | Yes| Path of the target file.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------------------ | +| path | string | Yes | Path of the target file. | **Return value** - | Type| Description| - | -------- | -------- | - | [Storage](#storage) | **Storage** instance used for data storage operations.| + +| Type | Description | +| ------------------- | ------------------------------------------------------ | +| [Storage](#storage) | **Storage** instance used for data storage operations. | **Example** - ```js - import data_storage from '@ohos.data.storage' - - let path = '/data/storage/el2/database' - let storage = data_storage.getStorageSync(path + '/mystore') - storage.putSync('startup', 'auto') - storage.flushSync() - - ``` + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +var path; +var context = featureAbility.getContext(); +context.getFilesDir().then((filePath) => { + path = filePath; + console.info("======================>getFilesDirPromsie====================>"); +}); + +let storage = data_storage.getStorageSync(path + '/mystore'); +storage.putSync('startup', 'auto'); +storage.flushSync(); +``` ## data_storage.getStorage @@ -65,25 +73,33 @@ Reads the specified file and loads its data to the **Storage** instance for data **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | path | string | Yes| Path of the target file.| - | callback | AsyncCallback<[Storage](#storage)> | Yes| Callback used to return the execution result.| + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | --------- | --------------------------------------------- | +| path | string | Yes | Path of the target file. | +| callback | AsyncCallback<[Storage](#storage)> | Yes | Callback used to return the execution result. | **Example** - ```js - import data_storage from '@ohos.data.storage' - - let path = '/data/storage/el2/database' - data_storage.getStorage(path + '/mystore', function (err, storage) { - if (err) { - console.info("Failed to get the storage. Path: " + path + '/mystore') - return; - } - storage.putSync('startup', 'auto') - storage.flushSync() - }) - ``` + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +var path; +var context = featureAbility.getContext(); +context.getFilesDir().then((filePath) => { + path = filePath; + console.info("======================>getFilesDirPromsie====================>"); +}); + +data_storage.getStorage(path + '/mystore', function (err, storage) { + if (err) { + console.info("Failed to get the storage. path: " + path + '/mystore'); + return; + } + storage.putSync('startup', 'auto'); + storage.flushSync(); +}) +``` ## data_storage.getStorage @@ -95,29 +111,37 @@ Reads the specified file and loads its data to the **Storage** instance for data **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | path | string | Yes| Path of the target file.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------------------ | +| path | string | Yes | Path of the target file. | **Return value** - | Type| Description| - | -------- | -------- | - | Promise<[Storage](#storage)> | Promise used to return the result.| + +| Type | Description | +| ---------------------------------- | ---------------------------------- | +| Promise<[Storage](#storage)> | Promise used to return the result. | **Example** - ```js - import data_storage from '@ohos.data.storage' - - let path = '/data/storage/el2/database' - - let getPromise = data_storage.getStorage(path + '/mystore') - getPromise.then((storage) => { - storage.putSync('startup', 'auto') - storage.flushSync() - }).catch((err) => { - console.info("Failed to get the storage. Path: " + path + '/mystore') - }) - ``` + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +var path; +var context = featureAbility.getContext(); +context.getFilesDir().then((filePath) => { + path = filePath; + console.info("======================>getFilesDirPromsie====================>"); +}); + +let getPromise = data_storage.getStorage(path + '/mystore'); +getPromise.then((storage) => { + storage.putSync('startup', 'auto'); + storage.flushSync(); +}).catch((err) => { + console.info("Failed to get the storage. path: " + path + '/mystore'); +}) +``` ## data_storage.deleteStorageSync @@ -129,15 +153,25 @@ Deletes the singleton **Storage** instance of a file from the memory, and delete **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | path | string | Yes| Path of the target file.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------------------ | +| path | string | Yes | Path of the target file. | **Example** - ```js - let path = '/data/storage/el2/database' - data_storage.deleteStorageSync(path + '/mystore') - ``` + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +var path; +var context = featureAbility.getContext(); +context.getFilesDir().then((filePath) => { + path = filePath; + console.info("======================>getFilesDirPromsie====================>"); +}); + +data_storage.deleteStorageSync(path + '/mystore'); +``` ## data_storage.deleteStorage @@ -149,22 +183,32 @@ Deletes the singleton **Storage** instance of a file from the memory, and delete **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | path | string | Yes| Path of the target file.| - | callback | AsyncCallback<void> | Yes| Callback that returns no value.| + +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | --------- | ------------------------------- | +| path | string | Yes | Path of the target file. | +| callback | AsyncCallback<void> | Yes | Callback that returns no value. | **Example** - ```js - let path = '/data/storage/el2/database' - data_storage.deleteStorage(path + '/mystore', function (err) { - if (err) { - console.info("Deleted failed with err: " + err) - return - } - console.info("Deleted successfully.") - }) - ``` + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +var path; +var context = featureAbility.getContext(); +context.getFilesDir().then((filePath) => { + path = filePath; + console.info("======================>getFilesDirPromsie====================>"); +}); + +data_storage.deleteStorage(path + '/mystore', function (err) { + if (err) { + console.info("Failed to delete the storage with err: " + err); + return; + } + console.info("Succeeded in deleting the storage."); +}) +``` ## data_storage.deleteStorage @@ -176,25 +220,35 @@ Deletes the singleton **Storage** instance of a file from the memory, and delete **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | path | string | Yes| Path of the target file.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------------------ | +| path | string | Yes | Path of the target file. | **Return value** - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ------------------------------ | +| Promise<void> | Promise that returns no value. | **Example** - ```js - let path = '/data/storage/el2/database' - let promisedelSt = data_storage.deleteStorage(path + '/mystore') - promisedelSt.then(() => { - console.info("Deleted successfully.") - }).catch((err) => { - console.info("Deleted failed with err: " + err) - }) - ``` + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +var path; +var context = featureAbility.getContext(); +context.getFilesDir().then((filePath) => { + path = filePath; + console.info("======================>getFilesDirPromsie====================>"); +}); + +let promisedelSt = data_storage.deleteStorage(path + '/mystore'); +promisedelSt.then(() => { + console.info("Succeeded in deleting the storage."); +}).catch((err) => { + console.info("Failed to delete the storage with err: " + err); +}) +``` ## data_storage.removeStorageFromCacheSync @@ -206,15 +260,25 @@ Removes the singleton **Storage** instance of a file from the cache. The removed **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | path | string | Yes| Path of the target file.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------------------ | +| path | string | Yes | Path of the target file. | **Example** - ```js - let path = '/data/storage/el2/database' - data_storage.removeStorageFromCacheSync(path + '/mystore') - ``` + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +var path; +var context = featureAbility.getContext(); +context.getFilesDir().then((filePath) => { + path = filePath; + console.info("======================>getFilesDirPromsie====================>"); +}); + +data_storage.removeStorageFromCacheSync(path + '/mystore'); +``` ## data_storage.removeStorageFromCache @@ -226,22 +290,32 @@ Removes the singleton **Storage** instance of a file from the cache. The removed **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | path | string | Yes| Path of the target file.| - | callback | AsyncCallback<void> | Yes| Callback that returns no value.| + +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | --------- | ------------------------------- | +| path | string | Yes | Path of the target file. | +| callback | AsyncCallback<void> | Yes | Callback that returns no value. | **Example** - ```js - let path = '/data/storage/el2/database' - data_storage.removeStorageFromCache(path + '/mystore', function (err) { - if (err) { - console.info("Removed storage from cache failed with err: " + err) - return - } - console.info("Removed storage from cache successfully.") - }) - ``` + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +var path; +var context = featureAbility.getContext(); +context.getFilesDir().then((filePath) => { + path = filePath; + console.info("======================>getFilesDirPromsie====================>"); +}); + +data_storage.removeStorageFromCache(path + '/mystore', function (err) { + if (err) { + console.info("Failed to remove storage from cache with err: " + err); + return; + } + console.info("Succeeded in removing storage from cache."); +}) +``` ## data_storage.removeStorageFromCache @@ -253,25 +327,36 @@ Removes the singleton **Storage** instance of a file from the cache. The removed **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | path | string | Yes| Path of the target file.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------------------ | +| path | string | Yes | Path of the target file. | **Return value** - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise that returns no value.| + +| Type | Description | +| ------------------- | ------------------------------ | +| Promise<void> | Promise that returns no value. | **Example** - ```js - let path = '/data/storage/el2/database' - let promiserevSt = data_storage.removeStorageFromCache(path + '/mystore') - promiserevSt.then(() => { - console.info("Removed storage from cache successfully.") - }).catch((err) => { - console.info("Removed storage from cache failed with err: " + err) - }) - ``` + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +var path; +var context = featureAbility.getContext(); +context.getFilesDir().then((filePath) => { + path = filePath; + console.info("======================>getFilesDirPromsie====================>"); +}); + +let promiserevSt = data_storage.removeStorageFromCache(path + '/mystore') +promiserevSt.then(() => { + console.info("Succeeded in removing storage from cache."); +}).catch((err) => { + console.info("Failed to remove storage from cache with err: " + err); +}) +``` ## Storage @@ -288,21 +373,24 @@ Obtains the value corresponding to a key. If the value is null or not in the def **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| - | defValue | [ValueType](#valuetype) | Yes| Default value to be returned if the value of the specified key does not exist. It can be a number, string, or Boolean value.| + +| Name | Type | Mandatory | Description | +| -------- | ----------------------- | --------- | ------------------------------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | +| defValue | [ValueType](#valuetype) | Yes | Default value to be returned if the value of the specified key does not exist. It can be a number, string, or Boolean value. | **Return value** - | Type| Description| - | -------- | -------- | - | ValueType | Value corresponding to the specified key. If the value is null or not in the default value format, the default value is returned.| + +| Type | Description | +| --------- | ------------------------------------------------------------ | +| ValueType | Value corresponding to the specified key. If the value is null or not in the default value format, the default value is returned. | **Example** - ```js - let value = storage.getSync('startup', 'default') - console.info("The value of startup is " + value) - ``` + +```js +let value = storage.getSync('startup', 'default'); +console.info("The value of startup is " + value); +``` ### get @@ -314,22 +402,24 @@ Obtains the value corresponding to a key. If the value is null or not in the def **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| - | defValue | [ValueType](#valuetype) | Yes| Default value to be returned. It can be a number, string, or Boolean value.| - | callback | AsyncCallback<ValueType> | Yes| Callback used to return the execution result.| + +| Name | Type | Mandatory | Description | +| -------- | ------------------------------ | --------- | ------------------------------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | +| defValue | [ValueType](#valuetype) | Yes | Default value to be returned. It can be a number, string, or Boolean value. | +| callback | AsyncCallback<ValueType> | Yes | Callback used to return the execution result. | **Example** - ```js - storage.get('startup', 'default', function(err, value) { - if (err) { - console.info("Get the value of startup failed with err: " + err) - return + +```js +storage.get('startup', 'default', function(err, value) { + if (err) { + console.info("Failed to get the value of startup with err: " + err); + return; } - console.info("The value of startup is " + value) - }) - ``` + console.info("The value of startup is " + value); +}) +``` ### get @@ -342,25 +432,26 @@ Obtains the value corresponding to a key. If the value is null or not in the def **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| key | string | Yes| Key of the data. It cannot be empty.| -| defValue | [ValueType](#valuetype) | Yes| Default value to be returned. It can be a number, string, or Boolean value.| +| Name | Type | Mandatory | Description | +| -------- | ----------------------- | --------- | ------------------------------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | +| defValue | [ValueType](#valuetype) | Yes | Default value to be returned. It can be a number, string, or Boolean value. | **Return value** - | Type| Description| - | -------- | -------- | - | Promise<ValueType> | Promise used to return the result.| + +| Type | Description | +| ------------------------ | ---------------------------------- | +| Promise<ValueType> | Promise used to return the result. | **Example** - ```js - let promiseget = storage.get('startup', 'default') - promiseget.then((value) => { - console.info("The value of startup is " + value) - }).catch((err) => { - console.info("Get the value of startup failed with err: " + err) - }) - ``` +```js +let promiseget = storage.get('startup', 'default'); +promiseget.then((value) => { + console.info("The value of startup is " + value) +}).catch((err) => { + console.info("Failed to get the value of startup with err: " + err); +}) +``` ### putSync @@ -372,15 +463,17 @@ Obtains the **Storage** instance corresponding to the specified file, writes dat **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| - | value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, string, or Boolean value.| + +| Name | Type | Mandatory | Description | +| ----- | ----------------------- | --------- | ------------------------------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | +| value | [ValueType](#valuetype) | Yes | New value to store. It can be a number, string, or Boolean value. | **Example** - ```js - storage.putSync('startup', 'auto') - ``` + +```js +storage.putSync('startup', 'auto') +``` ### put @@ -392,22 +485,24 @@ Obtains the **Storage** instance corresponding to the specified file, writes dat **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| - | value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, string, or Boolean value.| - | callback | AsyncCallback<void> | Yes| Callback that returns no value.| + +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | --------- | ------------------------------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | +| value | [ValueType](#valuetype) | Yes | New value to store. It can be a number, string, or Boolean value. | +| callback | AsyncCallback<void> | Yes | Callback that returns no value. | **Example** - ```js - storage.put('startup', 'auto', function (err) { - if (err) { - console.info("Put the value of startup failed with err: " + err) - return - } - console.info("Put the value of startup successfully.") - }) - ``` + +```js +storage.put('startup', 'auto', function (err) { + if (err) { + console.info("Failed to put the value of startup with err: " + err); + return; + } + console.info("Succeeded in putting the value of startup."); +}) +``` ### put @@ -419,25 +514,27 @@ Obtains the **Storage** instance corresponding to the specified file, writes dat **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| - | value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, string, or Boolean value.| + +| Name | Type | Mandatory | Description | +| ----- | ----------------------- | --------- | ------------------------------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | +| value | [ValueType](#valuetype) | Yes | New value to store. It can be a number, string, or Boolean value. | **Return value** - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise that returns no value.| + +| Type | Description | +| ------------------- | ------------------------------ | +| Promise<void> | Promise that returns no value. | **Example** - ```js - let promiseput = storage.put('startup', 'auto') - promiseput.then(() => { - console.info("Put the value of startup successfully.") - }).catch((err) => { - console.info("Put the value of startup failed with err: " + err) - }) - ``` +```js +let promiseput = storage.put('startup', 'auto'); +promiseput.then(() => { + console.info("Succeeded in putting the value of startup."); +}).catch((err) => { + console.info("Failed to put the value of startup with err: " + err); +}) +``` ### hasSync @@ -449,22 +546,25 @@ Checks whether the storage object contains data with a given key. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | **Return value** - | Type| Description| - | -------- | -------- | - | boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise.| + +| Type | Description | +| ------- | ------------------------------------------------------------ | +| boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise. | **Example** - ```js - let isExist = storage.hasSync('startup') - if (isExist) { - console.info("The key of startup is contained.") - } - ``` + +```js +let isExist = storage.hasSync('startup'); +if (isExist) { + console.info("The key of startup is contained."); +} +``` ### has @@ -476,28 +576,31 @@ Checks whether the storage object contains data with a given key. This API uses **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| - | callback | AsyncCallback<boolean> | Yes| Callback used to return the execution result.| + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------- | --------- | --------------------------------------------- | +| key | string | Yes | Key of the data. It cannot be empty. | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the execution result. | **Return value** - | Type| Description| - | -------- | -------- | - | boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise.| + +| Type | Description | +| ------- | ------------------------------------------------------------ | +| boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise. | **Example** - ```js - storage.has('startup', function (err, isExist) { - if (err) { - console.info("Check the key of startup failed with err: " + err) - return - } - if (isExist) { - console.info("The key of startup is contained.") - } - }) - ``` + +```js +storage.has('startup', function (err, isExist) { + if (err) { + console.info("Failed to check the key of startup with err: " + err); + return; + } + if (isExist) { + console.info("The key of startup is contained."); + } +}) +``` ### has @@ -509,26 +612,29 @@ Checks whether the storage object contains data with a given key. This API uses **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | **Return value** - | Type| Description| - | -------- | -------- | - | Promise<boolean> | Promise used to return the result.| + +| Type | Description | +| ---------------------- | ---------------------------------- | +| Promise<boolean> | Promise used to return the result. | **Example** - ```js - let promisehas = storage.has('startup') - promisehas.then((isExist) => { - if (isExist) { - console.info("The key of startup is contained.") - } - }).catch((err) => { - console.info("Check the key of startup failed with err: " + err) - }) - ``` + +```js +let promisehas = storage.has('startup') +promisehas.then((isExist) => { + if (isExist) { + console.info("The key of startup is contained."); + } +}).catch((err) => { + console.info("Failed to check the key of startup with err: " + err); +}) +``` ### deleteSync @@ -540,14 +646,16 @@ Deletes data with the specified key from this storage object. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | **Example** - ```js - storage.deleteSync('startup') - ``` + +```js +storage.deleteSync('startup') +``` ### delete @@ -559,21 +667,23 @@ Deletes data with the specified key from this storage object. This API uses an a **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| - | callback | AsyncCallback<void> | Yes| Callback that returns no value.| + +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | --------- | ------------------------------------ | +| key | string | Yes | Key of the data. It cannot be empty. | +| callback | AsyncCallback<void> | Yes | Callback that returns no value. | **Example** - ```js - storage.delete('startup', function (err) { - if (err) { - console.info("Delete startup key failed with err: " + err) - return - } - console.info("Deleted startup key successfully.") - }) - ``` + +```js +storage.delete('startup', function (err) { + if (err) { + console.info("Failed to delete startup key failed err: " + err); + return; + } + console.info("Succeeded in deleting startup key."); +}) +``` ### delete @@ -585,24 +695,27 @@ Deletes data with the specified key from this storage object. This API uses a pr **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data.| + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ---------------- | +| key | string | Yes | Key of the data. | **Return value** - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise that returns no value.| + +| Type | Description | +| ------------------- | ------------------------------ | +| Promise<void> | Promise that returns no value. | **Example** - ```js - let promisedel = storage.delete('startup') - promisedel.then(() => { - console.info("Deleted startup key successfully.") - }).catch((err) => { - console.info("Delete startup key failed with err: " + err) - }) - ``` + +```js +let promisedel = storage.delete('startup') +promisedel.then(() => { + console.info("Succeeded in deleting startup key."); +}).catch((err) => { + console.info("Failed to delete startup key failed err: " + err); +}) +``` ### flushSync @@ -614,9 +727,10 @@ Saves the modification of this object to the **Storage** instance and synchroniz **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Example** - ```js - storage.flushSync() - ``` + +```js +storage.flushSync() +``` ### flush @@ -628,20 +742,22 @@ Saves the modification of this object to the **Storage** instance and synchroniz **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<void> | Yes| Callback that returns no value.| + +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | --------- | ------------------------------- | +| callback | AsyncCallback<void> | Yes | Callback that returns no value. | **Example** - ```js - storage.flush(function (err) { - if (err) { - console.info("Flush to file failed with err: " + err) - return - } - console.info("Flushed to file successfully.") - }) - ``` + +```js +storage.flush(function (err) { + if (err) { + console.info("Failed to flush to file with err: " + err); + return; + } + console.info("Succeeded in flushing to file."); +}) +``` ### flush @@ -653,19 +769,21 @@ Saves the modification of this object to the **Storage** instance and synchroniz **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Return value** - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise that returns no value.| + +| Type | Description | +| ------------------- | ------------------------------ | +| Promise<void> | Promise that returns no value. | **Example** - ```js - let promiseflush = storage.flush() - promiseflush.then(() => { - console.info("Flushed to file successfully.") - }).catch((err) => { - console.info("Flush to file failed with err: " + err) - }) - ``` + +```js +let promiseflush = storage.flush(); +promiseflush.then(() => { + console.info("Succeeded in flushing to file."); +}).catch((err) => { + console.info("Failed to flush to file with err: " + err); +}) +``` ### clearSync @@ -677,9 +795,10 @@ Clears this **Storage** object. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Example** - ```js - storage.clearSync() - ``` + +```js +storage.clearSync() +``` ### clear @@ -691,20 +810,22 @@ Clears this **Storage** object. This API uses an asynchronous callback to return **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<void> | Yes| Callback that returns no value.| + +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | --------- | ------------------------------- | +| callback | AsyncCallback<void> | Yes | Callback that returns no value. | **Example** - ```js - storage.clear(function (err) { - if (err) { - console.info("Clear to file failed with err: " + err) - return - } - console.info("Cleared to file successfully.") - }) - ``` + +```js +storage.clear(function (err) { + if (err) { + console.info("Failed to clear the storage with err: " + err); + return; + } + console.info("Succeeded in clearing the storage."); +}) +``` ### clear @@ -716,19 +837,21 @@ Clears this **Storage** object. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Return value** - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise that returns no value.| + +| Type | Description | +| ------------------- | ------------------------------ | +| Promise<void> | Promise that returns no value. | **Example** - ```js - let promiseclear = storage.clear() - promiseclear.then(() => { - console.info("Cleared to file successfully.") - }).catch((err) => { - console.info("Clear to file failed with err: " + err) - }) - ``` + +```js +let promiseclear = storage.clear(); +promiseclear.then(() => { + console.info("Succeeded in clearing the storage."); +}).catch((err) => { + console.info("Failed to clear the storage with err: " + err); +}) +``` ### on('change') @@ -740,20 +863,22 @@ Subscribes to data changes. The **StorageObserver** needs to be implemented. Whe **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Description| - | -------- | -------- | -------- | - | type | string | Event type. The value **change** indicates data change events.| - | callback | Callback<[StorageObserver](#storageobserver)> | Callback used to return data changes.| + +| Name | Type | Description | +| -------- | --------------------------------------------------- | ------------------------------------------------------------ | +| type | string | Event type. The value **change** indicates data change events. | +| callback | Callback<[StorageObserver](#storageobserver)> | Callback used to return data changes. | **Example** - ```js - var observer = function (key) { - console.info("The key of " + key + " changed.") - } - storage.on('change', observer) - storage.putSync('startup', 'auto') - storage.flushSync() // observer will be called. - ``` + +```js +var observer = function (key) { + console.info("The key of " + key + " changed."); +} +storage.on('change', observer); +storage.putSync('startup', 'auto'); +storage.flushSync(); // observer will be called. +``` ### off('change') @@ -765,27 +890,29 @@ Unsubscribes from data changes. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** - | Name| Type| Description| - | -------- | -------- | -------- | - | type | string | Event type. The value **change** indicates data change events.| - | callback | Callback<[StorageObserver](#storageobserver)> | Callback used to return data changes.| + +| Name | Type | Description | +| -------- | --------------------------------------------------- | ------------------------------------------------------------ | +| type | string | Event type. The value **change** indicates data change events. | +| callback | Callback<[StorageObserver](#storageobserver)> | Callback used to return data changes. | **Example** - ```js - var observer = function (key) { - console.info("The key of " + key + " changed.") - } - storage.off('change', observer) - ``` + +```js +var observer = function (key) { + console.info("The key of " + key + " changed."); +} +storage.off('change', observer); +``` ## StorageObserver **System capability**: SystemCapability.DistributedDataManager.Preferences.Core -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| key | string | No| Data changed.| +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ------------- | +| key | string | No | Data changed. | ## ValueType @@ -793,8 +920,8 @@ Enumerates the value types. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core -| Type | Description | -| ------- | -------------------- | -| number | The value is a number. | -| string | The value is a string. | -| boolean | The value is of Boolean type.| +| Type | Description | +| ------- | ----------------------------- | +| number | The value is a number. | +| string | The value is a string. | +| boolean | The value is of Boolean type. | \ No newline at end of file diff --git a/en/application-dev/reference/apis/js-apis-dataAbilityHelper.md b/en/application-dev/reference/apis/js-apis-dataAbilityHelper.md index 52af89ae7faa9fd20a28a62f959f4a3f39340ced..1d10f56aeb69e13d2f329bfc18f56127667ef930 100644 --- a/en/application-dev/reference/apis/js-apis-dataAbilityHelper.md +++ b/en/application-dev/reference/apis/js-apis-dataAbilityHelper.md @@ -119,7 +119,7 @@ helper.on( off(type: 'dataChange', uri: string, callback?: AsyncCallback\): void -Unregisters the observer used to observe data specified by a given URI. This API uses an asynchronous callback to return the result. +Deregisters the observer used to observe data specified by a given URI. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.FAModel @@ -647,7 +647,7 @@ Deletes one or more data records from the database. This API uses an asynchronou ```js import featureAbility from '@ohos.ability.featureAbility' -import ohos_data_ability from '@ohos.data.dataability' +import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" ); @@ -662,7 +662,7 @@ DAHelper.delete( ## DataAbilityHelper.delete -delete(uri: string, predicates: dataAbility.DataAbilityPredicates): Promise\ +delete(uri: string, predicates?: dataAbility.DataAbilityPredicates): Promise\; Deletes one or more data records from the database. This API uses a promise to return the result. @@ -685,7 +685,7 @@ Deletes one or more data records from the database. This API uses a promise to r ```js import featureAbility from '@ohos.ability.featureAbility' -import ohos_data_ability from '@ohos.data.dataability' +import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" ); @@ -719,7 +719,7 @@ Updates data records in the database. This API uses an asynchronous callback to ```js import featureAbility from '@ohos.ability.featureAbility' -import ohos_data_ability from '@ohos.data.dataability' +import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" ); @@ -741,7 +741,7 @@ DAHelper.update( ## DataAbilityHelper.update -update(uri: string, valuesBucket: rdb.ValuesBucket, predicates: dataAbility.DataAbilityPredicates): Promise\ +update(uri: string, valuesBucket: rdb.ValuesBucket, predicates?: dataAbility.DataAbilityPredicates): Promise\; Updates data records in the database. This API uses a promise to return the result. @@ -765,7 +765,7 @@ Updates data records in the database. This API uses a promise to return the resu ```js import featureAbility from '@ohos.ability.featureAbility' -import ohos_data_ability from '@ohos.data.dataability' +import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" ); @@ -806,7 +806,7 @@ Queries data in the database. This API uses an asynchronous callback to return t ```js import featureAbility from '@ohos.ability.featureAbility' -import ohos_data_ability from '@ohos.data.dataability' +import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" ); @@ -825,7 +825,7 @@ DAHelper.query( ## DataAbilityHelper.query -query(uri: string, columns: Array\, predicates: dataAbility.DataAbilityPredicates): Promise\ +query(uri: string, columns?: Array\, predicates?: dataAbility.DataAbilityPredicates): Promise\; Queries data in the database. This API uses a promise to return the result. @@ -849,7 +849,7 @@ Queries data in the database. This API uses a promise to return the result. ```js import featureAbility from '@ohos.ability.featureAbility' -import ohos_data_ability from '@ohos.data.dataability' +import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" ); @@ -876,7 +876,7 @@ Calls the extended API of the Data ability. This API uses a promise to return th | Name | Type | Mandatory| Description | | ---------- | --------------------------------- | ---- | ------------------------------------------------ | -| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx" | +| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". | | method | string | Yes | Name of the API to call. | | arg | string | Yes |Parameter to pass. | | extras | [PacMap](#pacmap) | Yes | Key-value pair parameter. | @@ -912,7 +912,7 @@ Calls the extended API of the Data ability. This API uses an asynchronous callba | Name | Type | Mandatory| Description | | ---------- | --------------------------------- | ---- | ------------------------------------------------ | -| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx" | +| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". | | method | string | Yes | Name of the API to call. | | arg | string | Yes |Parameter to pass. | | extras | [PacMap](#pacmap) | Yes | Key-value pair parameter. | @@ -932,8 +932,107 @@ dataAbilityHelper.call("dataability:///com.example.jsapidemo.UserDataAbility", " console.info('Operation succeeded: ' + data); }); ``` + +## DataAbilityHelper.executeBatch + +executeBatch(uri: string, operations: Array\, callback: AsyncCallback\>): void; + +Operates data in the database. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | --------------------------------- | ---- | ------------------------------------------------ | +| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx".| +| operations | Array\<[DataAbilityOperation](#dataabilityoperation)> | Yes | A list of data operations on the database. | +| callback | AsyncCallback\> | Yes |Callback used to return the result of each operation in the **DataAbilityResult** array. | + +**Example** + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +// Select the operations to be performed on the database according to the DataAbilityOperation array. +let op=new Array(); +let dataAbilityHelper = featureAbility.acquireDataAbilityHelper("dataability:///com.example.jsapidemo.UserDataAbility"); +dataAbilityHelper.executeBatch("dataability:///com.example.jsapidemo.UserDataAbility", op, (err, data) => { + if (err) { + console.error('Operation failed. Cause: ' + err); + return; + } + console.info('Operation succeeded: ' + data); +}); +``` + +## DataAbilityHelper.executeBatch + +executeBatch(uri: string, operations: Array\): Promise\>; + +Operates data in the database. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | -------------------------------| ---- | ------------------------------------------------ | +| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx".| +| operations | Array\<[DataAbilityOperation](#dataabilityoperation)> | Yes | A list of data operations on the database. | + +**Return value** + +| Type| Description| +|------ | ------- | +|Promise\> | Promise used to return the result of each operation in the **DataAbilityResult** array.| + +**Example** + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +// Select the operations to be performed on the database according to the DataAbilityOperation array. +let op=new Array(); +let dataAbilityHelper = featureAbility.acquireDataAbilityHelper("dataability:///com.example.jsapidemo.UserDataAbility"); +dataAbilityHelper.executeBatch("dataability:///com.example.jsapidemo.UserDataAbility",op ).then((data) => { + console.info('Operation succeeded: ' + data); +}).catch((error) => { + console.error('Operation failed. Cause: ' + error); +}); + +``` + ## PacMap +[key: string]: number | string | boolean | Array\ | null; + +**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel + | Name| Type| Mandatory| Description| | ------ | ------ | ------ | ------ | | [key: string] | number \| string \| boolean \| Array\ \| null | Yes| Data stored in key-value pairs.| + +## DataAbilityOperation + +**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel + +| Name | Type | Readable | Writable | Mandatory| Description | +| -------- | -------- | -------- | -------- | --------| -------- | +| uri | string | Yes | No | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". | +| type | featureAbility.DataAbilityOperationType | Yes | No | Yes | Operation type. | +| valuesBucket? | rdb.ValuesBucket | Yes | No | No | Data value to set. | +| valueBackReferences? | rdb.ValuesBucket | Yes | No | No | **ValuesBucket** object that contains a set of key-value pairs. | +| predicates? | dataAbility.DataAbilityPredicates | Yes | No | No | Predicates to set. If no predicate is set, all data records are displayed. | +| predicatesBackReferences? | Map\ | Yes | No | No | Back references of the predicates. | +| interrupted? | boolean | Yes | No | No | Whether batch operations can be interrupted. | +| expectedCount? | number | Yes | No | No | Expected number of rows to be updated or deleted. | + +## DataAbilityResult + +**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel + +| Name | Type | Readable | Writable | Mandatory | Description | +| -------- | -------- | -------- | -------- | -------- | -------- | +| uri? | string | Yes | No | No | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". | +| count? | number | Yes | No | No | Number of rows affected by the operation. | diff --git a/en/application-dev/reference/apis/js-apis-dispatchInfo.md b/en/application-dev/reference/apis/js-apis-dispatchInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..5f476f34bd9ed8c08fc0e033243c1f4fb55ca23c --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-dispatchInfo.md @@ -0,0 +1,16 @@ +# DispatchInfo + +The **DispatchInfo** module provides dispatch information. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## DispatchInfo + +**System capability**: SystemCapability.BundleManager.BundleFramework + +| Name | Type | Readable| Writable| Description | +| ----------- | ------ | ---- | ---- | ------------------------ | +| verison | string | Yes | No | Version of the API to dispatch.| +| dispatchAPI | string | Yes | No | API to dispatch. | diff --git a/en/application-dev/reference/apis/js-apis-emitter.md b/en/application-dev/reference/apis/js-apis-emitter.md index fa54f6739279745a1f7538fd32abf0fca6402711..6398b87f685e5f91c59dacb1da97b4ad993e5afa 100644 --- a/en/application-dev/reference/apis/js-apis-emitter.md +++ b/en/application-dev/reference/apis/js-apis-emitter.md @@ -1,6 +1,9 @@ # Emitter -> **NOTE**
+The **Emitter** module provides APIs for sending and processing in-process events, including the APIs for processing events that are subscribed to in persistent or one-shot manner, unsubscribing from events, and emitting events to the event queue. + +> **NOTE** +> > The initial APIs of this module are supported since API version 7. ## Modules to Import @@ -17,12 +20,14 @@ None Enumerates the event emit priority levels. - | Name | Value | Description | - | --------- | ---- | ------------------------------------------------- | - | IMMEDIATE | 0 | The event will be emitted immediately.
**System capability**: SystemCapability.Notification.Emitter | - | HIGH | 1 | The event will be emitted before low-priority events.
**System capability**: SystemCapability.Notification.Emitter | - | LOW | 2 | The event will be emitted before idle-priority events. By default, an event is in LOW priority.
**System capability**: SystemCapability.Notification.Emitter | - | IDLE | 3 | The event will be emitted after all the other events.
**System capability**: SystemCapability.Notification.Emitter | +**System capability**: SystemCapability.Notification.Emitter + +| Name | Value | Description | +| --------- | ---- | ------------------------------------------------- | +| IMMEDIATE | 0 | The event will be emitted immediately. | +| HIGH | 1 | The event will be emitted before low-priority events. | +| LOW | 2 | The event will be emitted before idle-priority events. By default, an event is in LOW priority. | +| IDLE | 3 | The event will be emitted after all the other events. | ## emitter.on @@ -34,10 +39,10 @@ Subscribes to an event in persistent manner. This API uses a callback to return **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ----------------------------------- | ---- | ------------------------ | - | event | [InnerEvent](#innerevent) | Yes | Event to subscribe to in persistent manner. | - | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback used to return the event. | +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------- | ---- | ------------------------ | +| event | [InnerEvent](#innerevent) | Yes | Event to subscribe to in persistent manner. | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback used to return the event.| **Example** @@ -61,10 +66,10 @@ Subscribes to an event in one-shot manner and unsubscribes from it after the eve **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ----------------------------------- | ---- | ------------------------ | - | event | [InnerEvent](#innerevent) | Yes | Event to subscribe to in one-shot manner. | - | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback used to return the event. | +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------- | ---- | ------------------------ | +| event | [InnerEvent](#innerevent) | Yes | Event to subscribe to in one-shot manner. | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback used to return the event.| **Example** @@ -88,9 +93,9 @@ Unsubscribes from an event. **Parameters** - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ------ | - | eventId | number | Yes | Event ID. | +| Name | Type | Mandatory| Description | +| ------- | ------ | ---- | ------ | +| eventId | number | Yes | Event ID.| **Example** @@ -108,10 +113,10 @@ Emits an event to the event queue. **Parameters** - | Name | Type | Mandatory | Description | - | ------ | ------------------------- | ---- | -------------- | - | event | [InnerEvent](#innerevent) | Yes | Event to emit. | - | data | [EventData](#eventdata) | No | Data carried by the event. | +| Name| Type | Mandatory| Description | +| ------ | ------------------------- | ---- | -------------- | +| event | [InnerEvent](#innerevent) | Yes | Event to emit. | +| data | [EventData](#eventdata) | No | Data carried by the event.| **Example** @@ -130,17 +135,21 @@ emitter.emit(innerEvent, eventData); ## InnerEvent -Describes an intra-process event. +Describes an in-process event. - | Name | Type | Readable | Writable | Description | - | -------- | ------------------------------- | ---- | ---- | ---------------------------------- | - | eventId | number | Yes | Yes | Event ID, which is used to identify an event.
**System capability**: SystemCapability.Notification.Emitter | - | priority | [EventPriority](#eventpriority) | Yes | Yes | Emit priority of the event.
**System capability**: SystemCapability.Notification.Emitter | +**System capability**: SystemCapability.Notification.Emitter + +| Name | Type | Readable| Writable| Description | +| -------- | ------------------------------- | ---- | ---- | ---------------------------------- | +| eventId | number | Yes | Yes | Event ID, which is used to identify an event.| +| priority | [EventPriority](#eventpriority) | Yes | Yes | Emit priority of the event. | ## EventData Describes the data passed in the event. - | Name | Type | Readable | Writable | Description | - | ---- | ------------------ | ---- | ---- | -------------- | - | data | [key: string]: any | Yes | Yes | Data carried by the event. The data type can be String, Integer, or Boolean.
**System capability**: SystemCapability.Notification.Emitter | +**System capability**: SystemCapability.Notification.Emitter + +| Name| Type | Readable| Writable| Description | +| ---- | ------------------ | ---- | ---- | -------------- | +| data | [key: string]: any | Yes | Yes | Data carried by the event. The data type can be String, Integer, or Boolean.| diff --git a/en/application-dev/reference/apis/js-apis-errorManager.md b/en/application-dev/reference/apis/js-apis-errorManager.md new file mode 100644 index 0000000000000000000000000000000000000000..a06e1650bd6f3614a33c58dd092b55451d0a0db8 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-errorManager.md @@ -0,0 +1,139 @@ +# ErrorManager + +The **ErrorManager** module provides APIs for registering and deregistering error observers. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import +``` +import errorManager from '@ohos.application.errorManager' +``` + +## ErrorManager.registerErrorObserver + +registerErrorObserver(observer: ErrorObserver): number; + +Registers an error observer. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| observer | [ErrorObserver](#errorobserver) | No| Numeric code of the observer.| + +**Example** + +```js +var observer = { + onUnhandledException(errorMsg) { + console.log('onUnhandledException, errorMsg: ', errorMsg) + } +} +errorManager.registerErrorObserver(observer) + .then((data) => { + console.log('----------- registerErrorObserver success ----------', data); + }) + .catch((err) => { + console.log('----------- registerErrorObserver fail ----------', err); + }) + +``` + +## ErrorManager.unregisterErrorObserver + +unregisterErrorObserver(observerId: number, callback: AsyncCallback\): void; + +Deregisters an error observer. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| observerId | number | No| Numeric code of the observer.| +| callback | AsyncCallback\ | No| Callback used to return the result.| + +**Example** + +```js +var observerId = 100; + +function unregisterErrorObserverCallback(err) { + if (err) { + console.log('------------ unregisterErrorObserverCallback ------------', err); + } +} +errorManager.unregisterErrorObserver(observerId, unregisterErrorObserverCallback); + +``` + +## ErrorManager.unregisterErrorObserver + +unregisterErrorObserver(observerId: number): Promise\; + +Deregisters an error observer. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| observerId | number | No| Numeric code of the observer.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +var observerId = 100; +errorManager.unregisterErrorObserver(observerId) +.then((data) => { + console.log('----------- unregisterErrorObserver success ----------', data); +}) +.catch((err) => { + console.log('----------- unregisterErrorObserver fail ----------', err); +}) + +``` + +## ErrorObserver + +onUnhandledException(errMsg: string): void; + +Called when an unhandled exception occurs in the JS runtime. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| errMsg | string | No| Message and error stack trace about the exception.| + +**Example** + +```js +var observer = { + onUnhandledException(errorMsg) { + console.log('onUnhandledException, errorMsg: ', errorMsg) + } +} +errorManager.registerErrorObserver(observer) + .then((data) => { + console.log('----------- registerErrorObserver success ----------', data); + }) + .catch((err) => { + console.log('----------- registerErrorObserver fail ----------', err); + }) + +``` diff --git a/en/application-dev/reference/apis/js-apis-filemanager.md b/en/application-dev/reference/apis/js-apis-filemanager.md index 38d6d982683a111a7ef98acfbd0d6f8f8d61ba4d..9aa6294c56aed0d897ceecc46c4fd4ca6ecd48c6 100644 --- a/en/application-dev/reference/apis/js-apis-filemanager.md +++ b/en/application-dev/reference/apis/js-apis-filemanager.md @@ -1,6 +1,6 @@ # User File Access and Management -The fileManager module provides APIs for accessing and managing user files. It interworks with the underlying file management services to implement media library and external card management, and provides capabilities for applications to query and create user files. +The **fileManager** module provides APIs for accessing and managing user files. It interworks with the underlying file management services to implement media library and external card management, and provides capabilities for applications to query and create user files. >**NOTE**
> @@ -35,12 +35,10 @@ Obtains information about the root album or directory in asynchronous mode. This **Example** ```js - filemanager.getRoot().then((fileInfo) => { - if(Array.isArray(fileInfo)) { - for (var i = 0; i < fileInfo.length; i++) { - console.log("file:"+JSON.stringify(fileInfo)); - } - } + filemanager.getRoot().then((fileInfos) => { + for (var i = 0; i < fileInfos.length; i++) { + console.log("files:"+JSON.stringify(fileInfos)); + } }).catch((err) => { console.log(err) }); @@ -69,14 +67,11 @@ Obtains information about the root album or directory in asynchronous mode. This "name":"local" } }; - filemanager.getRoot(options, (err, fileInfo)=>{ - if(Array.isArray(fileInfo)) { - for (var i = 0; i < fileInfo.length; i++) { - console.log("file:"+JSON.stringify(fileInfo)); - } - } + filemanager.getRoot(options, (err, fileInfos)=>{ + for (var i = 0; i < fileInfos.length; i++) { + console.log("files:"+JSON.stringify(fileInfos)); + } }); - ``` ## filemanager.listFile @@ -111,18 +106,17 @@ Obtains information about the second-level album or files in asynchronous mode. **Example** ```js - // Obtain all files in the directory. - // Call listFile() and getRoot() to obtain the file URI. - let media_path = "" - filemanager.listFile(media_path, "file") - .then((fileInfo) => { - if(Array.isArray(fileInfo)) { - for (var i = 0; i < fileInfo.length; i++) { - console.log("file:"+JSON.stringify(fileInfo)); - } - } + // Obtain all files in the directory. You can use getRoot to obtain the directory URI. + filemanager.getRoot().then((fileInfos) => { + let file = fileInfos.find(item => item.name == "file_folder"); + let path = file.path; + filemanager.listFile(path, "file").then((files) => { + console.log("files:" + JSON.stringify(files)); + }).catch((err) => { + console.log("failed to get files" + err); + }); }).catch((err) => { - console.log("Failed to get file"+err); + console.log("failed to get root" + err); }); ``` @@ -153,33 +147,18 @@ Obtains information about the second-level album or files in asynchronous mode. **Example** - ```js - // Call listFile() and getRoot() to obtain the file path. - let fileInfos = filemanager.getRoot(); - let media_path = ""; - for (let i = 0; i < fileInfos.length; i++) { - if (fileInfos[i].name == "image_album") { - media_path = fileInfos[i].path; - } else if (fileInfos[i].name == "audio_album") { - media_path = fileInfos[i].path; - } else if (fileInfos[i].name == "video_album") { - media_path = fileInfos[i].path; - } else if (fileInfos[i].name == "file_folder") { - media_path = fileInfos[i].path; - } - } - - filemanager.listFile(media_path, "file") - .then((fileInfo) => { - if(Array.isArray(fileInfo)) { - for (var i = 0; i < fileInfo.length; i++) { - console.log("file:"+JSON.stringify(fileInfo)); - } - } - }).catch((err) => { - console.log("Failed to get file"+err); - }); - ``` +```js +// Obtain all files in the directory. You can use getRoot to obtain the directory URI. +filemanager.getRoot().then((fileInfos) => { + let file = fileInfos.find(item => item.name == "image_album"); + let path = file.path; + filemanager.listFile(path, "image",function(err, files){ + console.log("files:" + JSON.stringify(files)); + }) +}).catch((err) => { + console.log("failed to get root" + err); +}); +``` ## filemanager.createFile diff --git a/en/application-dev/reference/apis/js-apis-formextension.md b/en/application-dev/reference/apis/js-apis-formextension.md index daea33dbb50edf3aec50c84eee9795339bd9c43a..1540e538e1bcc8f53165a3fd277e60f76e73a7a1 100644 --- a/en/application-dev/reference/apis/js-apis-formextension.md +++ b/en/application-dev/reference/apis/js-apis-formextension.md @@ -35,15 +35,15 @@ Called to notify the widget provider that a **Form** instance (widget) has been **Parameters** -| Name| Type | Mandatory| Description | -| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | -| want | [Want](js-apis-application-Want.md) | Yes | Information related to the extension, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.| + | Name| Type | Mandatory| Description | + | ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | + | want | [Want](js-apis-application-Want.md) | Yes | Information related to the extension, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.| **Return value** -| Type | Description | -| ------------------------------------------------------------ | ----------------------------------------------------------- | -| [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.| + | Type | Description | + | ------------------------------------------------------------ | ----------------------------------------------------------- | + | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.| **Example** @@ -72,9 +72,9 @@ Called to notify the widget provider that a temporary widget has been converted **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------------ | -| formId | string | Yes | ID of the widget that requests to be converted to a normal one.| + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------------------------ | + | formId | string | Yes | ID of the widget that requests to be converted to a normal one.| **Example** @@ -96,9 +96,9 @@ Called to notify the widget provider that a widget has been updated. After obtai **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------ | -| formId | string | Yes | ID of the widget that requests to be updated.| + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------------------ | + | formId | string | Yes | ID of the widget that requests to be updated.| **Example** @@ -127,9 +127,9 @@ Called to notify the widget provider of the change of visibility. **Parameters** -| Name | Type | Mandatory| Description | -| --------- | ------------------------- | ---- | ---------------------------- | -| newStatus | { [key: string]: number } | Yes | ID and visibility status of the widget to be changed.| + | Name | Type | Mandatory| Description | + | --------- | ------------------------- | ---- | ---------------------------- | + | newStatus | { [key: string]: number } | Yes | ID and visibility status of the widget to be changed.| **Example** @@ -162,10 +162,10 @@ Called to instruct the widget provider to receive and process the widget event. **Parameters** -| Name | Type | Mandatory| Description | -| ------- | ------ | ---- | ---------------------- | -| formId | string | Yes | ID of the widget that requests the event.| -| message | string | Yes | Event message. | + | Name | Type | Mandatory| Description | + | ------- | ------ | ---- | ---------------------- | + | formId | string | Yes | ID of the widget that requests the event.| + | message | string | Yes | Event message. | **Example** @@ -187,9 +187,9 @@ Called to notify the widget provider that a **Form** instance (widget) has been **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------ | -| formId | string | Yes | ID of the widget to be destroyed.| + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------------------ | + | formId | string | Yes | ID of the widget to be destroyed.| **Example** @@ -211,9 +211,9 @@ Called when the configuration of the environment where the ability is running is **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [Configuration](js-apis-configuration.md) | Yes| New configuration.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [Configuration](js-apis-configuration.md) | Yes| New configuration.| **Example** @@ -235,9 +235,9 @@ Called when the widget provider receives the status query result of a widget. By **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | No| Description of the widget state, including the bundle name, ability name, module name, widget name, and widget dimension.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-application-Want.md) | No| Description of the widget state, including the bundle name, ability name, module name, widget name, and widget dimension.| **Example** @@ -250,3 +250,40 @@ Called when the widget provider receives the status query result of a widget. By } } ``` + +## FormExtension.onShare + +onShare?(formId: string): {[key: string]: any}; + +Called by the widget provider to receive shared widget data. + +This is a system API. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | formId | string | Yes | ID of a widget.| + +**Return value** + + | Type | Description | + | ------------------------------------------------------------ | ----------------------------------------------------------- | + | {[key: string]: any} | Data to be shared by the widget, in the form of key-value pairs.| + +**Example** + + ```js + class MyFormExtension extends FormExtension { + onShare(formId) { + console.log('FormExtension onShare, formId:' + formId); + let wantParams = { + "temperature":"20", + "time":"2022-8-8 09:59", + }; + return wantParams; + } + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-formextensioncontext.md b/en/application-dev/reference/apis/js-apis-formextensioncontext.md index f2e1fe143fbac2991698d2dd4244d88b23b0ebd5..7cd19e0e0f9a5d4ae906abd1a6d469893c1e95e0 100644 --- a/en/application-dev/reference/apis/js-apis-formextensioncontext.md +++ b/en/application-dev/reference/apis/js-apis-formextensioncontext.md @@ -2,13 +2,32 @@ The **FormExtensionContext** module, inherited from **ExtensionContext**, provides context for Form Extension abilities. -You can use the APIs of this module to start abilities. +You can use the APIs of this module to start Form Extension abilities. > **NOTE** > > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the stage model. +## Usage + +Before using the **ServiceExtensionContext** module, you must first obtain a **FormExtension** instance. +```js +import FormExtension from '@ohos.application.FormExtension'; +import formBindingData from '@ohos.application.formBindingData' +export default class MyFormExtension extends FormExtension { + onCreate() { + let dataObj1 = { + temperature:"11c", + "time":"11:00" + }; + let obj1 = formBindingData.createFormBindingData(dataObj1); + return obj1; + } +} + +``` + ## FormExtensionContext.startAbility startAbility(want: Want, callback: AsyncCallback<void>): void @@ -64,7 +83,7 @@ Starts an ability. This API uses a promise to return the result. | Type | Description | | ------------ | ---------------------------------- | -| Promise\ | Promise used to return the result.| +| Promise<void< | Promise used to return the result.| **Example** diff --git a/en/application-dev/reference/apis/js-apis-formprovider.md b/en/application-dev/reference/apis/js-apis-formprovider.md index 81855948f4994b85d601763ffe5e817a175d3733..fbe8907aed6b59d005f027af62ec4d0b0ec9a141 100644 --- a/en/application-dev/reference/apis/js-apis-formprovider.md +++ b/en/application-dev/reference/apis/js-apis-formprovider.md @@ -189,6 +189,7 @@ Obtains the application's widget information that meets a filter criterion on th **Example** ```js +import formInfo from '@ohos.application.formInfo'; const filter : formInfo.FormInfoFilter = { moduleName : "entry" }; @@ -224,6 +225,7 @@ Obtains the application's widget information on the device. This API uses a prom **Example** ```js +import formInfo from '@ohos.application.formInfo'; const filter : formInfo.FormInfoFilter = { moduleName : "entry" }; @@ -236,13 +238,13 @@ formProvider.getFormsInfo(filter).then((data) => { ## requestPublishForm9+ -requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback<string>): <void>; +requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\): void; Requests to publish a widget carrying data to the widget host. This API uses an asynchronous callback to return the result. -**System capability** +**System capability**: SystemCapability.Ability.Form -SystemCapability.Ability.Form +**System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -276,13 +278,13 @@ SystemCapability.Ability.Form ## requestPublishForm9+ -requestPublishForm(want: Want, callback: AsyncCallback<string>): <void>; +requestPublishForm(want: Want, callback: AsyncCallback<string>): void; Requests to publish a widget to the widget host. This API uses an asynchronous callback to return the result. -**System capability** +**System capability**: SystemCapability.Ability.Form -SystemCapability.Ability.Form +**System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -317,9 +319,9 @@ requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData Requests to publish a widget to the widget host. This API uses a promise to return the result. -**System capability** +**System capability**: SystemCapability.Ability.Form -SystemCapability.Ability.Form +**System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -360,6 +362,8 @@ Checks whether a widget can be published to the widget host. This API uses an as **System capability**: SystemCapability.Ability.Form +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name| Type | Mandatory| Description | @@ -402,6 +406,8 @@ Checks whether a widget can be published to the widget host. This API uses a pro **System capability**: SystemCapability.Ability.Form +**System API**: This is a system API and cannot be called by third-party applications. + **Return value** | Type | Description | diff --git a/en/application-dev/reference/apis/js-apis-i18n.md b/en/application-dev/reference/apis/js-apis-i18n.md index 6dff0d44e9f3fd7cc75b27668f58184715a3bc42..a21e4ddb660cba43fef79e5e509464eca986aea9 100644 --- a/en/application-dev/reference/apis/js-apis-i18n.md +++ b/en/application-dev/reference/apis/js-apis-i18n.md @@ -1,6 +1,7 @@ # Internationalization – I18N -> **NOTE**
+> **NOTE** +> > - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. > > - This module provides system-related or enhanced I18N capabilities, such as locale management, phone number formatting, and calendar, through supplementary I18N interfaces that are not defined in ECMA 402. For details about the basic I18N capabilities, see [Intl](js-apis-intl.md). @@ -115,7 +116,7 @@ Obtains the system language. setSystemLanguage(language: string): boolean -Sets the system language. +Sets the system language. Currently, this API does not support real-time updating of the system language. This is a system API. @@ -673,7 +674,7 @@ Formats a phone number. phonenumberfmt.isValidNumber("15812312312"); ``` -### getLocationName8+ +### getLocationName9+ static getLocationName(number: string, locale: string): string @@ -752,6 +753,29 @@ Converts one measurement unit into another and formats the unit based on the spe i18n.Util.unitConvert({unit: "cup", measureSystem: "US"}, {unit: "liter", measureSystem: "SI"}, 1000, "en-US", "long"); ``` +### getDateOrder9+ + +static getDateOrder(locale: string): string + +Obtains the sequence of the year, month, and day in the specified locale. + +**System capability**: SystemCapability.Global.I18n + +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ---------------------------------------- | +| locale | string | Yes | Locale used for formatting, for example, **zh-Hans-CN**. | + +**Return value** +| Type | Description | +| ------ | ----------------------- | +| string | Sequence of the year, month, and day.| + +**Example** + ``` + i18n.Util.getDateOrder("zh-CN"); + ``` + ## getInstance8+ @@ -1486,10 +1510,10 @@ Obtains the **TimeZone** object corresponding to the specified time zone ID. ``` -## TimeZone8+ +## TimeZone -### getID8+ +### getID getID(): string @@ -1509,7 +1533,7 @@ Obtains the ID of the specified **TimeZone** object. ``` -### getDisplayName8+ +### getDisplayName getDisplayName(locale?: string, isDST?: boolean): string @@ -1535,7 +1559,7 @@ Obtains the representation of a **TimeZone** object in the specified locale. ``` -### getRawOffset8+ +### getRawOffset getRawOffset(): number @@ -1555,7 +1579,7 @@ Obtains the offset between the time zone represented by a **TimeZone** object an ``` -### getOffset8+ +### getOffset getOffset(date?: number): number @@ -1705,3 +1729,73 @@ Checks whether the local digit switch is turned on. ```js var status = i18n.getUsingLocalDigit(); ``` + +## Transliterator9+ + + +### getAvailableIDs9+ + +static getAvailableIDs(): string[] + +Obtains a list of IDs supported by the **Transliterator** object. + +**System capability**: SystemCapability.Global.I18n + +**Return value** +| Type | Description | +| ------ | ------------ | +| string[] | List of IDs supported by the **Transliterator** object.| + +**Example** + ``` + i18n.Transliterator.getAvailableIDs(); + ``` + + +### getInstance9+ + +static getInstance(id: string): Transliterator + +Creates a **Transliterator** object. + +**System capability**: SystemCapability.Global.I18n + +**Parameters** +| Name | Type | Mandatory | Description | +| ------ | ------- | ---- | -------------------- | +| id | string | Yes | ID supported by the **Transliterator** object. | + +**Return value** +| Type | Description | +| ------ | ------------- | +| [Transliterator](#transliterator9) | **Transliterator** object.| + +**Example** + ``` + var transliterator = i18n.Transliterator.getInstance("Any-Latn"); + ``` + + +### transform9+ + +transform(text: string): string + +Converts the input string from the source format to the target format. + +**System capability**: SystemCapability.Global.I18n + +**Parameters** +| Name | Type | Mandatory | Description | +| ------ | ------- | ---- | -------------------- | +| text | string | Yes | Input string. | + +**Return value** +| Type | Description | +| ------ | ------------- | +| string | Target string.| + +**Example** + ``` + var transliterator = i18n.Transliterator.getInstance("Any-Latn"); + transliterator.transform ("China"); + ``` diff --git a/en/application-dev/reference/apis/js-apis-inputconsumer.md b/en/application-dev/reference/apis/js-apis-inputconsumer.md index 6b30c686816e121ea8a3aacb9878a8a4d032f6f6..98529f06257e7d2dfe3e9a395fd176dd413bb347 100644 --- a/en/application-dev/reference/apis/js-apis-inputconsumer.md +++ b/en/application-dev/reference/apis/js-apis-inputconsumer.md @@ -2,7 +2,7 @@ The Input Consumer module implements listening for key events. -> **NOTE**
+> **NOTE** > > - The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > diff --git a/en/application-dev/reference/apis/js-apis-inputmethod.md b/en/application-dev/reference/apis/js-apis-inputmethod.md index e7046b7cc33a789db03235e3086aedf9d842317a..47f0d3429179406f598940f977baab87ef7b3482 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethod.md +++ b/en/application-dev/reference/apis/js-apis-inputmethod.md @@ -247,11 +247,11 @@ Displays a dialog box for selecting an input method. This API uses an asynchrono ### displayOptionalInputMethod - displayOptionalInputMethod(): Promise<void> +displayOptionalInputMethod(): Promise<void> Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result. - **System capability**: SystemCapability.MiscServices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Return value** diff --git a/en/application-dev/reference/apis/js-apis-inputmethodengine.md b/en/application-dev/reference/apis/js-apis-inputmethodengine.md index 60c6c8a4ce2d0caad26c838e6353cdc21bcbc785..55e702cd0501af092bbc7e0420f410ff81ed90c6 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethodengine.md +++ b/en/application-dev/reference/apis/js-apis-inputmethodengine.md @@ -1,19 +1,22 @@ # Input Method Engine -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +The **inputMethodEngine** module streamlines the interaction between applications and input methods. By calling APIs of this module, applications can accept text input through the input methods, be bound to input method services, request the keyboard to display or hide, listen for the input method status, and much more. + +> **NOTE** > +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import ``` -import inputMethodEngine from '@ohos.inputMethodEngine'; +import inputMethodEngine from '@ohos.inputmethodengine'; ``` ## inputMethodEngine -Defines constant values. +Provides the constants. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | @@ -50,7 +53,7 @@ getInputMethodEngine(): InputMethodEngine Obtains an **InputMethodEngine** instance. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Return value** @@ -60,9 +63,9 @@ Obtains an **InputMethodEngine** instance. **Example** -```js -var InputMethodEngine = inputMethodEngine.getInputMethodEngine(); -``` + ```js + var InputMethodEngine = inputMethodEngine.getInputMethodEngine(); + ``` ## inputMethodEngine.createKeyboardDelegate @@ -70,7 +73,7 @@ createKeyboardDelegate(): KeyboardDelegate Obtains a **KeyboardDelegate** instance. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Return value** @@ -80,9 +83,9 @@ Obtains a **KeyboardDelegate** instance. **Example** -```js -var KeyboardDelegate = inputMethodEngine.createKeyboardDelegate(); -``` + ```js + var KeyboardDelegate = inputMethodEngine.createKeyboardDelegate(); + ``` ## InputMethodEngine @@ -94,7 +97,7 @@ on(type: 'inputStart', callback: (kbController: KeyboardController, textInputCli Listens for the input method binding event. This API uses a callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** @@ -105,12 +108,12 @@ Listens for the input method binding event. This API uses a callback to return t **Example** -```js -InputMethodEngine.on('inputStart', (kbController, textInputClient) => { - KeyboardController = kbController; - TextInputClient = textInputClient; -}); -``` + ```js + InputMethodEngine.on('inputStart', (kbController, textInputClient) => { + KeyboardController = kbController; + TextInputClient = textInputClient; + }); + ``` ### off('inputStart') @@ -118,7 +121,7 @@ off(type: 'inputStart', callback?: (kbController: KeyboardController, textInputC Cancels listening for the input method binding event. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** @@ -127,11 +130,13 @@ Cancels listening for the input method binding event. | type | string | Yes | Listening type.
Set it to **'inputStart'**, which indicates listening for the input method binding event.| | callback | [KeyboardController](#KeyboardController), [TextInputClient](#TextInputClient) | No| Callback used to return the result.| + + **Example** -```js -InputMethodEngine.off('inputStart'); -``` + ```js + InputMethodEngine.off('inputStart'); + ``` ### on('keyboardShow'|'keyboardHide') @@ -139,22 +144,22 @@ on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void Listens for an input method event. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** | Name | Type | Mandatory| Description | | -------- | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
- The value **'keyboardShow'** means to listen for displaying of the input method.
- The value **'keyboardHide'** means to listen for hiding of the input method.| +| type | string | Yes | Listening type.
- The value **'keyboardShow'** means to listen for displaying of the input method.
- The value **'keyboardHide'** means to listen for hiding of the input method.| | callback | void | No | Callback used to return the result. | **Example** -```js -InputMethodEngine.on('keyboardShow', (err) => { - console.info('keyboardShow'); -}); -``` + ```js + InputMethodEngine.on('keyboardShow', (err) => { + console.info('keyboardShow'); + }); + ``` ### off('keyboardShow'|'keyboardHide') @@ -162,20 +167,21 @@ off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void Cancels listening for an input method event. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** | Name | Type | Mandatory| Description | | -------- | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
- The value **'keyboardShow'** means to listen for displaying of the input method.
- The value **'keyboardHide'** means to listen for hiding of the input method.| +| type | string | Yes | Listening type.
- The value **'keyboardShow'** means to listen for displaying of the input method.
- The value **'keyboardHide'** means to listen for hiding of the input method.| | callback | void | No | Callback used to return the result. | **Example** -```js -InputMethodEngine.off('keyboardShow'); -``` + ```js + InputMethodEngine.off('keyboardShow'); + ``` + ## KeyboardDelegate @@ -187,22 +193,24 @@ on(type: 'keyDown'|'keyUp', callback: (event: KeyEvent) => boolean): void Listens for a hard keyboard even. This API uses a callback to return the key information. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** | Name | Type | Mandatory| Description | | -------- | ------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
- The value **'keyDown'** means to listen for pressing of a key.
- The value **'keyUp'** means to listen for releasing of a key.| +| type | string | Yes | Listening type.
- The value **'keyDown'** means to listen for pressing of a key.
- The value **'keyUp'** means to listen for releasing of a key.| | callback | [KeyEvent](#KeyEvent) | Yes| Callback used to return the key information.| + + **Example** -```js -KeyboardDelegate.on('keyDown', (event) => { - console.info('keyDown'); -}); -``` + ```js + KeyboardDelegate.on('keyDown', (event) => { + console.info('keyDown'); + }); + ``` ### off('keyDown'|'keyUp') @@ -210,20 +218,20 @@ off(type: 'keyDown'|'keyUp', callback?: (event: KeyEvent) => boolean): void Cancels listening for a hard keyboard even. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** | Name | Type | Mandatory| Description | | -------- | --------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
- The value **'keyDown'** means to listen for pressing of a key.
- The value **'keyUp'** means to listen for releasing of a key.| +| type | string | Yes | Listening type.
- The value **'keyDown'** means to listen for pressing of a key.
- The value **'keyUp'** means to listen for releasing of a key.| | callback | [KeyEvent](#KeyEvent) | No | Callback used to return the key information. | **Example** -```js -KeyboardDelegate.off('keyDown'); -``` + ```js + KeyboardDelegate.off('keyDown'); + ``` ### on('cursorContextChange') @@ -231,21 +239,25 @@ on(type: 'cursorContextChange', callback: (x: number, y:number, height:number) = Listens for cursor context changes. This API uses a callback to return the cursor information. -**System capability**: SystemCapability.Miscservices.InputMethodFramework + **System capability**: SystemCapability.MiscServices.InputMethodFramework -**Parameters** + **Parameters** | Name | Type | Mandatory| Description | | -------- | ------ | ---- | ------------------------------------------------------------ | | type | string | Yes | Listening type.
Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.| | callback | number | Yes | Callback used to return the cursor information. | -**Example** + + + **Example** ```js + KeyboardDelegate.on('cursorContextChange', (x, y, height) => { console.info('cursorContextChange'); }); + ``` ### off('cursorContextChange') @@ -254,42 +266,46 @@ off(type: 'cursorContextChange', callback?: (x: number, y:number, height:number) Cancels listening for cursor context changes. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework -**Parameters** + **Parameters** -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ------------------------ | -| type | string | Yes | Listening type.
Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.| -| callback | number | No| Callback used to return the cursor information.| +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.| +| callback | number | No | Callback used to return the cursor information. | -**Example** + + **Example** ```js + KeyboardDelegate.off('cursorContextChange'); -``` +``` ### on('selectionChange') on(type: 'selectionChange', callback: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void Listens for text selection changes. This API uses a callback to return the text selection information. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework -**Parameters** + **Parameters** | Name | Type | Mandatory| Description | | -------- | ------ | ---- | ------------------------------------------------------------ | | type | string | Yes | Listening type.
Set it to **'selectionChange'**, which indicates listening for text selection changes.| | callback | number | Yes | Callback used to return the text selection information. | -**Example** + **Example** ```js + KeyboardDelegate.on('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => { console.info('selectionChange'); }); + ``` ### off('selectionChange') @@ -298,19 +314,21 @@ off(type: 'selectionChange', callback?: (oldBegin: number, oldEnd: number, newBe Cancels listening for text selection changes. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework -**Parameters** + **Parameters** -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ------------------------ | -| type | string | Yes | Listening type.
Set it to **'selectionChange'**, which indicates listening for text selection changes.| -| callback | number | No| Callback used to return the text selection information.| +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
Set it to **'selectionChange'**, which indicates listening for text selection changes.| +| callback | number | No | Callback used to return the text selection information. | -**Example** + **Example** ```js + KeyboardDelegate.off('selectionChange'); + ``` @@ -320,21 +338,23 @@ on(type: 'textChange', callback: (text: string) => void): void Listens for text changes. This API uses a callback to return the current text content. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework -**Parameters** + **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
Set it to **'textChange'**, which indicates listening for text changes.| -| callback | string | Yes| Callback used to return the current text content.| +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
Set it to **'textChange'**, which indicates listening for text changes.| +| callback | string | Yes | Callback used to return the current text content. | -**Example** + **Example** ```js + KeyboardDelegate.on('textChange', (text) => { console.info('textChange'); }); + ``` ### off('textChange') @@ -343,16 +363,16 @@ off(type: 'textChange', callback?: (text: string) => void): void Cancels listening for text changes. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework -**Parameters** + **Parameters** -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ------------------------ | -| type | string | Yes | Listening type.
Set it to **'textChange'**, which indicates listening for text changes.| -| callback | string | No| Callback used to return the current text content.| +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
Set it to **'textChange'**, which indicates listening for text changes.| +| callback | string | No | Callback used to return the current text content. | -**Example** + **Example** ```js KeyboardDelegate.off('textChange'); @@ -368,7 +388,7 @@ hideKeyboard(callback: AsyncCallback<void>): void Hides the keyboard. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** @@ -388,19 +408,18 @@ Hides the keyboard. This API uses an asynchronous callback to return the result. hideKeyboard(): Promise<void> -Hides the keyboard. This API uses a promise to return the result. +Hides the keyboard. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Return value** -| Type | Description: | +| Type | Description | | ---------------- | -------- | | Promise<void> | Promise used to return the result.| **Example** - ```js KeyboardController.hideKeyboard(); ``` @@ -415,30 +434,30 @@ getForward(length:number, callback: AsyncCallback<string>): void Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | length | number | Yes| Text length.| -| callback | AsyncCallback<string> | Yes| Text returned.| +| callback | AsyncCallback<string> | Yes| Callback used to return the text.| **Example** -```js - TextInputClient.getForward(5,(text) =>{ - console.info("text = " + text); - }); -``` + ```js + TextInputClient.getForward(5,(text) =>{ + console.info("text = " + text); + }); + ``` ### getForward getForward(length:number): Promise<string> -Obtains the specific-length text before the cursor. This API uses a promise to return the result. +Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** @@ -450,14 +469,14 @@ Obtains the specific-length text before the cursor. This API uses a promise to r | Type | Description | | ------------------------------- | ------------------------------------------------------------ | -| Promise<string> | Text returned. | +| Promise<string> | Promise used to return the text. | **Example** -```js - var text = TextInputClient.getForward(5); - console.info("text = " + text); -``` + ```js + var text = TextInputClient.getForward(5); + console.info("text = " + text); + ``` ### getBackward @@ -465,30 +484,30 @@ getBackward(length:number, callback: AsyncCallback<string>): void Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | length | number | Yes| Text length.| -| callback | AsyncCallback<string> | Yes| Text returned.| +| callback | AsyncCallback<string> | Yes| Callback used to return the text.| **Example** -```js - TextInputClient.getBackward(5,(text)=>{ - console.info("text = " + text); -}); -``` + ```js + TextInputClient.getBackward(5,(text)=>{ + console.info("text = " + text); + }); + ``` ### getBackward getBackward(length:number): Promise<string> -Obtains the specific-length text after the cursor. This API uses a promise to return the result. +Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** @@ -500,14 +519,14 @@ Obtains the specific-length text after the cursor. This API uses a promise to re | Type | Description | | ------------------------------- | ------------------------------------------------------------ | -| Promise<string> | Text returned. | +| Promise<string> | Promise used to return the text. | **Example** -```js - var text = TextInputClient.getBackward(5); - console.info("text = " + text); -``` + ```js + var text = TextInputClient.getBackward(5); + console.info("text = " + text); + ``` ### deleteForward @@ -515,47 +534,46 @@ deleteForward(length:number, callback: AsyncCallback<boolean>): void Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | length | number | Yes| Text length.| -| callback | AsyncCallback<boolean> | Yes| Returns whether the operation is successful.| +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| **Example** -```js -TextInputClient.deleteForward(5,(isSuccess)=>{ - console.info("isSuccess = " + isSuccess); -}); -``` - + ```js + TextInputClient.deleteForward(5,(isSuccess)=>{ + console.info("isSuccess = " + isSuccess); + }); + ``` ### deleteForward deleteForward(length:number): Promise<boolean> -Deletes the fixed-length text before the cursor. This API uses a promise to return the result. +Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| length | number | Yes| Text length.| +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------- | +| length | number | Yes | Text length.| **Return value** -| Type | Description | -| ------------------------------- | ------------------------------------------------------------ | -| Promise<boolean> | Returns whether the operation is successful. | +| Type | Description | +| ---------------------- | -------------- | +| Promise<boolean> | Promise used to return the result.| **Example** ```js - var isSuccess = TextInputClient.deleteForward(5); +var isSuccess = TextInputClient.deleteForward(5); console.info("isSuccess = " + isSuccess); ``` @@ -565,33 +583,34 @@ deleteBackward(length:number, callback: AsyncCallback<boolean>): void Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework -**Parameters** + **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| length | number | Yes| Text length.| -| callback | AsyncCallback<boolean> | Yes| Returns whether the operation is successful.| +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | -------------- | +| length | number | Yes | Text length. | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.| -**Example** + **Example** ```js + TextInputClient.deleteBackward(5, (isSuccess)=>{ console.info("isSuccess = " + isSuccess); }); + ``` ### deleteBackward deleteBackward(length:number): Promise<boolean> -Deletes the fixed-length text after the cursor. This API uses a promise to return the result. +Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** - | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | length | number | Yes| Text length.| @@ -600,45 +619,48 @@ Deletes the fixed-length text after the cursor. This API uses a promise to retur | Type | Description | | ------------------------------- | ------------------------------------------------------------ | -| Promise<boolean> | Returns whether the operation is successful. | +| Promise<boolean> | Promise used to return the result. | **Example** ```js -var isSuccess = TextInputClient.deleteBackward(5); -console.info("isSuccess = " + isSuccess); -``` + var isSuccess = TextInputClient.deleteBackward(5); + console.info("isSuccess = " + isSuccess); + +``` ### sendKeyFunction sendKeyFunction(action:number, callback: AsyncCallback<boolean>): void Sets the Enter key to send the text to its target. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework -**Parameters** + **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | action | number | Yes| Edit box attribute.| -| callback | AsyncCallback<boolean> | Yes| Returns whether the operation is successful.| +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| -**Example** + **Example** ```js + TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT,(isSuccess)=>{ console.info("isSuccess = " + isSuccess); }); + ``` ### sendKeyFunction sendKeyFunction(action:number): Promise<boolean> -Sets the Enter key to send the text to its target. This API uses a promise to return the result. +Sets the Enter key to send the text to its target. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** @@ -650,14 +672,14 @@ Sets the Enter key to send the text to its target. This API uses a promise to re | Type | Description | | ------------------------------- | ------------------------------------------------------------ | -| Promise<boolean> | Returns whether the operation is successful. | +| Promise<boolean> | Promise used to return the result. | **Example** -```js -var isSuccess = TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT); -console.info("isSuccess = " + isSuccess); -``` + ```js + var isSuccess = TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT); + console.info("isSuccess = " + isSuccess); + ``` ### insertText @@ -665,30 +687,32 @@ insertText(text:string, callback: AsyncCallback<boolean>): void Inserts text. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | text | string | Yes| Text to insert.| -| callback | AsyncCallback<boolean> | Yes| Returns whether the operation is successful.| +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| **Example** ```js + TextInputClient.insertText("test", (isSuccess)=>{ console.info("isSuccess = " + isSuccess); }); + ``` ### insertText insertText(text:string): Promise<boolean> -Inserts text. This API uses a promise to return the result. +Inserts text. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** @@ -696,18 +720,18 @@ Inserts text. This API uses a promise to return the result. | -------- | -------- | -------- | -------- | | text | string | Yes| Text to insert.| -**Return value** +**Return value** | Type | Description | | ------------------------------- | ------------------------------------------------------------ | -| Promise<boolean> | Returns whether the operation is successful. | +| Promise<boolean> | Promise used to return the result. | **Example** -```js -var isSuccess = TextInputClient.insertText("test"); -console.info("isSuccess = " + isSuccess); -``` + ```js + var isSuccess = TextInputClient.insertText("test"); + console.info("isSuccess = " + isSuccess); + ``` ### getEditorAttribute @@ -715,7 +739,7 @@ getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Parameters** @@ -725,36 +749,36 @@ Obtains the attribute of the edit box. This API uses an asynchronous callback to **Example** -```js - TextInputClient.getEditorAttribute((EditorAttribute)=>{ - }); -``` + ```js + TextInputClient.getEditorAttribute((EditorAttribute)=>{ + }); + ``` ### getEditorAttribute getEditorAttribute(): EditorAttribute -Obtains the attribute of the edit box. This API uses a promise to return the result. +Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework **Return value** | Type | Description | | ------------------------------- | ------------------------------------------------------------ | -| Promise<[EditorAttribute](#EditorAttribute)> | Returns the attribute of the edit box. | +| Promise<[EditorAttribute](#EditorAttribute)> | Promise used to return the attribute of the edit box. | **Example** -```js -var EditorAttribute = TextInputClient.getEditorAttribute(); -``` + ```js + var EditorAttribute = TextInputClient.getEditorAttribute(); + ``` ## EditorAttribute Describes the attribute of the edit box. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework | Name | Type| Readable| Writable| Description | | ------------ | -------- | ---- | ---- | ------------------ | @@ -765,7 +789,7 @@ Describes the attribute of the edit box. Describes the attribute of a key. -**System capability**: SystemCapability.Miscservices.InputMethodFramework +**System capability**: SystemCapability.MiscServices.InputMethodFramework | Name | Type| Readable| Writable| Description | | --------- | -------- | ---- | ---- | ------------ | diff --git a/en/application-dev/reference/apis/js-apis-keycode.md b/en/application-dev/reference/apis/js-apis-keycode.md index 9a1c1712577e7d34c841ba19fc47376166ad231c..3a711c0ea13132547c4fc2bb9cc76066f71ab0ee 100644 --- a/en/application-dev/reference/apis/js-apis-keycode.md +++ b/en/application-dev/reference/apis/js-apis-keycode.md @@ -203,7 +203,7 @@ import {KeyCode} from '@ohos.multimodalInput.keyCode' | KEYCODE_CLOSE | number | Yes| No| Close key| | KEYCODE_PLAY | number | Yes| No| Play key| | KEYCODE_BASSBOOST | number | Yes| No| Bass Boost key| -| KEYCODE_PRINT | number | Yes| No| Print key| +| KEYCODE_PRINT | number | Yes| No| Print key| | KEYCODE_CHAT | number | Yes| No| Chat key| | KEYCODE_FINANCE | number | Yes| No| Finance key| | KEYCODE_CANCEL | number | Yes| No| Cancel key| @@ -302,7 +302,7 @@ import {KeyCode} from '@ohos.multimodalInput.keyCode' | KEYCODE_SCREENLOCK | number | Yes| No| Screen Lock key| | KEYCODE_DIRECTION_ROTATE_DISPLAY | number | Yes| No| Directional Rotation Display key| | KEYCODE_CYCLEWINDOWS | number | Yes| No| Windows Cycle key| -| KEYCODE_COMPUTER | number | Yes| No| Computer key| +| KEYCODE_COMPUTER | number | Yes| No| Key | | KEYCODE_EJECTCLOSECD | number | Yes| No| Eject CD key| | KEYCODE_ISO | number | Yes| No| ISO key| | KEYCODE_MOVE | number | Yes| No| Move key| diff --git a/en/application-dev/reference/apis/js-apis-media.md b/en/application-dev/reference/apis/js-apis-media.md index 77002020139fbdb2aada0cb1141a0f2840a9f250..dff8251fcc345a2e8fb24b4fcafee582357951b0 100644 --- a/en/application-dev/reference/apis/js-apis-media.md +++ b/en/application-dev/reference/apis/js-apis-media.md @@ -106,6 +106,7 @@ media.createVideoPlayer().then((video) => { createAudioRecorder(): AudioRecorder Creates an **AudioRecorder** instance to control audio recording. +Only one **AudioRecorder** instance can be created per device. **System capability**: SystemCapability.Multimedia.Media.AudioRecorder @@ -126,6 +127,7 @@ let audioRecorder = media.createAudioRecorder(); createVideoRecorder(callback: AsyncCallback\<[VideoRecorder](#videorecorder9)>): void Creates a **VideoRecorder** instance in asynchronous mode. This API uses a callback to return the result. +Only one **AudioRecorder** instance can be created per device. **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -155,6 +157,7 @@ media.createVideoRecorder((error, video) => { createVideoRecorder(): Promise<[VideoRecorder](#videorecorder9)> Creates a **VideoRecorder** instance in asynchronous mode. This API uses a promise to return the result. +Only one **AudioRecorder** instance can be created per device. **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -272,14 +275,15 @@ For details about the audio playback demo, see [Audio Playback Development](../. **System capability**: SystemCapability.Multimedia.Media.AudioPlayer -| Name | Type | Readable| Writable| Description | -| ----------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ | -| src | string | Yes | Yes | Audio media URI. The mainstream audio formats (MPEG-4, AAC, MPEG-3, OGG, and WAV) are supported.
**Example of supported URIs**:
1. FD playback: fd://xx
![](figures/en-us_image_url.png)
2. HTTP network playback: http://xx
3. HTTPS network playback: https://xx
**Note**:
To use media materials, you must declare the read permission. Otherwise, the media materials cannot be played properly.| -| loop | boolean | Yes | Yes | Whether to loop audio playback. The value **true** means to loop audio playback, and **false** means the opposite. | -| currentTime | number | Yes | No | Current audio playback position. | -| duration | number | Yes | No | Audio duration. | -| state | [AudioState](#audiostate) | Yes | No | Audio playback state. | - +| Name | Type | Readable| Writable| Description | +| ------------------------------- | ----------------------------------- | ---- | ---- | ------------------------------------------------------------ | +| src | string | Yes | Yes | Audio file URI. The mainstream audio formats (M4A, AAC, MPEG-3, OGG, and WAV) are supported.
**Examples of supported URI schemes**:
1. FD: fd://xx
![](figures/en-us_image_url.png)
2. HTTP: http://xx
3. HTTPS: https://xx
4. HLS: http://xx or https://xx
**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.INTERNET (The latter is required only when online resources are used.)| +| fdSrc9+ | [AVFileDescriptor](#interruptmode9) | Yes | Yes | Description of the audio file. This attribute is required when audio resources of an application are continuously stored in a file.
**Example:**
Assume that a music file that stores continuous music resources consists of the following:
Music 1 (address offset: 0, byte length: 100)
Music 2 (address offset: 101; byte length: 50)
Music 3 (address offset: 151, byte length: 150)
1. To play music 1: AVFileDescriptor {fd = resource handle; offset = 0; length = 100; }
2. To play music 2: AVFileDescriptor {fd = resource handle; offset = 101; length = 50; }
3. To play music 3: AVFileDescriptor {fd = resource handle; offset = 151; length = 150; }
If the file is an independent music file, use **src=fd://xx**.

**Required permissions**: ohos.permission.READ_MEDIA| +| loop | boolean | Yes | Yes | Whether to loop audio playback. The value **true** means to loop audio playback, and **false** means the opposite. | +| audioInterruptMode9+ | [InterruptMode](#interruptmode9) | Yes | Yes | Audio interruption mode. | +| currentTime | number | Yes | No | Current audio playback position, in ms. | +| duration | number | Yes | No | Audio duration, in ms. | +| state | [AudioState](#audiostate) | Yes | No | Audio playback state. This state cannot be used as the condition for triggering the call of **play()**, **pause()**, or **stop()**.| ### play play(): void @@ -501,7 +505,7 @@ Subscribes to the audio buffering update event. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'bufferingUpdate' in this case. | +| type | string | Yes | Event type, which is **'bufferingUpdate'** in this case. | | callback | function | Yes | Callback invoked when the event is triggered.
When [BufferingInfoType](#bufferinginfotype8) is set to **BUFFERING_PERCENT** or **CACHED_DURATION**, **value** is valid. Otherwise, **value** is fixed at **0**.| **Example** @@ -590,7 +594,7 @@ audioPlayer.src = fdPath; // Set the src attribute and trigger the 'dataLoad' e on(type: 'timeUpdate', callback: Callback\): void -Subscribes to the 'timeUpdate' event. +Subscribes to the **'timeUpdate'** event. **System capability**: SystemCapability.Multimedia.Media.AudioPlayer @@ -598,7 +602,7 @@ Subscribes to the 'timeUpdate' event. | Name | Type | Mandatory| Description | | -------- | ----------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'timeUpdate' in this case.
The 'timeUpdate' event is triggered when the [seek()](#audioplayer_seek) API is called.| +| type | string | Yes | Event type, which is **'timeUpdate'** in this case.
The **'timeUpdate'** event is triggered when the [seek()](#audioplayer_seek) API is called. | | callback | Callback\ | Yes | Callback invoked when the event is triggered. The input parameter of the callback is the time when the seek operation is successful. | **Example** @@ -618,7 +622,7 @@ audioPlayer.seek(30000); // Seek to 30000 ms. on(type: 'error', callback: ErrorCallback): void -Subscribes to the audio playback error event. +Subscribes to audio playback error events. After an error event is reported, you must handle the event and exit the playback. **System capability**: SystemCapability.Multimedia.Media.AudioPlayer @@ -626,13 +630,13 @@ Subscribes to the audio playback error event. | Name | Type | Mandatory| Description | | -------- | ------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'error' in this case.
The 'error' event is triggered when an error occurs during audio playback.| +| type | string | Yes | Event type, which is **'error'** in this case.
The **'error'** event is triggered when an error occurs during audio playback. | | callback | ErrorCallback | Yes | Callback invoked when the event is triggered. | **Example** ```js -audioPlayer.on('error', (error) => { // Set the error event callback. +audioPlayer.on('error', (error) => { // Set the 'error' event callback. console.info(`audio error called, errName is ${error.name}`); // Print the error name. console.info(`audio error called, errCode is ${error.code}`); // Print the error code. console.info(`audio error called, errMessage is ${error.message}`);// Print the detailed description of the error type. @@ -646,13 +650,38 @@ Enumerates the audio playback states. You can obtain the state through the **sta **System capability**: SystemCapability.Multimedia.Media.AudioPlayer -| Name | Type | Description | -| ------------------ | ------ | -------------- | -| idle | string | The audio player is idle.| -| playing | string | Audio playback is in progress.| -| paused | string | Audio playback is paused.| -| stopped | string | Audio playback is stopped.| -| error8+ | string | Audio playback is in the error state. | +| Name | Type | Description | +| ------------------ | ------ | ---------------------------------------------- | +| idle | string | No audio playback is in progress. The audio player is in this state after the **'dataload'** or **'reset'** event is triggered.| +| playing | string | Audio playback is in progress. The audio player is in this state after the **'play'** event is triggered. | +| paused | string | Audio playback is paused. The audio player is in this state after the **'pause'** event is triggered. | +| stopped | string | Audio playback is stopped. The audio player is in this state after the **'stop'** event is triggered. | +| error8+ | string | Audio playback is in the error state. | + +## AVFileDescriptor9+ + +Describes audio and video file resources. It is used to specify a particular resource for playback based on its offset and length within a file. + +**System capability**: SystemCapability.Multimedia.Media.AudioPlayer + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| fd | number | Yes | Resource handle, which is obtained by calling **resourceManager.getRawFileDescriptor**. | +| offset | number | Yes | Resource offset, which needs to be entered based on the preset resource information. An invalid value causes a failure to parse audio and video resources.| +| length | number | Yes | Resource length, which needs to be entered based on the preset resource information. An invalid value causes a failure to parse audio and video resources.| + +## InterruptMode9+ + +Describes the audio interruption mode. + +**System capability**: SystemCapability.Multimedia.Media.AudioPlayer + +| Name | Default Value| Description | +| ---------------------------- | ------ | ---------- | +| SHARE_MODE | 0 | Shared mode.| +| INDEPENDENT_MODE| 1 | Independent mode. | ## VideoPlayer8+ @@ -666,13 +695,16 @@ For details about the video playback demo, see [Video Playback Development](../. | Name | Type | Readable| Writable| Description | | ------------------------ | ---------------------------------- | ---- | ---- | ------------------------------------------------------------ | -| url8+ | string | Yes | Yes | Video media URL. The mainstream video formats (MPEG-4, MPEG-TS, WebM, and MKV) are supported.
**Example of supported URIs**:
1. FD playback: fd://xx
![](figures/en-us_image_url.png)
2. HTTP network playback: http://xx
3. HTTPS network playback: https://xx
3. HLS network playback: http://xx or https://xx
**Note**:
To use media materials, you must declare the read permission. Otherwise, the media materials cannot be played properly.| +| url8+ | string | Yes | Yes | Video media URL. The mainstream video formats (MPEG-4, MPEG-TS, WebM, and MKV) are supported.
**Example of supported URIs**:
1. FD: fd://xx
![](figures/en-us_image_url.png)
2. HTTP: http://xx
3. HTTPS: https://xx
4. HLS: http://xx or https://xx
**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.INTERNET (The latter is required only when online resources are used.)| +| fdSrc9+ | [AVFileDescriptor](#interruptmode9) | Yes| Yes| Description of a video file. This attribute is required when video resources of an application are continuously stored in a file.
**Example:**
Assume that a music file that stores continuous music resources consists of the following:
Video 1 (address offset: 0, byte length: 100)
Video 2 (address offset: 101; byte length: 50)
Video 3 (address offset: 151, byte length: 150)
1. To play video 1: AVFileDescriptor {fd = resource handle; offset = 0; length = 100; }
2. To play video 2: AVFileDescriptor {fd = resource handle; offset = 101; length = 50; }
3. To play video 3: AVFileDescriptor {fd = resource handle; offset = 151; length = 150; }
To play an independent video file, use **src=fd://xx**.
**Note**:
**Required permissions**: ohos.permission.READ_MEDIA| | loop8+ | boolean | Yes | Yes | Whether to loop video playback. The value **true** means to loop video playback, and **false** means the opposite. | -| currentTime8+ | number | Yes | No | Current video playback position. | -| duration8+ | number | Yes | No | Video duration. The value **-1** indicates the live streaming mode. | +| videoScaleType9+ | [VideoScaleType](#videoscaletype9) | Yes | Yes | Video scale type. | +| audioInterruptMode9+ | [InterruptMode](#interruptmode9) | Yes | Yes | Audio interruption mode. | +| currentTime8+ | number | Yes | No | Current video playback position, in ms. | +| duration8+ | number | Yes | No | Video duration, in ms. The value **-1** indicates the live mode. | | state8+ | [VideoPlayState](#videoplaystate8) | Yes | No | Video playback state. | -| width8+ | number | Yes | No | Video width. | -| height8+ | number | Yes | No | Video height. | +| width8+ | number | Yes | No | Video width, in pixels. | +| height8+ | number | Yes | No | Video height, in pixels. | ### setDisplaySurface8+ @@ -1334,7 +1366,7 @@ videoPlayer.setSpeed(speed).then() => { selectBitrate(bitrate:number, callback: AsyncCallback\): void -Selects a bit rate from available bit rates. This API uses a callback to return the result. The available bit rates can be obtained by calling [availableBitrateCollected](#on('availableBitrateCollected')9+). +Selects a bit rate from available ones, which can be obtained by calling [availableBitratesCollect](#onavailablebitratescollect9). This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Multimedia.Media.VideoPlayer @@ -1362,7 +1394,7 @@ videoPlayer.selectBitrate(bitrate, (err, result) => { selectBitrate(bitrate:number): Promise\ -Selects a bit rate from available bit rates. This API uses a promise to return the result. The available bit rates can be obtained by calling [availableBitrateCollected](#on('availableBitrateCollected')9+). +Selects a bit rate from available ones, which can be obtained by calling [availableBitratesCollect](#onavailablebitratescollect9). This API uses a promise to return the result. **System capability**: SystemCapability.Multimedia.Media.VideoPlayer @@ -1401,7 +1433,7 @@ Subscribes to the video playback completion event. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ----------------------------------------------------------- | -| type | string | Yes | Event type, which is 'playbackCompleted' in this case.| +| type | string | Yes | Event type, which is **'playbackCompleted'** in this case. | | callback | function | Yes | Callback invoked when the event is triggered. | **Example** @@ -1424,7 +1456,7 @@ Subscribes to the video buffering update event. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'bufferingUpdate' in this case. | +| type | string | Yes | Event type, which is **'bufferingUpdate'** in this case. | | callback | function | Yes | Callback invoked when the event is triggered.
When [BufferingInfoType](#bufferinginfotype8) is set to **BUFFERING_PERCENT** or **CACHED_DURATION**, **value** is valid. Otherwise, **value** is fixed at **0**.| **Example** @@ -1448,7 +1480,7 @@ Subscribes to the frame rendering start event. | Name | Type | Mandatory| Description | | -------- | --------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'startRenderFrame' in this case.| +| type | string | Yes | Event type, which is **'startRenderFrame'** in this case. | | callback | Callback\ | Yes | Callback invoked when the event is triggered. | **Example** @@ -1471,7 +1503,7 @@ Subscribes to the video width and height change event. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'videoSizeChanged' in this case.| +| type | string | Yes | Event type, which is **'videoSizeChanged'** in this case. | | callback | function | Yes | Callback invoked when the event is triggered. **width** indicates the video width, and **height** indicates the video height. | **Example** @@ -1487,7 +1519,7 @@ videoPlayer.on('videoSizeChanged', (width, height) => { on(type: 'error', callback: ErrorCallback): void -Subscribes to the video playback error event. +Subscribes to video playback error events. After an error event is reported, you must handle the event and exit the playback. **System capability**: SystemCapability.Multimedia.Media.VideoPlayer @@ -1495,7 +1527,7 @@ Subscribes to the video playback error event. | Name | Type | Mandatory| Description | | -------- | ------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'error' in this case.
The 'error' event is triggered when an error occurs during video playback.| +| type | string | Yes | Event type, which is **'error'** in this case.
The **'error'** event is triggered when an error occurs during video playback. | | callback | ErrorCallback | Yes | Callback invoked when the event is triggered. | **Example** @@ -1506,12 +1538,12 @@ videoPlayer.on('error', (error) => { // Set the 'error' event callback. console.info(`video error called, errCode is ${error.code}`); // Print the error code. console.info(`video error called, errMessage is ${error.message}`);// Print the detailed description of the error type. }); -videoPlayer.setVolume(3); // Set volume to an invalid value to trigger the 'error' event. +videoPlayer.url = 'fd://error'; // Set an incorrect URL to trigger the 'error' event. ``` -### on('availableBitrateCollected')9+ +### on('availableBitratesCollect')9+ -on(type: 'availableBitrateCollected', callback: (bitrates: Array) => void): void +on(type: 'availableBitratesCollect', callback: (bitrates: Array\) => void): void Subscribes to the video playback bit rate reporting event. @@ -1521,15 +1553,15 @@ Subscribes to the video playback bit rate reporting event. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'availableBitrateCollected' in this case. This event is reported only once when the playback starts.| -| callback | function | Yes | Callback used to return supported bit rates, in an array. | +| type | string | Yes | Event type, which is **'availableBitratesCollect'** in this case. This event is reported only once when the playback starts.| +| callback | function | Yes | Callback used to return supported bit rates, in an array. | **Example** ```js -videoPlayer.on('availableBitrateCollected', (bitrates) => { +videoPlayer.on('availableBitratesCollect', (bitrates) => { for (let i = 0; i < bitrates.length; i++) { - console.info('case availableBitrateCollected bitrates: ' + bitrates[i]); // Print bit rates. + console.info('case availableBitratesCollect bitrates: ' + bitrates[i]); // Print bit rates. } }); ``` @@ -1574,6 +1606,17 @@ Enumerates the video playback speeds, which can be passed in the **setSpeed** AP | SPEED_FORWARD_1_75_X | 3 | Plays the video at 1.75 times the normal speed.| | SPEED_FORWARD_2_00_X | 4 | Plays the video at 2.00 times the normal speed.| +## VideoScaleType9+ + +Enumerates the video scale modes. + +**System capability**: SystemCapability.Multimedia.Media.VideoPlayer + +| Name | Default Value| Description | +| ---------------------------- | ------ | ---------- | +| VIDEO_SCALE_TYPE_FIT | 0 | The video will be stretched to fit the window.| +| VIDEO_SCALE_TYPE_FIT_CROP| 1 | The video will be stretched to fit the window, without changing its aspect ratio. The content may be cropped. | + ## MediaDescription8+ ### [key : string] : Object @@ -1765,7 +1808,7 @@ Subscribes to the audio recording events. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type. The following events are supported: 'prepare'\|'start'\| 'pause' \| 'resume' \|'stop'\|'release'\|'reset'
- The 'prepare' event is triggered when the [prepare](#audiorecorder_prepare) API is called and the audio recording parameters are set.
- The 'start' event is triggered when the [start](#audiorecorder_start) API is called and audio recording starts.
- The 'pause' event is triggered when the [pause](#audiorecorder_pause) API is called and audio recording is paused.
- The 'resume' event is triggered when the [resume](#audiorecorder_resume) API is called and audio recording is resumed.
- The 'stop' event is triggered when the [stop](#audiorecorder_stop) API is called and audio recording stops.
- The 'release' event is triggered when the [release](#audiorecorder_release) API is called and the recording resource is released.
- The 'reset' event is triggered when the [reset](#audiorecorder_reset) API is called and audio recording is reset.| +| type | string | Yes | Event type. The following events are supported:
- 'prepare': triggered when the [prepare](#audiorecorder_prepare) API is called and the audio recording parameters are set.
- 'start': triggered when the [start](#audiorecorder_start) API is called and audio recording starts.
- 'pause': triggered when the [pause](#audiorecorder_pause) API is called and audio recording is paused.
- 'resume': triggered when the [resume](#audiorecorder_resume) API is called and audio recording is resumed.
- 'stop': triggered when the [stop](#audiorecorder_stop) API is called and audio recording stops.
- 'release': triggered when the [release](#audiorecorder_release) API is called and the recording resource is released.
- 'reset': triggered when the [reset](#audiorecorder_reset) API is called and audio recording is reset. | | callback | ()=>void | Yes | Callback invoked when the event is triggered. | **Example** @@ -1781,41 +1824,41 @@ let audioRecorderConfig = { uri : 'fd://xx', // The file must be created by the caller and granted with proper permissions. location : { latitude : 30, longitude : 130}, } -audioRecorder.on('error', (error) => { // Set the error event callback. +audioRecorder.on('error', (error) => { // Set the 'error' event callback. console.info(`audio error called, errName is ${error.name}`); console.info(`audio error called, errCode is ${error.code}`); console.info(`audio error called, errMessage is ${error.message}`); }); -audioRecorder.on('prepare', () => { // Set the prepare event callback. +audioRecorder.on('prepare', () => { // Set the 'prepare' event callback. console.log('prepare success'); - audioRecorder.start(); // Start recording and trigger the start event callback. + audioRecorder.start(); // Start recording and trigger the 'start' event callback. }); -audioRecorder.on('start', () => { // Set the start event callback. +audioRecorder.on('start', () => { // Set the 'start' event callback. console.log('audio recorder start success'); }); -audioRecorder.on('pause', () => { // Set the pause event callback. +audioRecorder.on('pause', () => { // Set the 'pause' event callback. console.log('audio recorder pause success'); }); -audioRecorder.on('resume', () => { // Set the resume event callback. +audioRecorder.on('resume', () => { // Set the 'resume' event callback. console.log('audio recorder resume success'); }); -audioRecorder.on('stop', () => { // Set the stop event callback. +audioRecorder.on('stop', () => { // Set the 'stop' event callback. console.log('audio recorder stop success'); }); -audioRecorder.on('release', () => { // Set the release event callback. +audioRecorder.on('release', () => { // Set the 'release' event callback. console.log('audio recorder release success'); }); -audioRecorder.on('reset', () => { // Set the reset event callback. +audioRecorder.on('reset', () => { // Set the 'reset' event callback. console.log('audio recorder reset success'); }); -audioRecorder.prepare(audioRecorderConfig) // Set recording parameters and trigger the prepare event callback. +audioRecorder.prepare(audioRecorderConfig) // Set recording parameters and trigger the 'prepare' event callback. ``` ### on('error') on(type: 'error', callback: ErrorCallback): void -Subscribes to the audio recording error event. +Subscribes to audio recording error events. After an error event is reported, you must handle the event and exit the recording. **System capability**: SystemCapability.Multimedia.Media.AudioRecorder @@ -1823,18 +1866,18 @@ Subscribes to the audio recording error event. | Name | Type | Mandatory| Description | | -------- | ------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'error' in this case.
The 'error' event is triggered when an error occurs during audio recording.| +| type | string | Yes | Event type, which is **'error'** in this case.
The **'error'** event is triggered when an error occurs during audio recording. | | callback | ErrorCallback | Yes | Callback invoked when the event is triggered. | **Example** ```js -audioRecorder.on('error', (error) => { // Set the error event callback. +audioRecorder.on('error', (error) => { // Set the 'error' event callback. console.info(`audio error called, errName is ${error.name}`); // Print the error name. console.info(`audio error called, errCode is ${error.code}`); // Print the error code. console.info(`audio error called, errMessage is ${error.message}`); // Print the detailed description of the error type. }); -audioRecorder.prepare(); // Do no set any parameter in prepare and trigger the error event callback. +audioRecorder.prepare(); // Do no set any parameter in prepare and trigger the 'error' event callback. ``` ## AudioRecorderConfig @@ -1978,7 +2021,7 @@ prepare(config: VideoRecorderConfig): Promise\; Sets video recording parameters in asynchronous mode. This API uses a promise to return the result. -**Required permissions:** ohos.permission.MICROPHONE and ohos.permission.CAMERA +**Required permissions:** ohos.permission.MICROPHONE **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -2109,7 +2152,7 @@ start(callback: AsyncCallback\): void; Starts video recording in asynchronous mode. This API uses a callback to return the result. -This API can be called only after [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) are called, because the data source must pass data to the surface first. +This API can be called only after [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface9) are called, because the data source must pass data to the surface first. **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -2138,7 +2181,7 @@ start(): Promise\; Starts video recording in asynchronous mode. This API uses a promise to return the result. -This API can be called only after [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) are called, because the data source must pass data to the surface first. +This API can be called only after [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface9) are called, because the data source must pass data to the surface first. **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -2273,7 +2316,7 @@ stop(callback: AsyncCallback\): void; Stops video recording in asynchronous mode. This API uses a callback to return the result. -To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) again. +To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface9) again. **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -2302,7 +2345,7 @@ stop(): Promise\; Stops video recording in asynchronous mode. This API uses a promise to return the result. -To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) again. +To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface9) again. **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -2381,7 +2424,7 @@ reset(callback: AsyncCallback\): void; Resets video recording in asynchronous mode. This API uses a callback to return the result. -To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) again. +To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface9) again. **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -2410,7 +2453,7 @@ reset(): Promise\; Resets video recording in asynchronous mode. This API uses a promise to return the result. -To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) again. +To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface9) again. **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -2435,7 +2478,7 @@ videoRecorder.reset().then(() => { on(type: 'error', callback: ErrorCallback): void -Subscribes to the video recording error event. +Subscribes to video recording error events. After an error event is reported, you must handle the event and exit the recording. **System capability**: SystemCapability.Multimedia.Media.VideoRecorder @@ -2443,13 +2486,13 @@ Subscribes to the video recording error event. | Name | Type | Mandatory| Description | | -------- | ------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type, which is 'error' in this case.
The 'error' event is triggered when an error occurs during video recording.| +| type | string | Yes | Event type, which is **'error'** in this case.
The **'error'** event is triggered when an error occurs during video recording. | | callback | ErrorCallback | Yes | Callback invoked when the event is triggered. | **Example** ```js -videoRecorder.on('error', (error) => { // Set the error event callback. +videoRecorder.on('error', (error) => { // Set the 'error event' callback. console.info(`audio error called, errName is ${error.name}`); // Print the error name. console.info(`audio error called, errCode is ${error.code}`); // Print the error code. console.info(`audio error called, errMessage is ${error.message}`); // Print the detailed description of the error type. @@ -2485,7 +2528,7 @@ Describes the video recording parameters. | profile | [VideoRecorderProfile](#videorecorderprofile9) | Yes | Video recording profile. | | rotation | number | No | Rotation angle of the recorded video. | | location | [Location](#location) | No | Geographical location of the recorded video. | -| url | string | Yes | Video output URL. Supported: fd://xx (fd number)
![](figures/en-us_image_url.png)
The file must be created by the caller and granted with proper permissions.| +| url | string | Yes | Video output URL. Supported: fd://xx (fd number)
![](figures/en-us_image_url.png)
**Required permissions**: ohos.permission.READ_MEDIA| ## AudioSourceType9+ diff --git a/en/application-dev/reference/apis/js-apis-missionManager.md b/en/application-dev/reference/apis/js-apis-missionManager.md index b981d28061d45feb313dbaf7ea0709d6f198e0e8..50057062701f1ddbe0b058dc79e957c1a47e63a3 100644 --- a/en/application-dev/reference/apis/js-apis-missionManager.md +++ b/en/application-dev/reference/apis/js-apis-missionManager.md @@ -362,6 +362,88 @@ Obtains the snapshot of a given mission. This API uses a promise to return the r }); ``` +## missionManager.getLowResolutionMissionSnapShot9+ + +getLowResolutionMissionSnapShot(deviceId: string, missionId: number, callback: AsyncCallback\): void; + +Obtains the low-resolution snapshot of a given mission. This API uses an asynchronous callback to return the result. + +**Required permission**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | missionId | number | Yes| Mission ID.| + | callback | AsyncCallback<[MissionSnapshot](js-apis-application-MissionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.| + +**Example** + + ```js + import missionManager from '@ohos.application.missionManager' + + missionManager.getMissionInfos("", 10, (error, missions) => { + console.log("getMissionInfos is called, error.code = " + error.code); + console.log("size = " + missions.length); + console.log("missions = " + JSON.stringify(missions)); + var id = missions[0].missionId; + + missionManager.getLowResolutionMissionSnapShot("", id, (error, snapshot) => { + console.log("getLowResolutionMissionSnapShot is called, error.code = " + error.code); + console.log("bundleName = " + snapshot.ability.bundleName); + }) + }) + ``` + + +## missionManager.getLowResolutionMissionSnapShot9+ + +getLowResolutionMissionSnapShot(deviceId: string, missionId: number): Promise\; + +Obtains the low-resolution snapshot of a given mission. This API uses a promise to return the result. + +**Required permission**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | missionId | number | Yes| Mission ID.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<[MissionSnapshot](js-apis-application-MissionSnapshot.md)> | Promise used to return the snapshot information obtained.| + +**Example** + + ```js + import missionManager from '@ohos.application.missionManager' + + var allMissions; + missionManager.getMissionInfos("",10).then(function(res){ + allMissions=res; + }).catch(function(err){console.log(err);}); + console.log("size = " + allMissions.length); + console.log("missions = " + JSON.stringify(allMissions)); + var id = allMissions[0].missionId; + + var snapshot = missionManager.getLowResolutionMissionSnapShot("", id).catch(function (err){ + console.log(err); + }); + ``` + ## missionManager.lockMission diff --git a/en/application-dev/reference/apis/js-apis-nfcController.md b/en/application-dev/reference/apis/js-apis-nfcController.md index 1261c9736020f44d2e03dd49cc1f7cd628383e43..c8a9d7cf699963e494c5f04c1d5e887e8795eb0f 100644 --- a/en/application-dev/reference/apis/js-apis-nfcController.md +++ b/en/application-dev/reference/apis/js-apis-nfcController.md @@ -1,6 +1,6 @@ # Standard NFC -Implements Near-Field Communication (NFC). +The **nfcController** module implements Near-Field Communication (NFC). > **NOTE**
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -19,6 +19,8 @@ isNfcAvailable(): boolean Checks whether NFC is available. +**System capability**: SystemCapability.Communication.NFC.Core + **Return value** | **Type**| **Description**| @@ -34,7 +36,7 @@ Opens NFC. **Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Return value** @@ -50,7 +52,7 @@ Closes NFC. **Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Return value** @@ -64,7 +66,7 @@ isNfcOpen(): boolean Checks whether NFC is open. -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Return value** @@ -78,7 +80,7 @@ getNfcState(): NfcState Obtains the NFC state. -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Return value** @@ -92,7 +94,7 @@ on(type: "nfcStateChange", callback: Callback<NfcState>): void Subscribes to NFC state changes. -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Parameter** @@ -109,7 +111,7 @@ off(type: "nfcStateChange", callback?: Callback<NfcState>): void Unsubscribes from the NFC state changes. -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Parameter** @@ -140,6 +142,8 @@ Unsubscribes from the NFC state changes. Enumerates the NFC states. +**System capability**: SystemCapability.Communication.NFC.Core + | Name| Default Value| Description| | -------- | -------- | -------- | | STATE_OFF | 1 | Off| diff --git a/en/application-dev/reference/apis/js-apis-nfcTag.md b/en/application-dev/reference/apis/js-apis-nfcTag.md index 75cfa6f5620c66bf0a8b3bb557f169edf6ed26b1..01315a62d6aecacea806cdecebc268ed1f571c84 100644 --- a/en/application-dev/reference/apis/js-apis-nfcTag.md +++ b/en/application-dev/reference/apis/js-apis-nfcTag.md @@ -1,78 +1,171 @@ # Standard NFC Tag -Manages Near-Field Communication (NFC) tags. +The **nfcTag** module provides methods for managing Near-Field Communication (NFC) tags. > **NOTE**
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. - ## **Modules to Import** -``` +```js import tag from '@ohos.nfc.tag'; ``` - ## tag.getNfcATag -getNfcATag(tagInfo: TagInfo): NfcATag +getNfcATag(tagInfo: [TagInfo](#taginfo9)): [NfcATag](js-apis-nfctech.md#nfcatag) Obtains an **NfcATag** object, which allows access to the tags that use the NFC-A technology. **Required permissions**: ohos.permission.NFC_TAG -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Return value** | **Type**| **Description**| | -------- | -------- | -| NfcATag | **NfcATag** object obtained.| +| [NfcATag](js-apis-nfctech.md#nfcatag) | **NfcATag** object obtained.| ## tag.getNfcBTag -getNfcBTag(tagInfo: TagInfo): NfcBTag +getNfcBTag(tagInfo: [TagInfo](#taginfo9)): [NfcBTag](js-apis-nfctech.md#nfcbtag) Obtains an **NfcBTag** object, which allows access to the tags that use the NFC-B technology. **Required permissions**: ohos.permission.NFC_TAG -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Return value** | **Type**| **Description** | | -------- | ---------------- | -| NfcBTag | **NfcBTag** object obtained.| +| [NfcBTag](js-apis-nfctech.md#nfcbtag) | **NfcBTag** object obtained.| ## tag.getNfcFTag -getNfcFTag(tagInfo: TagInfo): NfcFTag +getNfcFTag(tagInfo: [TagInfo](#taginfo9)): [NfcFTag](js-apis-nfctech.md#nfcftag) Obtains an **NfcFTag** object, which allows access to the tags that use the NFC-F technology. **Required permissions**: ohos.permission.NFC_TAG -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Return value** | **Type**| **Description** | | -------- | ---------------- | -| NfcFTag | **NfcFTag** object obtained.| +| [NfcFTag](js-apis-nfctech.md#nfcftag) | **NfcFTag** object obtained.| ## tag.getNfcVTag -getNfcVTag(tagInfo: TagInfo): NfcVTag +getNfcVTag(tagInfo: [TagInfo](#taginfo9)): [NfcVTag](js-apis-nfctech.md#nfcvtag) Obtains an **NfcVTag** object, which allows access to the tags that use the NFC-V technology. **Required permissions**: ohos.permission.NFC_TAG -**System capability**: SystemCapability.Communication.NFC +**System capability**: SystemCapability.Communication.NFC.Core **Return value** | **Type**| **Description** | | -------- | ---------------- | -| NfcVTag | **NfcVTag** object obtained.| +| [NfcVTag](js-apis-nfctech.md#nfcvtag) | **NfcVTag** object obtained.| + +## tag.getIsoDepTag9+ + +getIsoDepTag(tagInfo: [TagInfo](#taginfo9)): [IsoDepTag](js-apis-nfctech.md#isodeptag9 ) + +Obtains an **IsoDepTag** object, which allows access to the tags that use the ISO-DEP technology. + + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ---------- | ------------------| +| [IsoDepTag](js-apis-nfctech.md#isodeptag9) | **IsoDepTag** object obtained.| + +## tag.getNdefTag9+ + +getNdefTag(tagInfo: [TagInfo](#taginfo9)): [NdefTag](js-apis-nfctech.md#ndeftag9) + +Obtains an **NdefTag** object, which allows access to the tags in the NFC Data Exchange Format (NDEF). + + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ---------| -------------- | +| [NdefTag](js-apis-nfctech.md#ndeftag9) | **NdefTag** object obtained.| + +## tag.getMifareClassicTag9+ + +getMifareClassicTag(tagInfo: [TagInfo](#taginfo9)): [MifareClassicTag](js-apis-nfctech.md#mifareclassictag-9) + +Obtains a **MifareClassicTag** object, which allows access to the tags that use MIFARE Classic. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ----------------- | ------------------------| +| [MifareClassicTag](js-apis-nfctech.md#mifareclassictag-9) | **MifareClassicTag** object obtained.| + +## tag.getMifareUltralightTag9+ + +getMifareUltralightTag(tagInfo: [TagInfo](#taginfo9)): [MifareUltralightTag](js-apis-nfctech.md#mifareultralighttag9) + +Obtains a **MifareUltralightTag** object, which allows access to the tags that use MIFARE Ultralight. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| -------------------- | ---------------------------| +| [MifareUltralightTag](js-apis-nfctech.md#mifareultralighttag9) | **MifareUltralightTag** object obtained.| + +## tag.getNdefFormatableTag9+ + +getNdefFormatableTag(tagInfo: [TagInfo](#taginfo9)): [NdefFormatableTag](js-apis-nfctech.md#ndefformatabletag9) + +Obtains an **NdefFormatableTag** object, which allows access to the tags that are NDEF formattable. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| [NdefFormatableTag](js-apis-nfctech.md#ndefformatabletag) | **NdefFormatableTag** object obtained.| + +## TagInfo9+ + +Represents the NFC tag information. + +| **Name**| **Type**| **Description**| +| -------- | -------- | -------- | +| uid | string | UID of the tag.| +| technology | number[] | Technology supported by the tag.| +| extrasData | PacMap[] | Additional information about the tag.| +| tagRfDiscId | number | RF discovery ID of the tag.| +| remoteTagService | rpc.RemoteObject | RPC remote object of the tag service.| +| supportedProfiles | number[] | Profiles supported by the tag.| diff --git a/en/application-dev/reference/apis/js-apis-nfctech.md b/en/application-dev/reference/apis/js-apis-nfctech.md new file mode 100644 index 0000000000000000000000000000000000000000..eb7d01dda3b5bcf8c88a45981d661aacf6d4e4f4 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-nfctech.md @@ -0,0 +1,1820 @@ +# Standard NFC Tag Technologies + +The **nfctech** module provides methods for reading and writing tags that use different Near-Field Communication (NFC) technologies. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## **Modules to Import** + +```js +import tag from '@ohos.nfc.tag'; +``` + +## NfcATag + +Provides access to NFC-A (ISO 14443-3A) properties and I/O operations. **NfcATag** inherits from **TagSession**. + +**TagSession** is the base class of all NFC tag technologies. It provides common interfaces for establishing connections and transferring data. For more details, see [TagSession](js-apis-tagSession.md). + +The following describes the unique interfaces of **NfcATag**. + +### NfcATag.getSak + +getSak(): number + +Obtains the SAK value of this NFC-A tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number | SAK value obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let sak = tag.getNfcATag(taginfo).getSak(); +console.log("sak:" +sak); +``` + +### NfcATag.getAtqa + +getAtqa(): number[] + +Obtains the ATQA value of this NFC-A tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number[] | ATQA value obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let atqa = tag.getNfcATag(taginfo).getAtqa(); +console.log("atqa:" +atqa); +``` + +## NfcBTag + +Provides access to NFC-B (ISO 14443-3B) properties and I/O operations. **NfcBTag** inherits from **TagSession**. + +**TagSession** is the base class of all NFC tag technologies. It provides common interfaces for establishing connections and transferring data. For more details, see [TagSession](js-apis-tagSession.md). + +The following describes the unique interfaces of **NfcBTag**. + +### NfcBTag.getRespAppData + +getRespAppData(): number[] + +Obtains the application data of this NFC-B tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number[] | Application data obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let appData = tag.getNfcBTag(taginfo).getRespAppData(); +console.log("appData:" +appData); +``` + +### NfcBTag.getRespProtocol + +getRespProtocol(): number[] + +Obtains protocol information of this NFC-B tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number[] | Protocol information obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let protocol = tag.getNfcBTag(taginfo).getRespProtocol(); +console.log("appData:" +protocol); +``` + +## NfcFTag + +Provides access to NFC-F(JIS 6319-4) properties and I/O operations. **NfcFTag** inherits from **TagSession**. + +**TagSession** is the base class of all NFC tag technologies. It provides common interfaces for establishing connections and transferring data. For more details, see [TagSession](js-apis-tagSession.md). + +The following describes the unique interfaces of **NfcFTag**. + +### NfcFTag.getSystemCode + +getSystemCode(): number[] + +Obtains the system code from the tag instance. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number[] | System code obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let systemCode = tag.getNfcFTag(taginfo).getSystemCode(); +console.log("systemCode:" +systemCode); +``` + +### NfcFTag.getPmm + +getPmm(): number[] + +Obtains the PMm (consisting of the IC code and manufacturer parameters) information from the tag instance. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number[] | PMm information obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let pmm = tag.getNfcFTag(taginfo).getPmm(); +console.log("pmm:" +pmm); +``` + +## NfcVTag + +Provides access to NFC-V (ISO 15693) properties and I/O operations. **NfcVTag** inherits from **TagSession**. + +**TagSession** is the base class of all NFC tag technologies. It provides common interfaces for establishing connections and transferring data. For more details, see [TagSession](js-apis-tagSession.md). + +The following describes the unique interfaces of **NfcVTag**. + +### NfcvTag.getResponseFlags + +getResponseFlags(): number + +Obtains the response flags from the tag instance. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number | Response flags obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let flags = tag.getNfcVTag(taginfo).getResponseFlags(); +console.log("flags:" +flags); +``` + +### NfcvTag.getDsfId + +getDsfId(): number + +Obtains the data storage format identifier (DSFID) from the tag instance. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number | DSFID obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let dsfId = tag.getNfcVTag(taginfo).getDsfId(); +console.log("dsfId:" +dsfId); +``` + +## IsoDepTag9+ + +Provides access to ISO-DEP (ISO 14443-4) properties and I/O operations. **IsoDepTag** inherits from **TagSession**. + +**TagSession** is the base class of all NFC tag technologies. It provides common interfaces for establishing connections and transferring data. For more details, see [TagSession](js-apis-tagSession.md). + +The following describes the unique interfaces of **IsoDepTag**. + +### IsoDepTag.getHistoricalBytes9+ + +getHistoricalBytes(): string + +Obtains the historical bytes of this tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| string | Historical bytes obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let historicalBytes = tag.getIsoDepTag(taginfo).getHistoricalBytes(); +console.log("historicalBytes:" +historicalBytes); +``` + +### IsoDepTag.getHiLayerResponse9+ + +getHiLayerResponse(): string + +Obtains the HiLayer response of this tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| string | HiLayer response obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let hiLayerResponse = tag.getIsoDepTag(taginfo).getHiLayerResponse(); +console.log("hiLayerResponse:" +hiLayerResponse); +``` + +### IsoDepTag.isExtendedApduSupported9+ + +isExtendedApduSupported(): Promise<boolean> + +Checks whether an extended application protocol data unit (APDU) is supported. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise<boolean> | Promise used to return the result. If the extended APDU is supported, **true** is returned; otherwise, **false** is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.getIsoDepTag(taginfo).isExtendedApduSupported().then(function (has) { + console.log('has: ' + has) +}) +``` + +### IsoDepTag.isExtendedApduSupported9+ + +isExtendedApduSupported(callback: AsyncCallback\): void + +Checks whether an extended application protocol data unit (APDU) is supported. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the extended APDU is supported, **true** is returned; otherwise, **false** is returned.| + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.getIsoDepTag(taginfo).isExtendedApduSupported(function (error, has) { + console.log(JSON.stringify(error)) + console.log('has: ' + has) +}) +``` + +## NdefTag9+ + +Provides access to the tags in the NFC Data Exchange Format (NDEF). **NdefTag** inherits from **TagSession**. + +**TagSession** is the base class of all NFC tag technologies. It provides common interfaces for establishing connections and transferring data. For more details, see [TagSession](js-apis-tagSession.md). + +The following describes the unique interfaces of **NdefTag**. + +### NdefTag.createNdefMessage9+ + +createNdefMessage(data: string): [NdefMessage](#ndefmessage9) + +Creates an NDEF message using raw bytes. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| **Name**| **Type**| **Mandatory**| **Description**| +| -------- | -------- | -------- | -------- | +| data | string | Yes| Raw bytes of the string type.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| [NdefMessage](#ndefmessage9) | NDEF message created.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let NdefMessage = tag.NdefTag(taginfo).createNdefMessage(data); +``` + +## NdefMessage9+ + +### NdefMessage.getNdefRecords9+ + +getNdefRecords(): [NdefRecord](#ndefrecord9)[ ] + +Obtains all NDEF records. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| [NdefRecord](#ndefrecord9)[ ] | All records obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let NdefRecord = tag.NdefTag(taginfo).getNdefRecords(); +``` + +## NdefRecord9+ + +| **Name**| **Type**| **Description**| +| -------- | -------- | -------- | +| tnf | number | UID of the tag.| +| [rtdType](#rtdtype9) | string | NFC Record Type Definition (RTD) supported by the tag.| +| id | string | Additional information about the tag.| +| payload | string | RF discovery ID of the tag.| + +## RtdType9+ + +| **Name**| **Type**| **Description**| +| -------- | -------- | -------- | +| RTD_TEXT | 'T' | Text information.| +| RTD_URI | 'U' | Network address, email, or phone number.| + +### NdefTag.createNdefMessage9+ + +createNdefMessage(ndefRecords: NdefRecord[]): [NdefMessage](#ndefmessage9) + +Creates an NDEF message using the NDEF records. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** +| **Name**| **Type**| **Mandatory**| **Description**| +| -------- | -------- | -------- | -------- | +| ndefRecords | [NdefRecord](#ndefrecord9)[] | Yes| A list of NDEF records.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| [NdefMessage](#ndefmessage9) | NDEF message created.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let NdefMessage = tag.NdefTag(taginfo).createNdefMessage(ndefRecords); +``` + +### NdefTag.getNdefTagType9+ + +getNdefTagType(): NfcForumType + +Obtains the type of this NDEF tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| [NfcForumType](#nfcforumtype9) | NDEF tag type obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let NfcForumType = tag.NdefTag(taginfo).getNdefTagType(); +``` + +### NdefTag.getNdefMessage9+ + +getNdefMessage(): NdefMessage + +Obtains the NDEF message from the tag discovered. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| [NdefMessage](#ndefmessage9) | NDEF message created.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let NdefMessage = tag.NdefTag(taginfo).getNdefMessage(); +``` + +### NdefTag.isNdefWritable9+ + +isNdefWritable(): Promise<boolean> + +Checks whether the NDEF tag is writable. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise<boolean> | Promise used to return the result. If the tag is writable, **true** is returned; otherwise, **false** is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefTag(taginfo).isNdefWritable().then(function (has) { + console.log(JSON.stringify(has)) +}) +``` + +### NdefTag.isNdefWritable9+ + +isNdefWritable(callback: AsyncCallback<boolean>): void; + +Checks whether the NDEF tag is writable. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the tag is writable, **true** is returned; otherwise, **false** is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefTag(taginfo).isNdefWritable(function (error, has) { + console.log(JSON.stringify(error)) + console.log('has: ' + has) +}) +``` + +### NdefTag.readNdef9+ + +readNdef(): Promise\ + +Reads the NDEF message from this tag. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\<[NdefMessage](#ndefmessage9)> | Promise used to return the message read.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefTag(taginfo).readNdef().then(function (ndefMessage) { + console.log(JSON.stringify(ndefMessage)) +}) +``` + +### NdefTag.readNdef9+ + +readNdef(callback: AsyncCallback\<[NdefMessage](#ndefmessage9)>): void + +Reads the NDEF message from this tag. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| callback | AsyncCallback\<[NdefMessage](#ndefmessage9)> | Yes | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefTag(taginfo).readNdef(function (error, ndefMessage) { + console.log(JSON.stringify(error)) + console.log('ndefMessage: ' + ndefMessage) +}) +``` + +### NdefTag.writeNdef9+ + +writeNdef(msg: NdefMessage): Promise\; + +Write an NDEF message to this tag. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| msg | NdefMessage | Yes | NDEF message to write.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If **0** is returned, the operation is successful. If the operation fails, an error code is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +NdefTag.writeNdef(msg).then(function (netHandle) { + console.log(JSON.stringify(netHandle)) +}) +``` + +### NdefTag.writeNdef9+ + +writeNdef(msg: NdefMessage, callback: AsyncCallback\): void + +Write an NDEF message to this tag. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| msg | NdefMessage | Yes | NDEF message to write.| +| callback | AsyncCallback\ | Yes | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefTag(taginfo).write(msg, function (error, has) { + console.log(JSON.stringify(error)) + console.log('has: ' + has) +}) +``` + +### NdefTag.canSetReadOnly9+ + +canSetReadOnly(): Promise\ + +Checks whether this NDEF tag can be set to read-only. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise<boolean> | Promise used to return the result. If the tag can be set to read-only, **true** is returned; otherwise, **false** is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefTag(taginfo).canSetReadOnly().then(function (has) { + console.log(JSON.stringify(has)) +}) +``` + +### NdefTag.canSetReadOnly9+ + +canSetReadOnly()(callback: AsyncCallback<boolean>): void; + +Checks whether this NDEF tag can be set to read-only. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the tag can be set to read-only, **true** is returned; otherwise, **false** is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefTag(taginfo).canSetReadOnly(function (error, has) { + console.log(JSON.stringify(error)) + console.log('has: ' + has) +}) +``` + +### NdefTag.setReadOnly9+ + +setReadOnly(): Promise\ + +Sets this NDEF tag to read-only. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise<number> | Promise used to return the result. If the operation is successful, **0** is returned; otherwise, an error code is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefTag(taginfo).setReadOnly().then(function (errcode) { + console.log(JSON.stringify(errcode)) +}) +``` + +### NdefTag.setReadOnly9+ + +setReadOnly(callback: AsyncCallback): void + +Sets this NDEF tag to read-only. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefTag(taginfo).setReadOnly(function (error, errcode) { + console.log(JSON.stringify(error)) + console.log('has: ' + errcode) +}) +``` + +### NdefTag.getNdefTagTypeString9+ + +getNdefTagTypeString(type: [NfcForumType](#nfcforumtype9)): string + +Converts the NFC Forum Type to a byte array defined in the NFC Forum. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| type | [NfcForumType](#nfcforumtype9) | Yes | NFC Forum Type.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| string | Byte array obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let ndefTypeString= tag.NdefTag(taginfo).getNdefTagTypeString(type); +``` + +## NfcForumType9+ + +| **Name**| **Type**| **Description**| +| -------- | -------- | -------- | +| NFC_FORUM_TYPE_1 | 1 | NFC Forum Type 1.| +| NFC_FORUM_TYPE_2 | 2 | NFC Forum Type 2.| +| NFC_FORUM_TYPE_3 | 3 | NFC Forum Type 3.| +| NFC_FORUM_TYPE_4 | 4 | NFC Forum Type 4.| +| MIFARE_CLASSIC | 101 | MIFARE Classic.| + +## MifareClassicTag 9+ + +Provides access to MIFARE Classic properties and I/O operations. **MifareClassicTag** inherits from **TagSession**. + +**TagSession** is the base class of all NFC tag technologies. It provides common interfaces for establishing connections and transferring data. For more details, see [TagSession](js-apis-tagSession.md). + +The following describes the unique interfaces of **MifareClassicTag**. + +### MifareClassicTag.authenticateSector9+ + +authenticateSector(sectorIndex: number, key: number[], isKeyA: boolean): Promise\ + +Authenticates a sector using the key. The sector can be accessed only after the authentication is successful. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| sectorIndex | number | Yes | Index of the sector to authenticate.| +| key | number[]| Yes | Key (6 bytes) used for authentication.| +| isKeyA | boolean | Yes | Whether the key is key A. The value **true** indicates key A, and **false** indicates key B.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If the authentication is successful, **true** is returned. Otherwise, **false** is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).authenticateSector(sectorIndex, key).then(function (isKeyA) { + console.log(JSON.stringify(isKeyA)) + }) +``` + +### MifareClassicTag.authenticateSector9+ + +authenticateSector(sectorIndex: number, key: number[], isKeyA: boolean, callback: AsyncCallback): void + +Authenticates a sector using the key. The sector can be accessed only after the authentication is successful. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| sectorIndex | number | Yes | Index of the sector to authenticate.| +| key | number[]| Yes | Key (6 bytes) used for authentication.| +| isKeyA | boolean | Yes | Whether the key is key A. The value **true** indicates key A, and **false** indicates key B.| +| callback | AsyncCallback\ | Yes | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).authenticateSector(sectorIndex, key, function (error, has) { + console.log(JSON.stringify(error)) + console.log('has: ' + has) +}) +``` + +### MifareClassicTag.readSingleBlock9+ + +readSingleBlock(blockIndex: number): Promise\ + +Reads a block on the tag. The size of a block is 16 bytes. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the block to read.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the block data read.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +let data = "xxx"; +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).readSingleBlock(blockIndex).then(function (data){ + console.log('data: ' + data) + }) +``` + +### MifareClassicTag.readSingleBlock9+ + +readSingleBlock(blockIndex: number, callback: AsyncCallback\): void + +Reads a block on the tag. The size of a block is 16 bytes. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the block to read.| +| callback | AsyncCallback\ | Yes | Callback invoked to return the block read.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +let data = "xxx"; +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).readSingleBlock(blockIndex, function (error, data) { + console.log(JSON.stringify(error)) + console.log('data: ' + data) +}) +``` + +### MifareClassicTag.writeSingleBlock9+ + +writeSingleBlock(blockIndex: number, data: string): Promise\ + +Writes data to a block on the tag. The size of a block is 16 bytes. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the target block.| +| data | string | Yes | Data to write.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If **0** is returned, the operation is successful. If the operation fails, an error code is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +let data = "xxx"; +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).writeSingleBlock(blockIndex, data).then(function (errcode){ + console.log(JSON.stringify(errcode)) + }) +``` + +### MifareClassicTag.writeSingleBlock9+ + +writeSingleBlock(blockIndex: number, data: string, callback: AsyncCallback\): void + +Writes data to a block on the tag. The size of a block is 16 bytes. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the target block.| +| data | string | Yes | Data to write.| +| callback | AsyncCallback\ | Yes | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +let data = "xxx"; +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).writeSingleBlock(blockIndex, data, function (error, errcode) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(errcode)) +}) +``` + +### MifareClassicTag.incrementBlock9+ + +incrementBlock(blockIndex: number, value: number): Promise\ + +Increments a block with data. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the block to increment.| +| value | number | Yes | Block data to increment. The value is a non-negative number.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If **0** is returned, the operation is successful. If the operation fails, an error code is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).incrementBlock(blockIndex, value).then(function (errcode){ + console.log(JSON.stringify(errcode)) + }) +``` + +### MifareClassicTag.incrementBlock9+ + +incrementBlock(blockIndex: number, value: number, callback: AsyncCallback\): void + +Increments a block with data. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the block to increment.| +| value | number | Yes | Block data to increment. The value is a non-negative number.| +| callback | AsyncCallback\ | Yes | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).incrementBlock(blockIndex, value, function (error, errcode) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(errcode)) +}) +``` + +### MifareClassicTag.decrementBlock9+ + +decrementBlock(blockIndex: number, value: number): Promise\ + +Decrements a block with data. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the block to decrement.| +| value | number | Yes | Block data to decrement. The value is a non-negative number.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If **0** is returned, the operation is successful. If the operation fails, an error code is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).decrementBlock(blockIndex, value).then(function (errcode){ + console.log(JSON.stringify(errcode)) + }) +``` + +### MifareClassicTag.decrementBlock9+ + +decrementBlock(blockIndex: number, value: number, callback: AsyncCallback\): void + +Decrements a block with data. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the block to decrement.| +| value | number | Yes | Block data to decrement. The value is a non-negative number.| +| callback | AsyncCallback\ | Yes | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).decrementBlock(blockIndex, value, function (error, errcode) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(errcode)) +}) +``` + +### MifareClassicTag.transferToBlock9+ + +transferToBlock(blockIndex: number): Promise\ + +Copies data from the register to a block. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the destination block.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If **0** is returned, the operation is successful. If the operation fails, an error code is returned.| + +**Example** + +```js + +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).transferToBlock(blockIndex).then(function (errcode){ + console.log(JSON.stringify(errcode)) + }) +``` + +### MifareClassicTag.transferToBlock + +transferToBlock(blockIndex: number, callback: AsyncCallback\): void + +Copies data from the register to a block. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the destination block.| +| callback | AsyncCallback\ | Yes | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).transferToBlock(blockIndex, function (error, errcode) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(errcode)) +}) +``` + +### MifareClassicTag.restoreFromBlock9+ + +restoreFromBlock(blockIndex: number): Promise\ + +Copies data from a block to the register. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the source block.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If **0** is returned, the operation is successful. If the operation fails, an error code is returned.| + +**Example** + +```js + +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).restoreFromBlock(blockIndex).then(function (errcode){ + console.log(JSON.stringify(errcode)) + }) +``` + +### MifareClassicTag.restoreFromBlock9+ + +restoreFromBlock(blockIndex: number, callback: AsyncCallback\): void + +Copies data from a block to the register. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the source block.| +| callback | AsyncCallback\ | Yes | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareClassicTag(taginfo).restoreFromBlock(blockIndex, function (error, errcode) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(errcode)) +}) +``` + +### MifareClassicTag.getSectorCount9+ + +getSectorCount(): number + +Obtains the number of sectors in this MIFARE Classic tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number | Number of sectors obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let setorCount = tag.MifareClassicTag(taginfo).getSectorCount(); +``` + +### MifareClassicTag.getBlockCountInSector9+ + +getBlockCountInSector(sectorIndex: number): number + +Obtains the number of blocks in a sector. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| sectorIndex | number | Yes | Index of the sector.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number | Number of blocks obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let blockNumber = tag.MifareClassicTag(taginfo).getBlockCountInSector(sectorIndex); +``` + +### MifareClassicTag.getType9+ + +getType(): [MifareClassicType](#mifareclassictype9) + +Obtains the type of this MIFARE Classic tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| [MifareClassicType](#mifareclassictype9) | Type of the MIFARE Classic tag obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let type = tag.MifareClassicTag(taginfo).getType(); +``` + +### MifareClassicTag.getTagSize9+ + +getTagSize(): number + +Obtains the tag size (in bytes). For details, see [MifareTagSize](#mifaretagsize9). + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number | Tag size obtained, in bytes. For details, see [MifareTagSize](#mifaretagsize9).| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let size = tag.MifareClassicTag(taginfo).getTagSize(); +``` + +## MifareClassicType9+ + +| **Name**| **Value**| **Description**| +| -------- | -------- | -------- | +| TYPE_UNKNOWN | -1 | Unknown type.| +| TYPE_CLASSIC | 0 | MIFARE Classic.| +| TYPE_PLUS | 1 | MIFARE Plus.| +| TYPE_PRO | 2 | MIFARE Pro.| + +## MifareTagSize9+ + +| **Name**| **Value**| **Description**| +| -------- | -------- | -------- | +| MC_SIZE_MINI | 320 | Each tag has five sectors, and each sector has four blocks.| +| MC_SIZE_1K | 1024 | Each tag has 16 sectors, and each sector has four blocks.| +| MC_SIZE_2K | 2048 | Each tag has 32 sectors, and each sector has four blocks.| +| MC_SIZE_4K | 4096 | Each tag has 40 sectors, and each sector has four blocks.| + +### MifareClassicTag.isEmulatedTag9+ + +isEmulatedTag(): boolean + +Checks whether the tag is an emulated tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| boolean |Returns **true** if the tag is an emulated tag; returns **false** otherwise.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let isEmulated = tag.MifareClassicTag(taginfo).isEmulatedTag(); +``` + +### MifareClassicTag.getBlockIndex9+ + +getBlockIndex(sectorIndex: number): number + +Obtains the first block of a sector. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| sectorIndex | number | Yes | Index of the sector.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number | Index of the first block obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let index = tag.MifareClassicTag(taginfo).getBlockIndex(sectorIndex); +``` + +### MifareClassicTag.getSectorIndex9+ + +getSectorIndex(blockIndex: number): number + +Obtains the index of a sector that contains the specified block. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| blockIndex | number | Yes | Index of the block contained in the sector.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number | Index of the sector obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let index = tag.MifareClassicTag(taginfo).getSectorIndex(blockIndex); +``` + +## MifareUltralightTag9+ + +Provides access to MIFARE Ultralight properties and I/O operations. **MifareUltralightTag** inherits from **TagSession**. + +**TagSession** is the base class of all NFC tag technologies. It provides common interfaces for establishing connections and transferring data. For more details, see [TagSession](js-apis-tagSession.md). + +The following describes the unique interfaces of **MifareUltralightTag**. + +### MifareUltralightTag.readMultiplePages9+ + +readMultiplePages(pageIndex: number): Promise\ + +Reads multiple pages. The size of each page is 4 bytes. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | ------------------------------ | +| pageIndex | number | Yes | Indexes of the pages to read.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the data read.| + +**Example** + +```js + +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareUltralightTag(taginfo).readMultiplePages(pageIndex).then(function (data){ + console.log("data: " + data) + }) +``` + +### MifareUltralightTag.readMultiplePages9+ + +readMultiplePages(pageIndex: number, callback: AsyncCallback\): void + +Reads multiple pages. The size of each page is 4 bytes. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| pageIndex | number | Yes | Indexes of the pages to read.| +| callback | AsyncCallback\ | Yes | Callback invoked to return the data read.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareUltralightTag(taginfo).readMultiplePages(pageIndex, function (error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) +``` + +### MifareUltralightTag.writeSinglePages9+ + +writeSinglePages(pageIndex: number, data: string): Promise\ + +Writes a page of data. The size of each page is 4 bytes. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| pageIndex | number | Yes | Index of the page.| +| data | string | Yes | Data to write.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If **0** is returned, the operation is successful. If the operation fails, an error code is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareUltralightTag(taginfo).writeSinglePages(pageIndex, data).then(function (errcode){ + console.log(JSON.stringify(errcode)) + }) +``` + +### MifareUltralightTag.writeSinglePages9+ + +writeSinglePages(pageIndex: number, data: string, callback: AsyncCallback\): void + +Writes a page of data. The size of each page is 4 bytes. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | ------------------------ | +| pageIndex | number | Yes | Index of the page.| +| data | string | Yes | Data to write.| +| callback|AsyncCallback\ |Yes| Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.MifareUltralightTag(taginfo).writeSinglePages(pageIndex, data, function (error, errcode) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(errcode)) +}) +``` + +### MifareUltralightTag.getType9+ + +getType(): MifareUltralightType + +Obtains the MIFARE Ultralight tag type, in bytes. For details, see [MifareUltralightType](#mifareultralighttype9). + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| MifareUltralightType | Type of the MIFARE Ultralight tag. For details, see [MifareUltralightType](#mifareultralighttype9).| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let type = tag.MifareUltralightType(taginfo).getType(); +``` + +### MifareUltralightType9+ + +| **Name**| **Value**| **Description**| +| -------- | -------- | -------- | +| TYPE_UNKOWN | -1 | Unknown type.| +| TYPE_ULTRALIGHT | 1 | MIFARE Ultralight.| +| TYPE_ULTRALIGHT_C | 2 | MIFARE Ultralight C.| + +## NdefFormatableTag9+ + +Provides methods for operating NDEF formattable tags. **NdefFormatableTag** inherits from **TagSession**. + +**TagSession** is the base class of all NFC tag technologies. It provides common interfaces for establishing connections and transferring data. For more details, see [TagSession](js-apis-tagSession.md). + +The following describes the unique interfaces of **NdefFormatableTag**. + +### NdefFormatableTag.format9+ + +format(message: [NdefMessage](#ndefmessage9)): Promise\ + +Formats this tag as an NDEF tag, and writes an NDEF message to the tag. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| message | [NdefMessage](#ndefmessage9) | Yes | NDEF message to write when the formatting is successful. If it is **null**, the tag is formatted only and no data will be written.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If **0** is returned, the operation is successful. If the operation fails, an error code is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefFormatableTag(taginfo).format(message).then(function (errcode){ + console.log(JSON.stringify(errcode)) + }) +``` + +### NdefFormatableTag.format9+ + +format(message: [NdefMessage](#ndefmessage9), callback: AsyncCallback\): void + +Formats this tag as an NDEF tag, and writes an NDEF message to the tag. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| message | [NdefMessage](#ndefmessage9) | Yes | NDEF message to write when the formatting is successful. If it is **null**, the tag is formatted only and no data will be written.| +| callback: AsyncCallback\ | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefFormatableTag(taginfo).format(message, function (error, errcode) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(errcode)) +}) +``` + +### NdefFormatableTag.formatReadOnly9+ + +formatReadOnly(message: [NdefMessage](#ndefmessage9)): Promise\ + +Formats this tag as an NDEF tag, writes an NDEF message to the NDEF tag, and then sets the tag to read-only. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| message | [NdefMessage](#ndefmessage9) | Yes | NDEF message to write when the formatting is successful. If it is **null**, the tag is formatted only and no data will be written.| + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| Promise\ | Promise used to return the result. If **0** is returned, the operation is successful. If the operation fails, an error code is returned.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefFormatableTag(taginfo).formatReadOnly(message).then(function (errcode){ + console.log(JSON.stringify(errcode)) + }) +``` + +### NdefFormatableTag.formatReadOnly9+ + +formatReadOnly(message: [NdefMessage](#ndefmessage9), callback: AsyncCallback\): void + +Formats this tag as an NDEF tag, writes an NDEF message to the NDEF tag, and then sets the tag to read-only. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| message | [NdefMessage](#ndefmessage9) | Yes | NDEF message to write when the formatting is successful. If it is **null**, the tag is formatted only and no data will be written.| +| callback: AsyncCallback\ | Callback invoked to return the result.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +tag.NdefFormatableTag(taginfo).formatReadOnly(message, function (error, errcode) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(errcode)) +}) +``` diff --git a/en/application-dev/reference/apis/js-apis-notification.md b/en/application-dev/reference/apis/js-apis-notification.md index 7912809087579d64ca726be1b9ada1c8ea0129fb..1e9fa33963ed6eb07302ddfbb9db44973e9be4d4 100644 --- a/en/application-dev/reference/apis/js-apis-notification.md +++ b/en/application-dev/reference/apis/js-apis-notification.md @@ -1,6 +1,11 @@ # Notification +The **Notification** module provides notification management capabilities, covering notifications, notification slots, notification subscription, notification enabled status, and notification badge status. + +Generally, only system applications have the permission to subscribe to and unsubscribe from notifications. + > **NOTE**
+> > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -21,7 +26,7 @@ Publishes a notification. This API uses an asynchronous callback to return the r | Name | Readable| Writable| Type | Mandatory| Description | | -------- | ---- | ---- | ------------------------------------------- | ---- | ------------------------------------------- | -| request | Yes | No |[NotificationRequest](#notificationrequest) | Yes | Notification to publish.| +| request | Yes | No |[NotificationRequest](#notificationrequest) | Yes | **NotificationRequest** object.| | callback | Yes | No |AsyncCallback\ | Yes | Callback used to return the result. | **Example** @@ -85,13 +90,15 @@ Publishes a notification. This API uses an asynchronous callback to return the r **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** | Name | Readable| Writable| Type | Mandatory| Description | | -------- | ---- | ---- | ----------------------------------------- | ---- | ------------------------------------------- | -| request | Yes | No |[NotificationRequest](#notificationrequest) | Yes | Notification to publish.| +| request | Yes | No |[NotificationRequest](#notificationrequest) | Yes | **NotificationRequest** object.| | userId | Yes | No |number | Yes | ID of the user who receives the notification. | | callback | Yes | No |AsyncCallback\ | Yes | Callback used to return the result. | @@ -127,13 +134,15 @@ Publishes a notification. This API uses a promise to return the result. **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** | Name | Readable| Writable| Type | Mandatory| Description | | -------- | ---- | ---- | ----------------------------------------- | ---- | ------------------------------------------- | -| request | Yes | No |[NotificationRequest](#notificationrequest) | Yes | Notification to publish.| +| request | Yes | No |[NotificationRequest](#notificationrequest) | Yes | **NotificationRequest** object.| | userId | Yes | No |number | Yes | ID of the user who receives the notification. | **Example** @@ -291,6 +300,8 @@ Adds a notification slot. This API uses an asynchronous callback to return the r **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -324,6 +335,8 @@ Adds a notification slot. This API uses a promise to return the result. **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -405,6 +418,8 @@ Adds multiple notification slots. This API uses an asynchronous callback to retu **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -442,6 +457,8 @@ Adds multiple notification slots. This API uses a promise to return the result. **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -681,6 +698,8 @@ Subscribes to a notification with the subscription information specified. This A **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -720,6 +739,8 @@ Subscribes to a notification with the subscription information specified. This A **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -754,6 +775,8 @@ Subscribes to a notification with the subscription information specified. This A **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -787,6 +810,8 @@ Unsubscribes from a notification. This API uses an asynchronous callback to retu **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -821,6 +846,8 @@ Unsubscribes from a notification. This API uses a promise to return the result. **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -853,6 +880,8 @@ Sets whether to enable notification for a specified bundle. This API uses an asy **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -885,6 +914,8 @@ Sets whether to enable notification for a specified bundle. This API uses a prom **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -917,6 +948,8 @@ Checks whether notification is enabled for a specified bundle. This API uses an **System API**: This is a system API and cannot be called by third-party applications. +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **Parameters** | Name | Readable| Writable| Type | Mandatory| Description | @@ -946,6 +979,8 @@ Checks whether notification is enabled for a specified bundle. This API uses a p **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -981,6 +1016,8 @@ Checks whether notification is enabled for this application. This API uses an as **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1009,6 +1046,8 @@ Checks whether notification is enabled for this application. This API uses a pro **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1041,6 +1080,8 @@ Sets whether to enable the notification badge for a specified bundle. This API u **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1073,6 +1114,8 @@ Sets the notification slot for a specified bundle. This API uses a promise to re **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1103,6 +1146,8 @@ Checks whether the notification badge is enabled for a specified bundle. This AP **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1134,6 +1179,8 @@ Checks whether the notification badge is enabled for a specified bundle. This AP **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1169,6 +1216,8 @@ Sets the notification slot for a specified bundle. This API uses an asynchronous **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1204,6 +1253,8 @@ Sets the notification slot for a specified bundle. This API uses a promise to re **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1237,6 +1288,8 @@ Obtains the notification slots of a specified bundle. This API uses an asynchron **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1268,6 +1321,8 @@ Obtains the notification slots of a specified bundle. This API uses a promise to **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1303,6 +1358,8 @@ Obtains the number of notification slots of a specified bundle. This API uses an **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1334,6 +1391,8 @@ Obtains the number of notification slots of a specified bundle. This API uses a **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1369,6 +1428,8 @@ Removes a notification for a specified bundle. This API uses an asynchronous cal **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1405,6 +1466,8 @@ Removes a notification for a specified bundle. This API uses a promise to return **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1439,6 +1502,8 @@ Removes a notification for a specified bundle. This API uses an asynchronous cal **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1470,6 +1535,8 @@ Removes a notification for a specified bundle. This API uses a promise to return **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1500,6 +1567,8 @@ Removes all notifications for a specified bundle. This API uses an asynchronous **System API**: This is a system API and cannot be called by third-party applications. +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **Parameters** | Name | Readable| Writable| Type | Mandatory| Description | @@ -1529,6 +1598,8 @@ Removes all notifications. This API uses an asynchronous callback to return the **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1557,6 +1628,8 @@ Removes all notifications for a specified user. This API uses a promise to retur **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1581,6 +1654,8 @@ Removes all notifications for a specified user. This API uses an asynchronous ca **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1610,6 +1685,8 @@ Removes all notifications for a specified user. This API uses a promise to retur **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1639,6 +1716,8 @@ Obtains all active notifications. This API uses an asynchronous callback to retu **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1667,7 +1746,9 @@ Obtains all active notifications. This API uses a promise to return the result. **System capability**: SystemCapability.Notification.Notification -**System API**: This is a system API and cannot be called by third-party applications. +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + +**System API**: This is a system API and cannot be called by third-party applications.removeGroupByBundle **Return value** @@ -1847,6 +1928,8 @@ Removes a notification group for a specified bundle. This API uses an asynchrono **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1880,6 +1963,8 @@ Removes a notification group for a specified bundle. This API uses a promise to **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1909,6 +1994,8 @@ Sets the DND time. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1944,6 +2031,8 @@ Sets the DND time. This API uses a promise to return the result. **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -1974,6 +2063,8 @@ Sets the DND time for a specified user. This API uses an asynchronous callback t **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2012,6 +2103,8 @@ Sets the DND time for a specified user. This API uses a promise to return the re **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2046,6 +2139,8 @@ Obtains the DND time. This API uses an asynchronous callback to return the resul **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2074,6 +2169,8 @@ Obtains the DND time. This API uses a promise to return the result. **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Return value** @@ -2099,6 +2196,10 @@ Obtains the DND time of a specified user. This API uses an asynchronous callback **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name | Readable| Writable| Type | Mandatory| Description | @@ -2128,6 +2229,10 @@ Obtains the DND time of a specified user. This API uses a promise to return the **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name | Readable| Writable| Type | Mandatory| Description | @@ -2159,6 +2264,8 @@ Checks whether the DND mode is supported. This API uses an asynchronous callback **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2187,6 +2294,8 @@ Checks whether the DND mode is supported. This API uses a promise to return the **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Return value** @@ -2317,6 +2426,8 @@ Sets whether this device supports distributed notifications. This API uses an as **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2348,6 +2459,8 @@ Sets whether this device supports distributed notifications. This API uses a pro **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2426,6 +2539,8 @@ Sets whether an application supports distributed notifications based on the bund **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2456,12 +2571,14 @@ Notification.enableDistributedByBundle(bundle, enable, enableDistributedByBundle ## Notification.enableDistributedByBundle8+ -bundleenableDistributedByBundle(bundle: BundleOption, enable: boolean): Promise\ +enableDistributedByBundle(bundle: BundleOption, enable: boolean): Promise\ Sets whether an application supports distributed notifications based on the bundle. This API uses a promise to return the result. **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2494,6 +2611,8 @@ Obtains whether an application supports distributed notifications based on the b **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2527,6 +2646,8 @@ Obtains whether an application supports distributed notifications based on the b **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2563,6 +2684,8 @@ Obtains the notification reminder type. This API uses an asynchronous callback t **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2591,6 +2714,8 @@ Obtains the notification reminder type. This API uses a promise to return the re **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Return value** @@ -2608,6 +2733,7 @@ Notification.getDeviceRemindType() }); ``` + ## Notification.publishAsBundle9+ publishAsBundle(request: NotificationRequest, representativeBundle: string, userId: number, callback: AsyncCallback\): void @@ -2616,14 +2742,15 @@ Publishes an agent-powered notification. This API uses an asynchronous callback **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER, ohos.permission.NOTIFICATION_AGENT_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** - | Name | Type | Mandatory| Description | | -------------------- | ------------------------------------------- | ---- | --------------------------------------------- | -| request | [NotificationRequest](#notificationrequest) | Yes | Notification to publish.| +| request | [NotificationRequest](#notificationrequest) | Yes | **NotificationRequest** object.| | representativeBundle | string | Yes | Bundle name of the application whose notification function is taken over by the reminder agent. | | userId | number | Yes | ID of the user who receives the notification. | | callback | AsyncCallback | Yes | Callback used to return the result. | @@ -2663,6 +2790,8 @@ Publishes a notification through the reminder agent. This API uses a promise to **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER, ohos.permission.NOTIFICATION_AGENT_CONTROLLER + **System API**: This is a system API and cannot be called by third-party applications. **Parameters** @@ -2670,7 +2799,7 @@ Publishes a notification through the reminder agent. This API uses a promise to | Name | Type | Mandatory| Description | | -------------------- | ------------------------------------------- | ---- | --------------------------------------------- | -| request | [NotificationRequest](#notificationrequest) | Yes | Notification to publish.| +| request | [NotificationRequest](#notificationrequest) | Yes | **NotificationRequest** object.| | representativeBundle | string | Yes | Bundle name of the application whose notification function is taken over by the reminder agent. | | userId | number | Yes | ID of the user who receives the notification. | @@ -2707,6 +2836,8 @@ Cancels a notification published by the reminder agent. This API uses an asynchr **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER, ohos.permission.NOTIFICATION_AGENT_CONTROLLER + **Parameters** @@ -2740,6 +2871,8 @@ Publishes a notification through the reminder agent. This API uses a promise to **System capability**: SystemCapability.Notification.Notification +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER, ohos.permission.NOTIFICATION_AGENT_CONTROLLER + **Parameters** @@ -2762,9 +2895,9 @@ Notification.cancelAsBundle(0, representativeBundle, userId).then(() => { }); ``` -## Notification.enableNotificationSlot9+ +## Notification.enableNotificationSlot 9+ -enableNotificationSlot(bundle: BundleOption, type: SlotType, enable: boolean, callback: AsyncCallback): void +enableNotificationSlot(bundle: BundleOption, type: SlotType, enable: boolean, callback: AsyncCallback\): void Sets the enabled status for a notification slot of a specified type. This API uses an asynchronous callback to return the result. @@ -2772,6 +2905,8 @@ Sets the enabled status for a notification slot of a specified type. This API us **System API**: This is a system API and cannot be called by third-party applications. +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **Parameters** | Name | Type | Mandatory| Description | @@ -2791,14 +2926,14 @@ function enableSlotCallback(err) { Notification.enableNotificationSlot( { bundle: "ohos.samples.notification", }, - notify.SlotType.SOCIAL_COMMUNICATION, + Notification.SlotType.SOCIAL_COMMUNICATION, true, enableSlotCallback); ``` -## Notification.enableNotificationSlot9+ +## Notification.enableNotificationSlot 9+ -enableNotificationSlot(bundle: BundleOption, type: SlotType, enable: boolean): Promise +enableNotificationSlot(bundle: BundleOption, type: SlotType, enable: boolean): Promise\ Sets the enabled status for a notification slot of a specified type. This API uses a promise to return the result. @@ -2806,6 +2941,8 @@ Sets the enabled status for a notification slot of a specified type. This API us **System API**: This is a system API and cannot be called by third-party applications. +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **Parameters** | Name| Type | Mandatory| Description | @@ -2820,29 +2957,31 @@ Sets the enabled status for a notification slot of a specified type. This API us //enableNotificationSlot Notification.enableNotificationSlot( { bundle: "ohos.samples.notification", }, - notify.SlotType.SOCIAL_COMMUNICATION, + Notification.SlotType.SOCIAL_COMMUNICATION, true).then(() => { console.log('====================>enableNotificationSlot====================>'); }); ``` -## Notification.isNotificationSlotEnabled9+ +## Notification.isNotificationSlotEnabled 9+ -isNotificationSlotEnabled(bundle: BundleOption, type: SlotType, callback: AsyncCallback): void +isNotificationSlotEnabled(bundle: BundleOption, type: SlotType, callback: AsyncCallback\): void -Obtains the enabled status of a notification slot of a specified type. This API uses an asynchronous callback to return the result. +Obtains the enabled status of the notification slot of a specified type. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Notification.Notification **System API**: This is a system API and cannot be called by third-party applications. +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **Parameters** | Name | Type | Mandatory| Description | | -------- | ----------------------------- | ---- | ---------------------- | | bundle | [BundleOption](#bundleoption) | Yes | Bundle information. | | type | [SlotType](#slottype) | Yes | Notification slot type. | -| callback | AsyncCallback\ | Yes | Callback used to return the result.| +| callback | AsyncCallback\ | Yes | Callback used to return the result.| **Example** @@ -2854,20 +2993,22 @@ function getEnableSlotCallback(err, data) { Notification.isNotificationSlotEnabled( { bundle: "ohos.samples.notification", }, - notify.SlotType.SOCIAL_COMMUNICATION, + Notification.SlotType.SOCIAL_COMMUNICATION, getEnableSlotCallback); ``` -## Notification.isNotificationSlotEnabled9+ +## Notification.isNotificationSlotEnabled 9+ -isNotificationSlotEnabled(bundle: BundleOption, type: SlotType): Promise +isNotificationSlotEnabled(bundle: BundleOption, type: SlotType): Promise\ -Obtains the enabled status of a notification slot of a specified type. This API uses a promise to return the result. +Obtains the enabled status of the notification slot of a specified type. This API uses a promise to return the result. **System capability**: SystemCapability.Notification.Notification **System API**: This is a system API and cannot be called by third-party applications. +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + **Parameters** | Name| Type | Mandatory| Description | @@ -2875,30 +3016,180 @@ Obtains the enabled status of a notification slot of a specified type. This API | bundle | [BundleOption](#bundleoption) | Yes | Bundle information. | | type | [SlotType](#slottype) | Yes | Notification slot type.| +**Return value** + +| Type | Description | +| ----------------------------------------------------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the enabled status of the notification slot of the specified type.| + **Example** ```js //isNotificationSlotEnabled Notification.isNotificationSlotEnabled( { bundle: "ohos.samples.notification", }, - notify.SlotType.SOCIAL_COMMUNICATION, - true).then((data) => { + Notification.SlotType.SOCIAL_COMMUNICATION + ).then((data) => { console.log('====================>isNotificationSlotEnabled====================>'); }); ``` + +## Notification.setSyncNotificationEnabledForUninstallApp9+ + +setSyncNotificationEnabledForUninstallApp(userId: number, enable: boolean, callback: AsyncCallback\): void + +Sets whether to sync notifications to devices where the application is not installed. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.Notification + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ----------------------------- | ---- | -------------- | +| userId | number | Yes | User ID. | +| enable | boolean | Yes | Whether to sync notifications to devices where the application is not installed. The value **true** means to sync notifications to devices where the application is not installed, and **false** means the opposite.| +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js +let userId = 100; +let enable = true; + +function setSyncNotificationEnabledForUninstallAppCallback(err) { + console.log('setSyncNotificationEnabledForUninstallAppCallback'); +} + +Notification.setSyncNotificationEnabledForUninstallApp(userId, enable, setSyncNotificationEnabledForUninstallAppCallback); +``` + + +## Notification.setSyncNotificationEnabledForUninstallApp9+ + +setSyncNotificationEnabledForUninstallApp(userId: number, enable: boolean): Promise\ + +Sets whether to sync notifications to devices where the application is not installed. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.Notification + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ----------------------------- | ---- | -------------- | +| userId | number | Yes | User ID. | +| enable | boolean | Yes | Whether to sync notifications to devices where the application is not installed. The value **true** means to sync notifications to devices where the application is not installed, and **false** means the opposite.| + +**Example** + +```js +let userId = 100; +let enable = true; + +Notification.setSyncNotificationEnabledForUninstallApp(userId, enable) + .then((data) => { + console.log('setSyncNotificationEnabledForUninstallApp, data:', data); + }) + .catch((err) => { + console.log('setSyncNotificationEnabledForUninstallApp, err:', err); + }); +``` + + +## Notification.getSyncNotificationEnabledForUninstallApp9+ + +getSyncNotificationEnabledForUninstallApp(userId: number, callback: AsyncCallback\): void + +Checks whether notifications are synced to devices where the application is not installed. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.Notification + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ----------------------------- | ---- | -------------- | +| userId | number | Yes | User ID. | +| callback | AsyncCallback\ | Yes | Callback used to return the result. The value **true** means that notifications are synced to devices where the application is not installed, and **false** means the opposite.| + +**Example** + +```js +let userId = 100; + +function getSyncNotificationEnabledForUninstallAppCallback(err, data) { + console.log('getSyncNotificationEnabledForUninstallAppCallback, data: ', data); +} + +Notification.getSyncNotificationEnabledForUninstallApp(userId, getSyncNotificationEnabledForUninstallAppCallback); +``` + + +## Notification.getSyncNotificationEnabledForUninstallApp9+ + +getSyncNotificationEnabledForUninstallApp(userId: number): Promise\ + +Checks whether notifications are synced to devices where the application is not installed. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.Notification + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.NOTIFICATION_CONTROLLER + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ----------------------------- | ---- | -------------- | +| userId | number | Yes | User ID. | + +**Return value** + +| Type | Description | +| ----------------------------------------------------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the result. The value **true** means that notifications are synced to devices where the application is not installed, and **false** means the opposite.| + +**Example** + +```js +let userId = 100; + +Notification.getSyncNotificationEnabledForUninstallApp(userId) + .then((data) => { + console.log('getSyncNotificationEnabledForUninstallApp, data: ', data); + }) + .catch((err) => { + console.log('getSyncNotificationEnabledForUninstallApp, err: ', err); + }); +``` + + + ## NotificationSubscriber **System API**: This is a system API and cannot be called by third-party applications. ### onConsume -onConsume?:(data: [SubscribeCallbackData](#subscribecallbackdata)) +onConsume?: (data: [SubscribeCallbackData](#subscribecallbackdata)) => void Callback for receiving notifications. **System capability**: SystemCapability.Notification.Notification +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name| Type| Mandatory| Description| @@ -2940,12 +3231,14 @@ Notification.subscribe(subscriber, subscribeCallback); ### onCancel -onCancel?:(data: [SubscribeCallbackData](#subscribecallbackdata)) +onCancel?:(data: [SubscribeCallbackData](#subscribecallbackdata)) => void Callback for removing notifications. **System capability**: SystemCapability.Notification.Notification +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name| Type| Mandatory| Description| @@ -2978,12 +3271,14 @@ Notification.subscribe(subscriber, subscribeCallback); ### onUpdate -onUpdate?:(data: [NotificationSortingMap](#notificationsortingmap)) +onUpdate?:(data: [NotificationSortingMap](#notificationsortingmap)) => void Callback for notification sorting updates. **System capability**: SystemCapability.Notification.Notification +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name| Type| Mandatory| Description| @@ -3014,12 +3309,14 @@ Notification.subscribe(subscriber, subscribeCallback); ### onConnect -onConnect?:void +onConnect?:() => void Callback for subscription. **System capability**: SystemCapability.Notification.Notification +**System API**: This is a system API and cannot be called by third-party applications. + **Example** ```javascript @@ -3044,12 +3341,14 @@ Notification.subscribe(subscriber, subscribeCallback); ### onDisconnect -onDisconnect?:void +onDisconnect?:() => void Callback for unsubscription. **System capability**: SystemCapability.Notification.Notification +**System API**: This is a system API and cannot be called by third-party applications. + **Example** ```javascript @@ -3074,12 +3373,14 @@ Notification.subscribe(subscriber, subscribeCallback); ### onDestroy -onDestroy?:void +onDestroy?:() => void Callback for service disconnection. **System capability**: SystemCapability.Notification.Notification +**System API**: This is a system API and cannot be called by third-party applications. + **Example** ```javascript @@ -3104,17 +3405,19 @@ Notification.subscribe(subscriber, subscribeCallback); ### onDoNotDisturbDateChange8+ -onDoNotDisturbDateChange?:(mode: Notification.[DoNotDisturbDate](#donotdisturbdate8)) +onDoNotDisturbDateChange?:(mode: notification.[DoNotDisturbDate](#donotdisturbdate8)) => void Callback for DND time setting updates. **System capability**: SystemCapability.Notification.Notification +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name| Type| Mandatory| Description| | ------------ | ------------------------ | ---- | -------------------------- | -| mode | Notification.[DoNotDisturbDate](#donotdisturbdate8) | Yes| DND time setting updates.| +| mode | notification.[DoNotDisturbDate](#donotdisturbdate8) | Yes| DND time setting updates.| **Example** ```javascript @@ -3140,12 +3443,14 @@ Notification.subscribe(subscriber, subscribeCallback); ### onEnabledNotificationChanged8+ -onEnabledNotificationChanged?:(callbackData: [EnabledNotificationCallbackData](#enablednotificationcallbackdata8)) +onEnabledNotificationChanged?:(callbackData: [EnabledNotificationCallbackData](#enablednotificationcallbackdata8)) => void Listens for the notification enable status changes. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Notification.Notification +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name| Type| Mandatory| Description| @@ -3201,7 +3506,7 @@ Notification.subscribe(subscriber, subscribeCallback); | ------ | ---- | --- | ------- | ---- | ---------------- | | bundle | Yes | No | string | Yes | Bundle name of the application. | | uid | Yes | No | number | Yes | UID of the application. | -| enable | Yes | No | boolean | Yes | Notification enable status of the application.| +| enable | Yes | No | boolean | Yes | Notification enabled status of the application.| ## DoNotDisturbDate8+ @@ -3300,7 +3605,7 @@ Notification.subscribe(subscriber, subscribeCallback); | title | Yes | Yes | string | Yes | Button title. | | wantAgent | Yes | Yes | WantAgent | Yes | **WantAgent** of the button.| | extras | Yes | Yes | { [key: string]: any } | No | Extra information of the button. | -| userInput9+ | Yes | Yes | [NotificationUserInput](#notificationuserinput8) | No | User input object. | +| userInput8+ | Yes | Yes | [NotificationUserInput](#notificationuserinput8) | No | User input object. | ## NotificationBasicContent @@ -3425,14 +3730,16 @@ Notification.subscribe(subscriber, subscribeCallback); | creatorPid | Yes | No | number | No | PID used for creating the notification. | | creatorUserId8+| Yes | No | number | No | ID of the user who creates the notification. | | hashCode | Yes | No | string | No | Unique ID of the notification. | -| classification | Yes | Yes | string | No | Notification category. | +| classification | Yes | Yes | string | No | Notification category.
**System API**: This is a system API and cannot be called by third-party applications. | | groupName8+| Yes | Yes | string | No | Group notification name. | | template8+ | Yes | Yes | [NotificationTemplate](#notificationtemplate8) | No | Notification template. | -| isRemoveAllowed8+ | Yes | No | boolean | No | Whether the notification can be removed. | -| source8+ | Yes | No | number | No | Notification source. | +| isRemoveAllowed8+ | Yes | No | boolean | No | Whether the notification can be removed.
**System API**: This is a system API and cannot be called by third-party applications. | +| source8+ | Yes | No | number | No | Notification source.
**System API**: This is a system API and cannot be called by third-party applications. | | distributedOption8+ | Yes | Yes | [DistributedOptions](#distributedoptions8) | No | Option of distributed notification. | -| deviceId8+ | Yes | No | string | No | Device ID of the notification source. | +| deviceId8+ | Yes | No | string | No | Device ID of the notification source.
**System API**: This is a system API and cannot be called by third-party applications. | | notificationFlags8+ | Yes | No | [NotificationFlags](#notificationflags8) | No | Notification flags. | +| removalWantAgent9+ | Yes | Yes | WantAgent | No | **WantAgent** instance to which the notification will be redirected when it is removed. | +| badgeNumber9+ | Yes | Yes | number | No | Number of notifications displayed on the application icon. | ## DistributedOptions8+ @@ -3444,7 +3751,7 @@ Notification.subscribe(subscriber, subscribeCallback); | isDistributed | Yes | Yes | boolean | No | Whether the notification is a distributed notification. | | supportDisplayDevices | Yes | Yes | Array\ | Yes | Types of the devices to which the notification can be synchronized. | | supportOperateDevices | Yes | Yes | Array\ | No | Devices on which notification can be enabled. | -| remindType | Yes | No | number | No | Notification reminder type. | +| remindType | Yes | No | number | No | Notification reminder type.
**System API**: This is a system API and cannot be called by third-party applications. | ## NotificationSlot @@ -3535,3 +3842,16 @@ Notification.subscribe(subscriber, subscribeCallback); | IDLE_REMIND | 1 | The device is not in use. | | ACTIVE_DONOT_REMIND | 2 | The device is in use. No notification is required. | | ACTIVE_REMIND | 3 | The device is in use. | + + +## SourceType8+ + +**System capability**: SystemCapability.Notification.Notification + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name | Value | Description | +| -------------------- | --- | -------------------- | +| TYPE_NORMAL | 0 | Normal notification. | +| TYPE_CONTINUOUS | 1 | Continuous notification. | +| TYPE_TIMER | 2 | Timed notification. | diff --git a/en/application-dev/reference/apis/js-apis-radio.md b/en/application-dev/reference/apis/js-apis-radio.md index 5b371ea07267732eb69de7676cab7f6057954275..16da2e93685e99d26b9af2040af3f294ce68bd08 100644 --- a/en/application-dev/reference/apis/js-apis-radio.md +++ b/en/application-dev/reference/apis/js-apis-radio.md @@ -899,9 +899,698 @@ promise.then(data => { }); ``` +## radio.sendUpdateCellLocationRequest8+ + +sendUpdateCellLocationRequest\(callback: AsyncCallback\): void + +Sends a cell location update request. This API uses an asynchronous callback to return the result. + + + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ---------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js +radio.sendUpdateCellLocationRequest((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## radio.sendUpdateCellLocationRequest8+ + +sendUpdateCellLocationRequest\(\): Promise + +Sends a cell location update request. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +**Return value** + +| Type | Description | +| --------------- | ----------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let promise = radio.sendUpdateCellLocationRequest(); +promise.then(data => { + console.log(`sendUpdateCellLocationRequest success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`sendUpdateCellLocationRequest fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## radio.getCellInformation8+ + +getCellInformation(callback: AsyncCallback>): void + +Obtains cell information. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permissions**: ohos.permission.LOCATION + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------ | +| callback | AsyncCallback\\> | Yes | Callback used to return the result.| + +**Example** + +```js +radio.getCellInformation((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.getCellInformation8+ + +getCellInformation(slotId: number, callback: AsyncCallback\>): void + +Obtains cell information. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permissions**: ohos.permission.LOCATION + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback\\> | Yes | Callback used to return the result. | + +**Example** + +```js +let slotId = 0; +radio.getCellInformation(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.getCellInformation8+ + +getCellInformation(slotId?: number): Promise\> + +Obtains cell information. This API uses a promise to return the result. + +This is a system API. + +**Required permissions**: ohos.permission.LOCATION + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | No | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ------------------------------------------------------- | ----------------------- | +| Promise\\> | Promise used to return the result.| + +**Example** + +```js +let slotId = 0; +let promise = radio.getCellInformation(slotId); +promise.then(data => { + console.log(`getCellInformation success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getCellInformation fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## radio.setNetworkSelectionMode + +setNetworkSelectionMode\(options: NetworkSelectionModeOptions, callback: AsyncCallback\): void + +Sets the network selection mode. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------------------- | ---- | ------------------ | +| options | [NetworkSelectionModeOptions](#networkselectionmodeoptions) | Yes | Network selection mode.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```js +let networkInformation={ + operatorName: "China Mobile", + operatorNumeric: "898600", + state: 1, + radioTech: "CS" +} +let networkSelectionModeOptions={ + slotid: 0, + selectMode: 1, + networkInformation: networkInformation, + resumeSelection: true +} +radio.setNetworkSelectionMode(networkSelectionModeOptions, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## radio.setNetworkSelectionMode + +setNetworkSelectionMode\(options: NetworkSelectionModeOptions\): Promise + +Sets the network selection mode. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ----------------------------------------------------------- | ---- | ------------------ | +| options | [NetworkSelectionModeOptions](#networkselectionmodeoptions) | Yes | Network selection mode.| + +**Return value** + +| Type | Description | +| --------------- | ----------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let networkInformation={ + operatorName: "China Mobile", + operatorNumeric: "898600", + state: 1, + radioTech: "CS" +} +let networkSelectionModeOptions={ + slotid: 0, + selectMode: 1, + networkInformation: networkInformation, + resumeSelection: true +} +let promise = radio.setNetworkSelectionMode(networkSelectionModeOptions); +promise.then(data => { + console.log(`setNetworkSelectionMode success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`setNetworkSelectionMode fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## radio.getNetworkSearchInformation + +getNetworkSearchInformation\(slotId: number, callback: AsyncCallback\): void + +Obtains network search information. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback\<[NetworkSearchResult](#networksearchresult)\> | Yes | Callback used to return the result. | + +**Example** + +```js +radio.getNetworkSearchInformation(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## radio.getNetworkSearchInformation + +getNetworkSearchInformation\(slotId: number\): Promise + +Obtains network search information. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ------------------------------------------------------ | ----------------------- | +| Promise\<[NetworkSearchResult](#networksearchresult)\> | Promise used to return the result.| + +**Example** + +```js +let promise = radio.getNetworkSearchInformation(0); +promise.then(data => { + console.log(`getNetworkSearchInformation success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getNetworkSearchInformation fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## radio.getNrOptionMode8+ + +getNrOptionMode(callback: AsyncCallback): void + +Obtains the NR option mode. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\<[NrOptionMode](#nroptionmode8)\> | Yes | Callback used to return the result.| + +**Example** + +```js +radio.getNrOptionMode((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.getNrOptionMode8+ + +getNrOptionMode(slotId: number, callback: AsyncCallback): void + +Obtains the NR option mode. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback\<[NrOptionMode](#nroptionmode8)\> | Yes | Callback used to return the result. | + +**Example** + +```js +let slotId = 0; +radio.getNrOptionMode(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.getNrOptionMode8+ + +getNrOptionMode(slotId?: number): Promise + +Obtains the NR option mode. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | No | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ----------------------------------------- | ----------------------- | +| Promise\<[NrOptionMode](#nroptionmode8)\> | Promise used to return the result.| + +**Example** + +```js +let slotId = 0; +let promise = radio.getNrOptionMode(slotId); +promise.then(data => { + console.log(`getNrOptionMode success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getNrOptionMode fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## radio.turnOnRadio7+ + +turnOnRadio(callback: AsyncCallback): void + +Turns on the radio function. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ---------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js +radio.turnOnRadio((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.turnOnRadio7+ + +turnOnRadio(slotId: number, callback: AsyncCallback): void + +Turns on the radio function for the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```js +let slotId = 0; +radio.turnOnRadio(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.turnOnRadio7+ + +turnOnRadio(slotId?: number): Promise + +Turns on the radio function for the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | No | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| --------------- | ----------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let slotId = 0; +let promise = radio.turnOnRadio(slotId); +promise.then(data => { + console.log(`turnOnRadio success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`turnOnRadio fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## radio.turnOffRadio7+ + +turnOffRadio(callback: AsyncCallback): void + +Turns off the radio function. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ---------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js +radio.turnOffRadio((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.turnOffRadio7+ + +turnOffRadio(slotId: number, callback: AsyncCallback): void + +Turns off the radio function for the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```js +let slotId = 0; +radio.turnOffRadio(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.turnOffRadio7+ + +turnOffRadio(slotId?: number): Promise + +Turns off the radio function for the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | No | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| --------------- | ----------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let slotId = 0; +let promise = radio.turnOffRadio(slotId); +promise.then(data => { + console.log(`turnOffRadio success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`turnOffRadio fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## radio.setPreferredNetwork8+ + +setPreferredNetwork\(slotId: number, networkMode: PreferredNetworkMode, callback: AsyncCallback\): void + +Sets the preferred network. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ---------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| networkMode | [PreferredNetworkMode](#preferrednetworkmode8) | Yes | Preferred network mode. | +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```js +radio.setPreferredNetwork(0, 1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## radio.setPreferredNetwork8+ + +setPreferredNetwork(slotId: number, networkMode: PreferredNetworkMode): Promise + +Sets the preferred network. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ---------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| networkMode | [PreferredNetworkMode](#preferrednetworkmode8) | Yes | Preferred network mode. | + +**Return value** + +| Type | Description | +| --------------- | ----------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let promise = radio.setPreferredNetwork(0, 1); +promise.then(data => { + console.log(`setPreferredNetwork success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`setPreferredNetwork fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## radio.getPreferredNetwork8+ + +getPreferredNetwork\(slotId: number, callback: AsyncCallback\): void + +Obtains the preferred network. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback\<[PreferredNetworkMode](#preferrednetworkmode8)\> | Yes | Callback used to return the result. | + +**Example** + +```js +radio.getPreferredNetwork(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## radio.getPreferredNetwork8+ + +getPreferredNetwork(slotId: number): Promise + +Obtains the preferred network. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| --------------- | ----------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let promise = radio.getPreferredNetwork(0); +promise.then(data => { + console.log(`getPreferredNetwork success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getPreferredNetwork fail, promise: err->${JSON.stringify(err)}`); +}); +``` + ## RadioTechnology -Enumerates the RAT. +Enumerates radio access technologies. **System capability**: SystemCapability.Telephony.CoreService @@ -1010,3 +1699,238 @@ Enumerates network selection modes. | NETWORK_SELECTION_UNKNOWN | 0 | Unknown network selection mode.| | NETWORK_SELECTION_AUTOMATIC | 1 | Automatic network selection mode.| | NETWORK_SELECTION_MANUAL | 2 | Manual network selection mode.| + +## PreferredNetworkMode8+ + +Enumerates preferred network modes. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| --------------------------------------------------------- | ---- | --------------------------------------------- | +| PREFERRED_NETWORK_MODE_GSM | 1 | GSM network mode. | +| PREFERRED_NETWORK_MODE_WCDMA | 2 | WCDMA network mode. | +| PREFERRED_NETWORK_MODE_LTE | 3 | LTE network mode. | +| PREFERRED_NETWORK_MODE_LTE_WCDMA | 4 | LTE+WCDMA network mode. | +| PREFERRED_NETWORK_MODE_LTE_WCDMA_GSM | 5 | LTE+WCDMA+GSM network mode. | +| PREFERRED_NETWORK_MODE_WCDMA_GSM | 6 | WCDMA+GSM network mode. | +| PREFERRED_NETWORK_MODE_CDMA | 7 | CDMA network mode. | +| PREFERRED_NETWORK_MODE_EVDO | 8 | EVDO network mode. | +| PREFERRED_NETWORK_MODE_EVDO_CDMA | 9 | EVDO+CDMA network mode. | +| PREFERRED_NETWORK_MODE_WCDMA_GSM_EVDO_CDMA | 10 | WCDMA+GSM+EVDO+CDMA network mode. | +| PREFERRED_NETWORK_MODE_LTE_EVDO_CDMA | 11 | LTE+EVDO+CDMA network mode. | +| PREFERRED_NETWORK_MODE_LTE_WCDMA_GSM_EVDO_CDMA | 12 | LTE+WCDMA+GSM+EVDO+CDMA network mode. | +| PREFERRED_NETWORK_MODE_TDSCDMA | 13 | TD-SCDMA network mode. | +| PREFERRED_NETWORK_MODE_TDSCDMA_GSM | 14 | TD-SCDMA+GSM network mode. | +| PREFERRED_NETWORK_MODE_TDSCDMA_WCDMA | 15 | TD-SCDMA+WCDMA network mode. | +| PREFERRED_NETWORK_MODE_TDSCDMA_WCDMA_GSM | 16 | TD-SCDMA+WCDMA+GSM network mode. | +| PREFERRED_NETWORK_MODE_LTE_TDSCDMA | 17 | LTE+TD-SCDMA network mode. | +| PREFERRED_NETWORK_MODE_LTE_TDSCDMA_GSM | 18 | LTE+TD-SCDMA+GSM network mode. | +| PREFERRED_NETWORK_MODE_LTE_TDSCDMA_WCDMA | 19 | LTE+TD-SCDMA+WCDMA network mode. | +| PREFERRED_NETWORK_MODE_LTE_TDSCDMA_WCDMA_GSM | 20 | LTE+TD-SCDMA+WCDMA+GSM network mode. | +| PREFERRED_NETWORK_MODE_TDSCDMA_WCDMA_GSM_EVDO_CDMA | 21 | TD-SCDMA+WCDMA+GSM+EVDO+CDMA network mode. | +| PREFERRED_NETWORK_MODE_LTE_TDSCDMA_WCDMA_GSM_EVDO_CDMA | 22 | LTE+TD-SCDMA+WCDMA+GSM+EVDO+CDMA network mode.| +| PREFERRED_NETWORK_MODE_NR | 31 | NR network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE | 32 | NR+LTE network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE_WCDMA | 33 | NR+LTE+WCDMA network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE_WCDMA_GSM | 34 | NR+LTE+WCDMA+GSM network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE_EVDO_CDMA | 35 | NR+LTE+EVDO+CDMA network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE_WCDMA_GSM_EVDO_CDMA | 36 | NR+LTE+WCDMA+GSM+EVDO+CDMA network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE_TDSCDMA | 37 | NR+LTE+TD-SCDMA network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE_TDSCDMA_GSM | 38 | NR+LTE+TD-SCDMA+GSM network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE_TDSCDMA_WCDMA | 39 | NR+LTE+TD-SCDMA+WCDMA network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE_TDSCDMA_WCDMA_GSM | 40 | NR+LTE+TD-SCDMA+WCDMA+GSM network mode. | +| PREFERRED_NETWORK_MODE_NR_LTE_TDSCDMA_WCDMA_GSM_EVDO_CDMA | 41 | NR+LTE+TD-SCDMA+WCDMA+GSM+EVDO+CDMA network mode. | +| PREFERRED_NETWORK_MODE_MAX_VALUE | 99 | Maximum value of the preferred network mode. | + +## CellInformation8+ + +Defines the cell information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| networkType | [NetworkType](#networkType) | Network type of the cell. | +| isCamped | boolean | Status of the cell. | +| timeStamp | number | Timestamp when cell information is obtained. | +| signalInformation | [SignalInformation](#signalinformation) | Signal information. | +| data | [CdmaCellInformation](#cdmacellinformation) \| [GsmCellInformation](#gsmcellinformation) \| [LteCellInformation](#ltecellinformation) \| [NrCellInformation](#nrcellinformation) \| [TdscdmaCellInformation](#tdscdmacellinformation) | CDMA cell information \| GSM cell information \| LTE cell information \| NR cell information \| TD-SCDMA cell information | + +## CdmaCellInformation8+ + +Defines the CDMA cell information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| --------- | ------ | ------------ | +| baseId | number | Base station ID. | +| latitude | number | Longitude. | +| longitude | number | Latitude. | +| nid | number | Network ID.| +| sid | number | System ID.| + +## GsmCellInformation8+ + +Defines the GSM cell information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ------ | ------ | -------------------- | +| lac | number | Location area code. | +| cellId | number | Cell ID. | +| arfcn | number | Absolute radio frequency channel number.| +| bsic | number | Base station ID. | +| mcc | string | Mobile country code. | +| mnc | string | Mobile network code. | + +## LteCellInformation8+ + +Defines the LTE cell information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ------------- | ------- | ----------------------- | +| cgi | number | Cell global identification. | +| pci | number | Physical cell ID. | +| tac | number | Tracking area code. | +| earfcn | number | Absolute radio frequency channel number. | +| bandwidth | number | Bandwidth. | +| mcc | string | Mobile country code. | +| mnc | string | Mobile network code. | +| isSupportEndc | boolean | Support New Radio_Dual Connectivity| + +## NrCellInformation8+ + +Defines the NR cell information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ------- | ------ | ---------------- | +| nrArfcn | number | 5G frequency number. | +| pci | number | Physical cell ID. | +| tac | number | Tracking area code. | +| nci | number | 5G network cell ID.| +| mcc | string | Mobile country code. | +| mnc | string | Mobile network code. | + +## TdscdmaCellInformation8+ + +Defines the TD-SCDMA cell information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ------ | ------ | ------------ | +| lac | number | Location area code.| +| cellId | number | Cell ID. | +| cpid | number | Cell parameter ID.| +| uarfcn | number | Absolute radio frequency number.| +| mcc | string | Mobile country code.| +| mnc | string | Mobile network code. | + +## WcdmaCellInformation8+ + +Defines the WCDMA cell information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ------ | ------ | ------------ | +| lac | number | Location area code.| +| cellId | number | Cell ID. | +| psc | number | Primary scrambling code. | +| uarfcn | number | Absolute radio frequency number.| +| mcc | string | Mobile country code.| +| mnc | string | Mobile network code. | + +## NrOptionMode8+ + +Enumerates NR selection modes. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| -------------------- | ---- | ---------------------------------- | +| NR_OPTION_UNKNOWN | 0 | Unknown NR selection mode. | +| NR_OPTION_NSA_ONLY | 1 | NR selection mode in 5G non-standalone networking. | +| NR_OPTION_SA_ONLY | 2 | NR selection mode in 5G standalone networking. | +| NR_OPTION_NSA_AND_SA | 3 | NR selection mode in non-standalone and standalone networking.| + +## NetworkSearchResult + +Defines the network search result. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ---------------------- | ------------------------------------------------- | -------------- | +| isNetworkSearchSuccess | boolean | Successful network search.| +| networkSearchResult | Array<[NetworkInformation](#networkinformation)\> | Network search result.| + +## NetworkInformation + +Defines the network information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| --------------- | ----------------------------------------- | -------------- | +| operatorName | string | Carrier name.| +| operatorNumeric | string | Carrier number. | +| state | [NetworkInformation](#networkinformationstate) | Network information status.| +| radioTech | string | Radio technology. | + +## NetworkInformationState + +Enumerates network information states. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| ----------------- | ---- | ---------------- | +| NETWORK_UNKNOWN | 0 | Unknown state. | +| NETWORK_AVAILABLE | 1 | Available for registration.| +| NETWORK_CURRENT | 2 | Registered state.| +| NETWORK_FORBIDDEN | 3 | Unavailable for registration. | + +## NetworkSelectionModeOptions + +Defines the network selection mode. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ------------------ | --------------------------------------------- | -------------------------------------- | +| slotId | number | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| selectMode | [NetworkSelectionMode](#networkselectionmode) | Network selection mode. | +| networkInformation | [NetworkInformation](#networkinformation) | Network information. | +| resumeSelection | boolean | Whether to resume selection. | diff --git a/en/application-dev/reference/apis/js-apis-screenshot.md b/en/application-dev/reference/apis/js-apis-screenshot.md index 7f83f0250c209dbd6b5d57970fe7beb8d9b9a494..8f88d00f0d246628e3669ae376da04191efedb92 100644 --- a/en/application-dev/reference/apis/js-apis-screenshot.md +++ b/en/application-dev/reference/apis/js-apis-screenshot.md @@ -68,29 +68,30 @@ Takes a screenshot and saves it as a **PixelMap** object. This API uses an async | Name | Type | Mandatory| Description | | -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | | options | [ScreenshotOptions](#screenshotoptions) | No | Screenshot settings consist of **screenRect**, **imageSize**, **rotation**, and **displayId**. You can set the parameters separately.| -| callback | AsyncCallback<image.PixelMap> | Yes | Callback used to return a **PixelMap** object. | +| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes | Callback used to return a **PixelMap** object. | **Example** ```js - var ScreenshotOptions = { - "screenRect": { - "left": 200, - "top": 100, - "width": 200, - "height": 200}, - "imageSize": { - "width": 300, - "height": 300}, - "rotation": 0, - "displayId": 0 + var screenshotOptions = { + "screenRect": { + "left": 200, + "top": 100, + "width": 200, + "height": 200}, + "imageSize": { + "width": 300, + "height": 300}, + "rotation": 0, + "displayId": 0 }; - screenshot.save(ScreenshotOptions, (err, data) => { - if (err) { - console.error('Failed to save the screenshot. Error: ' + JSON.stringify(err)); - return; - } - console.info('Screenshot saved. Data: ' + JSON.stringify(data)); + screenshot.save(screenshotOptions, (err, pixelMap) => { + if (err) { + console.log('Failed to save screenshot: ' + JSON.stringify(err)); + return; + } + console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); + pixelMap.release(); // Release the memory in time after the PixelMap is used. }); ``` @@ -114,12 +115,12 @@ Takes a screenshot and saves it as a **PixelMap** object. This API uses a promis | Type | Description | | ----------------------------- | ----------------------------------------------- | -| Promise<image.PixelMap> | Promise used to return a **PixelMap** object.| +| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return a **PixelMap** object.| **Example** ```js - var ScreenshotOptions = { + var screenshotOptions = { "screenRect": { "left": 200, "top": 100, @@ -131,10 +132,11 @@ Takes a screenshot and saves it as a **PixelMap** object. This API uses a promis "rotation": 0, "displayId": 0 }; - let promise = screenshot.save(ScreenshotOptions); - promise.then(() => { - console.log('screenshot save success'); + let promise = screenshot.save(screenshotOptions); + promise.then((pixelMap) => { + console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); + pixelMap.release(); // Release the memory in time after the PixelMap is used. }).catch((err) => { - console.log('screenshot save fail: ' + JSON.stringify(err)); + console.log('Failed to save screenshot: ' + JSON.stringify(err)); }); ``` diff --git a/en/application-dev/reference/apis/js-apis-service-extension-ability.md b/en/application-dev/reference/apis/js-apis-service-extension-ability.md index 388657b05dce3f05601cc88123ff2d64adbf127b..388b4308555f8dc061bfa62da40fd4dc5d97cfee 100644 --- a/en/application-dev/reference/apis/js-apis-service-extension-ability.md +++ b/en/application-dev/reference/apis/js-apis-service-extension-ability.md @@ -23,9 +23,9 @@ None. **System API**: This is a system API and cannot be called by third-party applications. -| Name| Type| Readable| Writable| Description| +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| context | [ServiceExtensionContext](js-apis-service-extension-context.md) | Yes| No| Service Extension context, which is inherited from **ExtensionContext**.| +| context | [ServiceExtensionContext](js-apis-service-extension-context.md) | Yes| No| Service Extension context, which is inherited from **ExtensionContext**.| ## ServiceExtensionAbility.onCreate @@ -40,9 +40,9 @@ Called when a Service Extension ability is created to initialize the service log **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-application-Want.md) | Yes| Information related to this Service Extension ability, including the ability name and bundle name.| **Example** @@ -88,10 +88,10 @@ Called after **onCreate** is invoked when a Service Extension ability is started **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information related to this Service Extension ability, including the ability name and bundle name.| -| startId | number | Yes| Number of ability start times. The initial value is **1**, and the value is automatically incremented for each ability started.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-application-Want.md) | Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | startId | number | Yes| Number of ability start times. The initial value is **1**, and the value is automatically incremented for each ability started.| **Example** @@ -116,15 +116,15 @@ Called after **onCreate** is invoked when a Service Extension ability is started **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.| **Return value** -| Type| Description| -| -------- | -------- | -| rpc.RemoteObject | A **RemoteObject** object used for communication with the client.| + | Type| Description| + | -------- | -------- | + | rpc.RemoteObject | A **RemoteObject** object used for communication with the client.| **Example** @@ -158,9 +158,9 @@ Called when this Service Extension ability is disconnected. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want |[Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want |[Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.| **Example** @@ -184,16 +184,16 @@ Called when this Service Extension ability is reconnected. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want |[Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want |[Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.| **Example** ```js class ServiceExt extends ServiceExtension { - onDisconnect(want) { - console.log('onDisconnect, want:' + want.abilityName); + onReconnect(want) { + console.log('onReconnect, want:' + want.abilityName); } } ``` @@ -202,7 +202,7 @@ Called when this Service Extension ability is reconnected. onConfigurationUpdated(config: Configuration): void; -Called when the configuration of this Service Extension ability is updated. + Called when the configuration of this Service Extension ability is updated. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -210,9 +210,9 @@ Called when the configuration of this Service Extension ability is updated. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [Configuration](js-apis-configuration.md) | Yes| New configuration.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [Configuration](js-apis-configuration.md) | Yes| New configuration.| **Example** @@ -236,9 +236,9 @@ Dumps the client information. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| params | Array\ | Yes| Parameters in the form of a command.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | params | Array\ | Yes| Parameters in the form of a command.| **Example** diff --git a/en/application-dev/reference/apis/js-apis-service-extension-context.md b/en/application-dev/reference/apis/js-apis-service-extension-context.md index 241a8bf17f94a3362fe6d12d4662b139c4c4cd8b..cb56fdccb85fd5aa96e161df2f86fbc1a5573b2d 100644 --- a/en/application-dev/reference/apis/js-apis-service-extension-context.md +++ b/en/application-dev/reference/apis/js-apis-service-extension-context.md @@ -26,7 +26,7 @@ Before using the **ServiceExtensionContext** module, you must define a child cla startAbility(want: Want, callback: AsyncCallback<void>): void; -Starts an ability. This API uses a callback to return the result. +Starts an ability. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -36,8 +36,8 @@ Starts an ability. This API uses a callback to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to start, such as the ability name and bundle name.| - | callback | AsyncCallback<void> | No| Callback used to return the result indicating whether the API is successfully called.| + | want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability, such as the ability name and bundle name.| + | callback | AsyncCallback<void> | No| Callback used to return the result.| **Example** @@ -64,14 +64,14 @@ Starts an ability. This API uses a promise to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to start, such as the ability name and bundle name.| + | want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability, such as the ability name and bundle name.| | options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| **Return value** | Type| Description| | -------- | -------- | - | Promise<void> | Promise used to return the result indicating whether the API is successfully called.| + | Promise<void> | Promise used to return the result.| **Example** @@ -92,7 +92,7 @@ Starts an ability. This API uses a promise to return the result. startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void -Starts an ability. This API uses a callback to return the result. +Starts an ability. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -102,7 +102,7 @@ Starts an ability. This API uses a callback to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| | options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| @@ -136,8 +136,8 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** @@ -169,8 +169,8 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -206,10 +206,16 @@ Starts an ability with the account ID specified. This API uses a promise to retu | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + **Example** ```js @@ -245,7 +251,7 @@ Starts a new Service Extension ability. This API uses an asynchronous callback t | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** @@ -275,7 +281,13 @@ Starts a new Service Extension ability. This API uses a promise to return the re | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| **Example** @@ -310,8 +322,8 @@ Starts a new Service Extension ability with the account ID specified. This API u | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** @@ -344,8 +356,14 @@ Starts a new Service Extension ability with the account ID specified. This API u | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| **Example** @@ -369,7 +387,7 @@ Starts a new Service Extension ability with the account ID specified. This API u stopServiceExtensionAbility(want: Want, callback: AsyncCallback\): void; -Stops Service Extension abilities in the same application. This API uses an asynchronous callback to return the result. +Stops a Service Extension ability in the same application. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -379,7 +397,7 @@ Stops Service Extension abilities in the same application. This API uses an asyn | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** @@ -399,7 +417,7 @@ Stops Service Extension abilities in the same application. This API uses an asyn stopServiceExtensionAbility(want: Want): Promise\; -Stops Service Extension abilities in the same application. This API uses a promise to return the result. +Stops a Service Extension ability in the same application. This API uses a promise to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -409,7 +427,13 @@ Stops Service Extension abilities in the same application. This API uses a promi | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| **Example** @@ -432,7 +456,7 @@ Stops Service Extension abilities in the same application. This API uses a promi stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; -Stops Service Extension abilities in the same application with the account ID specified. This API uses an asynchronous callback to return the result. +Stops a Service Extension ability in the same application with the account ID specified. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -444,8 +468,8 @@ Stops Service Extension abilities in the same application with the account ID sp | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** @@ -466,7 +490,7 @@ Stops Service Extension abilities in the same application with the account ID sp stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\; -Stops Service Extension abilities in the same application with the account ID specified. This API uses a promise to return the result. +Stops a Service Extension ability in the same application with the account ID specified. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -478,8 +502,14 @@ Stops Service Extension abilities in the same application with the account ID sp | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| **Example** @@ -503,7 +533,7 @@ Stops Service Extension abilities in the same application with the account ID sp terminateSelf(callback: AsyncCallback<void>): void; -Terminates this ability. This API uses a callback to return the result. +Terminates this ability. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -513,7 +543,7 @@ Terminates this ability. This API uses a callback to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<void> | No| Callback used to return the result indicating whether the API is successfully called.| + | callback | AsyncCallback<void> | No| Callback used to return the result.| **Example** @@ -537,7 +567,7 @@ Terminates this ability. This API uses a promise to return the result. | Type| Description| | -------- | -------- | - | Promise<void> | Promise used to return the result indicating whether the API is successfully called.| + | Promise<void> | Promise used to return the result.| **Example** @@ -563,7 +593,7 @@ Connects this ability to a Service ability. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to connect to, such as the ability name and bundle name.| + | want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability, such as the ability name and bundle name.| | options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.| **Return value** @@ -601,8 +631,8 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the **Want** used for starting an ability.| -| accountId | number | Yes| ID of the account.| +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | options | ConnectOptions | No| Remote object instance.| **Return value** @@ -633,7 +663,7 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect disconnectAbility(connection: number, callback:AsyncCallback<void>): void; -Disconnects this ability from the Service ability. This API uses a callback to return the result. +Disconnects this ability from the Service ability. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -644,7 +674,7 @@ Disconnects this ability from the Service ability. This API uses a callback to r | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | connection | number | Yes| Number returned after **connectAbility** is called.| - | callback | AsyncCallback<void> | No| Callback used to return the result indicating whether the API is successfully called.| + | callback | AsyncCallback<void> | No| Callback used to return the result.| **Example** @@ -676,7 +706,7 @@ Disconnects this ability from the Service ability. This API uses a promise to re | Type| Description| | -------- | -------- | - | Promise<void> | Promise used to return the result indicating whether the API is successfully called.| + | Promise<void> | Promise used to return the result.| **Example** @@ -689,3 +719,41 @@ Disconnects this ability from the Service ability. This API uses a promise to re console.log('failed:' + JSON.stringify(error)); }); ``` + +## ServiceExtensionContext.startAbilityByCall + +startAbilityByCall(want: Want): Promise<Caller>; + +Starts an ability in the background and obtains the caller interface for communication. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-Want.md) | Yes| Information about the target ability, including the ability name, module name, bundle name, and device ID. If the device ID is left blank or the default value is used, the local ability will be started.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<Caller> | Promise used to return the caller object to communicate with.| + +**Example** + + ```js + let caller = undefined; + this.context.startAbilityByCall({ + bundleName: "com.example.myservice", + moduleName: "entry", + abilityName: "MainAbility", + deviceId: "" + }).then((obj) => { + caller = obj; + console.log('Caller GetCaller Get ' + caller); + }).catch((e) => { + console.log('Caller GetCaller error ' + e); + }); + ``` + diff --git a/en/application-dev/reference/apis/js-apis-settings.md b/en/application-dev/reference/apis/js-apis-settings.md index 9371381ea8d39f48410d925bd0b28b441f6a9be6..3cb8380f9f35b7fa584f09b0d88c5fb45e0c22fe 100644 --- a/en/application-dev/reference/apis/js-apis-settings.md +++ b/en/application-dev/reference/apis/js-apis-settings.md @@ -21,7 +21,7 @@ getUriSync(name: string): string Obtains the URI of a data item. -**System capability**: SystemCapability.Applictaions.settings.Core +**System capability**: SystemCapability.Applications.settings.Core **Parameters** @@ -50,7 +50,7 @@ getValueSync(dataAbilityHelper: DataAbilityHelper, name: string, defValue: strin Obtains the value of a data item. -**System capability**: SystemCapability.Applictaions.settings.Core +**System capability**: SystemCapability.Applications.settings.Core **Parameters** | Name| Type| Mandatory| Description| @@ -87,7 +87,7 @@ If the specified data item exists in the database, the **setValueSync** method u **Required permissions**: ohos.permission.MODIFY_SETTINGS -**System capability**: SystemCapability.Applictaions.settings.Core +**System capability**: SystemCapability.Applications.settings.Core **Parameters** diff --git a/en/application-dev/reference/apis/js-apis-sim.md b/en/application-dev/reference/apis/js-apis-sim.md index 41a4cfc71c77ff92c77b4b16ed19de9af6395bd3..958de3d7d1bb9d7295bedac1c844867160d687ca 100644 --- a/en/application-dev/reference/apis/js-apis-sim.md +++ b/en/application-dev/reference/apis/js-apis-sim.md @@ -144,7 +144,7 @@ sim.hasOperatorPrivileges(0, (err, data) => { hasOperatorPrivileges(slotId: number): Promise -Checks whether the application (caller) has been granted the operator permission. This API uses a promise to return the result. +Checks whether the application (caller) has been granted the carrier permission. This API uses a promise to return the result. **System capability**: SystemCapability.Telephony.CoreService @@ -158,7 +158,7 @@ Checks whether the application (caller) has been granted the operator permission | Type | Description | | :----------------- | :---------------------------------------------------------- | -| Promise\ | Promise used to return the result. The value **true** indicates that the application (caller) has been granted the operator permission, and the value **false** indicates the opposite.| +| Promise\ | Promise used to return the result. The value **true** indicates that the application (caller) has been granted the carrier permission, and the value **false** indicates the opposite.| **Example** @@ -184,7 +184,7 @@ Obtains the ISO country code of the SIM card in the specified slot. This API use | Name | Type | Mandatory| Description | | -------- | ----------------------- | ---- | ---------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | -| callback | AsyncCallback\ | Yes | Callback used to return the result, which is an ISO country code, for example, **CN** (China).| +| callback | AsyncCallback\ | Yes | Callback used to return the result. which is an ISO country code, for example, **CN** (China).| **Example** @@ -467,7 +467,7 @@ Checks whether the SIM card in the specified slot is installed. This API uses an **Example** -```jsjs +```js sim.hasSimCard(0, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); @@ -522,7 +522,7 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | --------------------------------------------------- | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| callback | AsyncCallback\<[IccAccountInfo](#IccAccountInfo7)\> | Yes | Callback used to return the result. | +| callback | AsyncCallback\<[IccAccountInfo](#iccaccountinfo7)\> | Yes | Callback used to return the result. | **Example** @@ -555,7 +555,7 @@ This is a system API. | Type | Description | | -------------------------------------------- | ------------------------------------------ | -| Promise<[IccAccountInfo](#IccAccountInfo7)\> | Promise used to return the result.| +| Promise<[IccAccountInfo](#iccaccountinfo7)\> | Promise used to return the result.| **Example** @@ -584,7 +584,7 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | ----------------------------------------------------------- | ---- | ---------- | -| callback | AsyncCallback\\> | Yes | Callback used to return the result.| +| callback | AsyncCallback\\> | Yes | Callback used to return the result.| **Example** @@ -611,7 +611,7 @@ This is a system API. | Type | Description | | ---------------------------------------------------- | ---------------------------------------------- | -| Promise\> | Promise used to return the result.| +| Promise\> | Promise used to return the result.| **Example** @@ -646,7 +646,7 @@ This is a system API. **Example** ```js -sim.setDefaultVoiceSlotId(0,(err, data) => { +sim.setDefaultVoiceSlotId(0, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -672,9 +672,9 @@ This is a system API. **Return value** -| Type | Description | -| -------------- | ------------------------------- | -| Promise\ | Promise used to return the result. | +| Type | Description | +| --------------- | ------------------------------- | +| Promise\ | Promise used to return the result.| **Example** @@ -711,7 +711,7 @@ This is a system API. ```js const name='China Mobile'; -sim.setShowName(0, name,(err, data) => { +sim.setShowName(0, name, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -737,15 +737,15 @@ This is a system API. **Return value** -| Type | Description | -| -------------- | ------------------------------- | -| Promise\ | Promise used to return the result. | +| Type | Description | +| --------------- | ------------------------------- | +| Promise\ | Promise used to return the result.| **Example** ```js const name='China Mobile'; -let promise = sim.setShowName(0,name); +let promise = sim.setShowName(0, name); promise.then(data => { console.log(`setShowName success, promise: data->${JSON.stringify(data)}`); }).catch(err => { @@ -839,8 +839,8 @@ This is a system API. **Example** ```js -let number='+861xxxxxxxxxx'; -sim.setShowNumber(0, number,(err, data) => { +let number = '+861xxxxxxxxxx'; +sim.setShowNumber(0, number, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -869,13 +869,13 @@ This is a system API. | Type | Description | | -------------- | ------------------------------- | -| Promise\ | Promise used to return the result. | +| Promise | Promise used to return the result.| **Example** ```js -let number='+861xxxxxxxxxx'; -let promise = sim.setShowNumber(0,number); +let number = '+861xxxxxxxxxx'; +let promise = sim.setShowNumber(0, number); promise.then(data => { console.log(`setShowNumber success, promise: data->${JSON.stringify(data)}`); }).catch(err => { @@ -994,9 +994,9 @@ This is a system API. **Return value** -| Type | Description | -| -------------- | ------------------------------- | -| Promise\ | Promise used to return the result. | +| Type | Description | +| --------------- | ------------------------------- | +| Promise\ | Promise used to return the result.| **Example** @@ -1057,8 +1057,8 @@ This is a system API. **Return value** -| Type | Description | -| -------------- | ------------------------------- | +| Type | Description | +| --------------- | ------------------------------- | | Promise\ | Promise used to return the result.| **Example** @@ -1089,16 +1089,18 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | -| callback | AsyncCallback\<[LockStatusResponse](#LockStatusResponse7)\> | Yes | Callback used to return the result. | -| options | [LockInfo](#LockInfo8) | Yes | Lock information.
- **lockType**: [LockType](#LockType8)
- **password**: string
- **state**: [LockState](#LockState8) | +| callback | AsyncCallback\<[LockStatusResponse](#lockstatusresponse7)\> | Yes | Callback used to return the result. | +| options | [LockInfo](#lockinfo8) | Yes | Lock information.
lockType: [LockType](#locktype8)
password: string
state: [LockState](#lockstate8) | **Example** ```js -LockInfo.lockType = 1; -LockInfo.password = "1234"; -LockInfo.state = 0; -sim.setLockState(0, LockInfo, (err, data) => { +let lockInfo = { + lockType = 1, + password = "1234", + state = 0 +}; +sim.setLockState(0, lockInfo, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -1121,21 +1123,23 @@ This is a system API. | Name | Type | Mandatory| Description | | ------- | ---------------------- | ---- | ------------------------------------------------------------ | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | -| options | [LockInfo](#LockInfo8) | Yes | Lock information.
- **lockType**: [LockType](#LockType8)
**password**: string
**state**: [LockState](#LockState8) | +| options | [LockInfo](#lockinfo8) | Yes | Lock information.
lockType: [LockType](#locktype8)
password: string
state: [LockState](#lockstate8) | **Return value** | Type | Description | | ---------------------------------------------------- | -------------------------------------------- | -| Promise<[LockStatusResponse](#LockStatusResponse7)\> | Promise used to return the result.| +| Promise<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Example** ```js -LockInfo.lockType = 1; -LockInfo.password = "1234"; -LockInfo.state = 0; -let promise = sim.setLockState(0, LockInfo); +let lockInfo = { + lockType = 1, + password = "1234", + state = 0 +}; +let promise = sim.setLockState(0, lockInfo); promise.then(data => { console.log(`setLockState success, promise: data->${JSON.stringify(data)}`); }).catch(err => { @@ -1158,8 +1162,8 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | ----------------------------------------- | ---- | --------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | -| callback | AsyncCallback\<[LockState](#LockState8)\> | Yes | Callback used to return the result. | -| options | [LockType](#LockType8) | Yes | Lock type.
- **1**: PIN lock
- **2**: PIN2 lock| +| callback | AsyncCallback\<[LockState](#lockstate8)\> | Yes | Callback used to return the result. | +| options | [LockType](#locktype8) | Yes | Lock type.
- **1**: PIN lock
- **2**: PIN 2 lock| **Example** @@ -1185,13 +1189,13 @@ This is a system API. | Name | Type | Mandatory| Description | | ------- | ---------------------- | ---- | --------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | -| options | [LockType](#LockType8) | Yes | Lock type.
- **1**: PIN lock
- **2**: PIN2 lock| +| options | [LockType](#locktype8) | Yes | Lock type.
- **1**: PIN lock
- **2**: PIN 2 lock| **Return value** | Type | Description | | ---------------------------------- | -------------------------------------------- | -| Promise<[LockState](#LockState8)\> | Promise used to return the result.| +| Promise<[LockState](#lockstate8)\> | Promise used to return the result.| **Example** @@ -1208,7 +1212,7 @@ promise.then(data => { alterPin(slotId: number, newPin: string, oldPin: string, callback: AsyncCallback): void -Changes the PIN. This API uses an asynchronous callback to return the result. +Changes the PIN of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. This is a system API. @@ -1221,14 +1225,14 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | ----------------------------------------------------------- | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| callback | AsyncCallback\<[LockStatusResponse](#LockStatusResponse7)\> | Yes | Callback used to return the result. | +| callback | AsyncCallback\<[LockStatusResponse](#lockstatusresponse7)\> | Yes | Callback used to return the result. | | newPin | string | Yes | New PIN. | | oldPin | string | Yes | Old PIN. | **Example** ```js -sim.alterPin(0, "1234", "0000"(err, data) => { +sim.alterPin(0, "1234", "0000", (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -1238,7 +1242,7 @@ sim.alterPin(0, "1234", "0000"(err, data) => { alterPin(slotId: number, newPin: string, oldPin: string): Promise; -Changes the PIN. This API uses a promise to return the result. +Changes the PIN of the SIM card in the specified slot. This API uses a promise to return the result. This is a system API. @@ -1258,7 +1262,7 @@ This is a system API. | Type | Description | | ---------------------------------------------------- | --------------------------------------------- | -| Promise<[LockStatusResponse](#LockStatusResponse7)\> | Promise used to return the result.| +| Promise<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Example** @@ -1275,7 +1279,7 @@ promise.then(data => { alterPin2(slotId: number, newPin2: string, oldPin2: string, callback: AsyncCallback): void -Changes PIN 2. This API uses an asynchronous callback to return the result. +Changes PIN 2 of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. This is a system API. @@ -1288,7 +1292,7 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | ----------------------------------------------------------- | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| callback | AsyncCallback\<[LockStatusResponse](#LockStatusResponse7)\> | Yes | Callback used to return the result. | +| callback | AsyncCallback\<[LockStatusResponse](#lockstatusresponse7)\> | Yes | Callback used to return the result. | | newPin2 | string | Yes | New PIN. | | oldPin2 | string | Yes | Old PIN. | @@ -1305,7 +1309,7 @@ sim.alterPin2(0, "1234", "0000", (err, data) => { alterPin2(slotId: number, newPin2: string, oldPin2: string): Promise -Changes PIN 2. This API uses a promise to return the result. +Changes PIN 2 of the SIM card in the specified slot. This API uses a promise to return the result. This is a system API. @@ -1325,12 +1329,12 @@ This is a system API. | Type | Description | | ---------------------------------------------------- | --------------------------------------------- | -| Promise<[LockStatusResponse](#LockStatusResponse7)\> | Promise used to return the result.| +| Promise<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Example** ```js -let promise = sim.alterPin2(0, "1234","0000"); +let promise = sim.alterPin2(0, "1234", "0000"); promise.then(data => { console.log(`alterPin2 success, promise: data->${JSON.stringify(data)}`); }).catch(err => { @@ -1342,7 +1346,7 @@ promise.then(data => { unlockPin(slotId: number,pin: string ,callback: AsyncCallback): void -Unlocks the PIN of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. +Unlocks PIN of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. This is a system API. @@ -1356,13 +1360,13 @@ This is a system API. | -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| | pin | string | Yes | PIN of the SIM card. | -| callback | AsyncCallback<[LockStatusResponse](#LockStatusResponse7)> | Yes | Callback used to return the result. | +| callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)> | Yes | Callback used to return the result. | **Example** ```js -let pin='1234'; -sim.unlockPin(0, pin,(err, data) => { +let pin = '1234'; +sim.unlockPin(0, pin, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -1391,13 +1395,13 @@ This is a system API. | Type | Description | | ---------------------------------------------------- | -------------------------------------------------- | -| Promise\<[LockStatusResponse](#LockStatusResponse)\> | Promise used to return the result.| +| Promise\<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Example** ```js -let pin='1234'; -let promise = sim.unlockPin(0,pin); +let pin = '1234'; +let promise = sim.unlockPin(0, pin); promise.then(data => { console.log(`unlockPin success, promise: data->${JSON.stringify(data)}`); }).catch(err => { @@ -1424,14 +1428,14 @@ This is a system API. | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| | newPin | string | Yes | New PIN. | | puk | string | Yes | PUK of the SIM card. | -| callback | AsyncCallback<[LockStatusResponse](#LockStatusResponse7)> | Yes | Callback used to return the result. | +| callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)> | Yes | Callback used to return the result. | **Example** ```js -let puk='1xxxxxxx'; -let newPin='1235'; -sim.unlockPuk(0, newPin,puk,(err, data) => { +let puk = '1xxxxxxx'; +let newPin = '1235'; +sim.unlockPuk(0, newPin, puk, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -1461,14 +1465,14 @@ This is a system API. | Type | Description | | ---------------------------------------------------- | -------------------------------------------------- | -| Promise\<[LockStatusResponse](#LockStatusResponse)\> | Promise used to return the result.| +| Promise\<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Example** ```js -let puk='1xxxxxxx'; -let newPin='1235'; -let promise = sim.unlockPuk(0,newPin,puk); +let puk = '1xxxxxxx'; +let newPin = '1235'; +let promise = sim.unlockPuk(0, newPin, puk); promise.then(data => { console.log(`unlockPuk success, promise: data->${JSON.stringify(data)}`); }).catch(err => { @@ -1493,14 +1497,14 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| pin2 | string | Yes | PIN of the SIM card. | -| callback | AsyncCallback<[LockStatusResponse](#LockStatusResponse7)> | Yes | Callback used to return the result. | +| pin2 | string | Yes | PIN 2 of the SIM card. | +| callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)> | Yes | Callback used to return the result. | **Example** ```js -let pin2='1234'; -sim.unlockPin2(0, pin2,(err, data) => { +let pin2 = '1234'; +sim.unlockPin2(0, pin2, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -1523,13 +1527,13 @@ This is a system API. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| pin2 | string | Yes | PIN of the SIM card. | +| pin2 | string | Yes | PIN 2 of the SIM card. | **Return value** | Type | Description | | ----------------------------------------------------- | -------------------------------------------------- | -| Promise\<[LockStatusResponse](#LockStatusResponse7)\> | Promise used to return the result.| +| Promise\<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Example** @@ -1560,16 +1564,16 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| newPin2 | string | Yes | New PIN. | -| puk2 | string | Yes | PUK of the SIM card. | -| callback | AsyncCallback<[LockStatusResponse](#LockStatusResponse7)> | Yes | Callback used to return the result. | +| newPin2 | string | Yes | New PIN 2. | +| puk2 | string | Yes | PUK 2 of the SIM card. | +| callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)> | Yes | Callback used to return the result. | **Example** ```js -let puk2='1xxxxxxx'; -let newPin2='1235'; -sim.unlockPuk2(0, newPin2,puk2,(err, data) => { +let puk2 = '1xxxxxxx'; +let newPin2 = '1235'; +sim.unlockPuk2(0, newPin2, puk2, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -1592,21 +1596,21 @@ This is a system API. | Name | Type | Mandatory| Description | | ------- | ------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| newPin2 | string | Yes | New PIN. | -| puk2 | string | Yes | PUK of the SIM card. | +| newPin2 | string | Yes | New PIN 2. | +| puk2 | string | Yes | PUK 2 of the SIM card. | **Return value** | Type | Description | | ---------------------------------------------------- | -------------------------------------------------- | -| Promise\<[LockStatusResponse](#LockStatusResponse)\> | Promise used to return the result.| +| Promise\<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Example** ```js -let puk2='1xxxxxxx'; -let newPin2='1235'; -let promise = sim.unlockPuk2(0,newPin2,puk2); +let puk2 = '1xxxxxxx'; +let newPin2 = '1235'; +let promise = sim.unlockPuk2(0, newPin2, puk2); promise.then(data => { console.log(`unlockPuk2 success, promise: data->${JSON.stringify(data)}`); }).catch(err => { @@ -1634,142 +1638,1313 @@ Obtains the number of card slots. console.log("Result: "+ sim.getMaxSimCount()) ``` +## sim.getSimIccId7+ -## SimState +getSimIccId(slotId: number, callback: AsyncCallback): void -Enumerates SIM card states. +Obtains the IC card identity (ICCID) of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE **System capability**: SystemCapability.Telephony.CoreService -| Name | Value | Description | -| --------------------- | ---- | ---------------------------------------------------------- | -| SIM_STATE_UNKNOWN | 0 | The SIM card is in **unknown** state; that is, the SIM card status cannot be obtained. | -| SIM_STATE_NOT_PRESENT | 1 | The SIM card is in **not present** state; that is, no SIM card is inserted into the card slot. | -| SIM_STATE_LOCKED | 2 | The SIM card is in **locked** state; that is, the SIM card is locked by the personal identification number (PIN), PIN unblocking key (PUK), or network. | -| SIM_STATE_NOT_READY | 3 | The SIM card is in **not ready** state; that is, the SIM card has been installed but cannot work properly. | -| SIM_STATE_READY | 4 | The SIM card is in **ready** state; that is, the SIM card has been installed and is working properly. | -| SIM_STATE_LOADED | 5 | The SIM card is in **loaded** state; that is, the SIM card is present and all its files have been loaded.| +**Parameters** -## CardType7+ +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +sim.getSimIccId(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.getSimIccId7+ + +getSimIccId(slotId: number): Promise + +Obtains the ICCID of the SIM card in the specified slot. This API uses a promise to return the result. -Enumerates card types. +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE **System capability**: SystemCapability.Telephony.CoreService -| Name| Value| Description| -| ----- | ----- | ----- | -|UNKNOWN_CARD | -1 | Unknown| -|SINGLE_MODE_SIM_CARD | 10 | Single-card (SIM)| -|SINGLE_MODE_USIM_CARD | 20 | Single-card (USIM)| -|SINGLE_MODE_RUIM_CARD | 30 | Single-card (RUIM)| -|DUAL_MODE_CG_CARD | 40 | Dual-card (CDMA+GSM)| -|CT_NATIONAL_ROAMING_CARD | 41 | China Telecom internal roaming card| -|CU_DUAL_MODE_CARD | 42 | China Unicom dual-mode card| -|DUAL_MODE_TELECOM_LTE_CARD | 43 | China Telecom dual-mode LTE card| -|DUAL_MODE_UG_CARD | 50 | Dual-mode card (UMTS+GSM)| -|SINGLE_MODE_ISIM_CARD8+ | 60 | Single-card (ISIM)| +**Parameters** -## LockType8+ +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -Enumerates lock types. +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.getSimIccId(0); +promise.then(data => { + console.log(`getSimIccId success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getSimIccId fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.getVoiceMailIdentifier8+ + +getVoiceMailIdentifier(slotId: number, callback: AsyncCallback): void + +Obtains the voice mailbox alpha identifier of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. This is a system API. +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + **System capability**: SystemCapability.Telephony.CoreService -| Name | Value | Description | -| -------- | ---- | ----------- | -| PIN_LOCK | 1 | SIM card password lock| -| FDN_LOCK | 2 | Fixed dialing lock | +**Parameters** -## LockState8+ +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +sim.getVoiceMailIdentifier(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` -Enumerates lock states. + +## sim.getVoiceMailIdentifier8+ + +getVoiceMailIdentifier(slotId: number): Promise + +Obtains the voice mailbox alpha identifier of the SIM card in the specified slot. This API uses a promise to return the result. This is a system API. +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + **System capability**: SystemCapability.Telephony.CoreService -| Name | Value | Description | -| -------- | ---- | ---------- | -| LOCK_OFF | 0 | The lock is off.| -| LOCK_ON | 1 | The lock is on.| +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -## **PersoLockType**8+ +**Return value** -Enumerates personalized lock types. +| Type | Description | +| ---------------- | ------------------------------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.getVoiceMailIdentifier(0); +promise.then(data => { + console.log(`getVoiceMailIdentifier success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getVoiceMailIdentifier fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.getVoiceMailNumber8+ + +getVoiceMailNumber(slotId: number, callback: AsyncCallback): void + +Obtains the voice mailbox number of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. This is a system API. +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + **System capability**: SystemCapability.Telephony.CoreService -| Name | Value | Description | -| ------------ | ---- | ----------------------------------------------- | -| PN_PIN_LOCK | 0 | Personalized network PIN lock. For details, see *3GPP TS 22.022 [33]*. | -| PN_PUK_LOCK | 1 | Personalized network PUK lock. | -| PU_PIN_LOCK | 2 | Personalized network subset PIN lock. For details, see *3GPP TS 22.022 [33]*. | -| PU_PUK_LOCK | 3 | Personalized network subset PUK lock. | -| PP_PIN_LOCK | 4 | Personalized service provider PIN lock. For details, see *3GPP TS 22.022 [33]*.| -| PP_PUK_LOCK | 5 | Personalized service provider PUK lock. | -| PC_PIN_LOCK | 6 | Personalized corporate PIN lock. For details, see *3GPP TS 22.022 [33]*. | -| PC_PUK_LOCK | 7 | Personalized corporate PUK lock. | -| SIM_PIN_LOCK | 8 | Personalized SIM card PIN lock. For details, see *3GPP TS 22.022 [33]*. | -| SIM_PUK_LOCK | 9 | Personalized SIM card PUK lock. | +**Parameters** -## **LockStatusResponse**7+ +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback | Yes | Callback used to return the result. | -Defines the lock status response. +**Example** + +```js +sim.getVoiceMailNumber(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.getVoiceMailNumber8+ + +getVoiceMailNumber(slotId: number): Promise + +Obtains the voice mailbox number of the SIM card in the specified slot. This API uses a promise to return the result. This is a system API. +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + **System capability**: SystemCapability.Telephony.CoreService -| Name | Type | Description | -| --------------- | ------ | ------------------ | -| result | number | Operation result. | -| remain?: number | number | Remaining attempts (can be null).| +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------------ | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.getVoiceMailNumber(0); +promise.then(data => { + console.log(`getVoiceMailNumber success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getVoiceMailNumber fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.setVoiceMailInfo8+ -## **LockInfo**8+ +setVoiceMailInfo(slotId: number, mailName: string, mailNumber: string, callback: AsyncCallback): void -Defines the personalized lock status response. +Sets voice mailbox information for the SIM card in the specified slot. This API uses an asynchronous callback to return the result. This is a system API. +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + **System capability**: SystemCapability.Telephony.CoreService -| Name | Type | Description | -| -------- | --------- | ------ | -| lockType | LockType | Lock type.| -| password | string | Password. | -| state | LockState | Lock state.| +**Parameters** -## **PersoLockInfo**8+ +| Name | Type | Mandatory| Description | +| ---------- | -------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| mailName | string | Yes | Voice mailbox name. | +| mailNumber | string | Yes | Voice mailbox number. | +| callback | AsyncCallback | Yes | Callback used to return the result. | -Defines the personalized lock information. +**Example** + +```js +sim.setVoiceMailInfo(0, "mail", "xxx@xxx.com" , (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.setVoiceMailInfo8+ + +setVoiceMailInfo(slotId: number, mailName: string, mailNumber: string): Promise + +Sets voice mailbox information for the SIM card in the specified slot. This API uses a promise to return the result. This is a system API. +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + **System capability**: SystemCapability.Telephony.CoreService -| Name | Type | Description | -| -------- | ------------- | ------------ | -| lockType | PersoLockType | Personalized lock type.| -| password | string | Password. | +**Parameters** -## **IccAccountInfo**7+ +| Name | Type | Mandatory| Description | +| ---------- | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| mailName | string | Yes | Voice mailbox name. | +| mailNumber | string | Yes | Voice mailbox number. | -Defines the ICC account information. +**Return value** + +| Type | Description | +| -------------- | ----------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.setVoiceMailInfo(0, "mail", "xxx@xxx.com"); +promise.then(data => { + console.log(`setVoiceMailInfo success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`setVoiceMailInfo fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.getSimTelephoneNumber8+ + +getSimTelephoneNumber(slotId: number, callback: AsyncCallback): void + +Obtains the mobile subscriber ISDN number (MSISDN) of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. This is a system API. +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + **System capability**: SystemCapability.Telephony.CoreService -| Name | Type | Description | -| ---------- | ------- | ---------------- | -| simId | number | SIM card ID. | -| slotIndex | number | Card slot ID. | -| isEsim | boolean | Whether the SIM card is an eSim card.| -| isActive | boolean | Whether the card is activated. | -| iccId | string | ICCID number. | -| showName | string | SIM card display name. | -| showNumber | string | SIM card display number. | +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +sim.getSimTelephoneNumber(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.getSimTelephoneNumber8+ + +getSimTelephoneNumber(slotId: number): Promise + +Obtains the MSISDN of the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ---------------- | -------------------------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.getSimTelephoneNumber(0); +promise.then(data => { + console.log(`getSimTelephoneNumber success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getSimTelephoneNumber fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.getSimGid17+ + +getSimGid1(slotId: number, callback: AsyncCallback): void + +Obtains the group identifier level 1 (GID1) of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```js +sim.getSimGid1(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.getSimGid17+ + +getSimGid1(slotId: number): Promise + +Obtains the GID1 of the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.getSimGid1(0); +promise.then(data => { + console.log(`getSimGid1 success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getSimGid1 fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.getIMSI + +getIMSI(slotId: number, callback: AsyncCallback): void + +Obtains the international mobile subscriber identity (IMSI) of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```js +sim.getIMSI(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.getIMSI + +getIMSI(slotId: number): Promise + +Obtains the IMSI of the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.getIMSI(0); +promise.then(data => { + console.log(`getIMSI success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getIMSI fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.getOperatorConfigs8+ + +getOperatorConfigs(slotId: number, callback: AsyncCallback>): void + +Obtains the carrier configuration of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback> | Yes | Callback used to return the result. | + +**Example** + +```js +sim.getOperatorConfigs(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.getOperatorConfigs8+ + +getOperatorConfigs(slotId: number): Promise> + +Obtains the carrier configuration of the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.GET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| --------------------------------------------------- | ----------------------------- | +| Promise> | Promise used to return the result.| + +**Example** + +```js +let promise = sim.getOperatorConfigs(0); +promise.then(data => { + console.log(`getOperatorConfigs success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getOperatorConfigs fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.queryIccDiallingNumbers8+ + +queryIccDiallingNumbers(slotId: number, type: ContactType, callback: AsyncCallback>): void + +Queries contact numbers of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Permission required**: ohos.permission.READ_CONTACTS + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ---------------------------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| type | [ContactType](#contacttype8) | Yes | Contact type.
1 : GENERAL_CONTACT
2 : FIXED_DIALING | +| callback | AsyncCallback> | Yes | Callback used to return the result. | + +**Example** + +```js +sim.queryIccDiallingNumbers(0, 1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.queryIccDiallingNumbers8+ + +queryIccDiallingNumbers(slotId: number, type: ContactType): Promise> + +Queries contact numbers of the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Permission required**: ohos.permission.READ_CONTACTS + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ----------- | ---- | ---------------------------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| type | [ContactType](#contacttype8) | Yes | Contact type.
1 : GENERAL_CONTACT
2 : FIXED_DIALING | + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ------------------------------ | +| Promise> | Promise used to return the result.| + +**Example** + +```js +let promise = sim.queryIccDiallingNumbers(0, 1); +promise.then(data => { + console.log(`queryIccDiallingNumbers success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`queryIccDiallingNumbers fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.addIccDiallingNumbers8+ + +addIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: DiallingNumbersInfo, callback: AsyncCallback): void + +Adds contact numbers for the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Permission required**: ohos.permission.WRITE_CONTACTS + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| type | [ContactType](#contacttype8) | Yes | Contact type.
**1**: GENERAL_CONTACT
**2**: FIXED_DIALING | +| diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +let diallingNumbersInof = { + alphaTag = "alpha", + number = "138xxxxxxxx", + recordNumber = 123, + pin2 = "1234" +}; +sim.addIccDiallingNumbers(0, 1, diallingNumbersInof, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.addIccDiallingNumbers8+ + +addIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: DiallingNumbersInfo): Promise + +Adds contact numbers for the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Permission required**: ohos.permission.WRITE_CONTACTS + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| type | [ContactType](#contacttype8) | Yes | Contact type.
**1**: GENERAL_CONTACT
**2**: FIXED_DIALING | +| diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | + +**Return value** + +| Type | Description | +| -------------- | --------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let diallingNumbersInof = { + alphaTag = "alpha", + number = "138xxxxxxxx", + recordNumber = 123, + pin2 = "1234" +}; +let promise = sim.addIccDiallingNumbers(0, 1, diallingNumbersInof); +promise.then(data => { + console.log(`addIccDiallingNumbers success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`addIccDiallingNumbers fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.delIccDiallingNumbers8+ + +delIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: DiallingNumbersInfo, callback: AsyncCallback): void + +Deletes contact numbers from the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Permission required**: ohos.permission.WRITE_CONTACTS + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| type | [ContactType](#contacttype8) | Yes | Contact type.
**1**: GENERAL_CONTACT
**2**: FIXED_DIALING | +| diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +let diallingNumbersInof = { + alphaTag = "alpha", + number = "138xxxxxxxx", + recordNumber = 123, + pin2 = "1234" +}; +sim.delIccDiallingNumbers(0, 1, diallingNumbersInof, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.delIccDiallingNumbers8+ + +delIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: DiallingNumbersInfo): Promise + +Deletes contact numbers from the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Permission required**: ohos.permission.WRITE_CONTACTS + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| type | [ContactType](#contacttype8) | Yes | Contact type.
**1**: GENERAL_CONTACT
**2**: FIXED_DIALING | +| diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | + +**Return value** + +| Type | Description | +| -------------- | --------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let diallingNumbersInof = { + alphaTag = "alpha", + number = "138xxxxxxxx", + recordNumber = 123, + pin2 = "1234" +}; +let promise = sim.delIccDiallingNumbers(0, 1, diallingNumbersInof); +promise.then(data => { + console.log(`delIccDiallingNumbers success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`delIccDiallingNumbers fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.updateIccDiallingNumbers8+ + +updateIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: DiallingNumbersInfo, callback: AsyncCallback): void + +Updates contact numbers for the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Permission required**: ohos.permission.WRITE_CONTACTS + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| type | [ContactType](#contacttype8) | Yes | Contact type.
**1**: GENERAL_CONTACT
**2**: FIXED_DIALING | +| diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +let diallingNumbersInof = { + alphaTag = "alpha", + number = "138xxxxxxxx", + recordNumber = 123, + pin2 = "1234" +}; +sim.updateIccDiallingNumbers(0, 1, diallingNumbersInof, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.updateIccDiallingNumbers8+ + +updateIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: DiallingNumbersInfo): Promise + +Updates contact numbers for the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Permission required**: ohos.permission.WRITE_CONTACTS + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | +| type | [ContactType](#contacttype8) | Yes | Contact type.
**1**: GENERAL_CONTACT
**2**: FIXED_DIALING | +| diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | + +**Return value** + +| Type | Description | +| -------------- | ----------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let diallingNumbersInof = { + alphaTag = "alpha", + number = "138xxxxxxxx", + recordNumber = 123, + pin2 = "1234" +}; +let promise = sim.updateIccDiallingNumbers(0, 1, diallingNumbersInof); +promise.then(data => { + console.log(`updateIccDiallingNumbers success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`updateIccDiallingNumbers fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.sendEnvelopeCmd8+ + +sendEnvelopeCmd(slotId: number, cmd: string, callback: AsyncCallback): void + +Sends an envelope command to the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| cmd | string | Yes | Envelope command. | +| callback | AsyncCallback | Yes | Yes | + +**Example** + +```js +sim.sendEnvelopeCmd(0, "ls", (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.sendEnvelopeCmd8+ + +sendEnvelopeCmd(slotId: number, cmd: string): Promise + +Sends an envelope command to the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| cmd | string | Yes | Envelope command. | + +**Return value** + +| Type | Description | +| -------------- | --------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.sendEnvelopeCmd(0, "ls"); +promise.then(data => { + console.log(`sendEnvelopeCmd success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`sendEnvelopeCmd fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.sendTerminalResponseCmd8+ + +sendTerminalResponseCmd(slotId: number, cmd: string, callback: AsyncCallback): void + +Sends a terminal response command to the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| cmd | string | Yes | Command | +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +sim.sendTerminalResponseCmd(0, "ls", (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.sendTerminalResponseCmd8+ + +sendTerminalResponseCmd(slotId: number, cmd: string): Promise + +Sends a terminal response command to the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| cmd | string | Yes | Command | + +**Return value** + +| Type | Description | +| -------------- | --------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.sendTerminalResponseCmd(0, "ls"); +promise.then(data => { + console.log(`sendTerminalResponseCmd success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`sendTerminalResponseCmd fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.unlockSimLock8+ + +unlockSimLock(slotId: number, lockInfo: PersoLockInfo, callback: AsyncCallback): void + +Unlocks the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| lockInfo | [PersoLockInfo](#persolockinfo8) | Yes | Personalized lock information. | +| callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)\> | Yes | Callback used to return the result. | + +**Example** + +```js +let persoLockInfo = { + lockType = 0, + password = "1234" +}; +sim.unlockSimLock(0, persoLockInfo, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.unlockSimLock8+ + +unlockSimLock(slotId: number, lockInfo: PersoLockInfo): Promise + +Unlocks the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| lockInfo | [PersoLockInfo](#persolockinfo8) | Yes | Personalized lock information. | + +**Return value** + +| Type | Description | +| ---------------------------------------------------- | ------------------------- | +| Promise<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| + +**Example** + +```js +let persoLockInfo = { + lockType = 0, + password = "1234" +}; +let promise = sim.unlockSimLock(0, persoLockInfo); +promise.then(data => { + console.log(`unlockSimLock success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`unlockSimLock fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.getOpKey9+ + +getOpKey(slotId: number, callback: AsyncCallback): void + +Obtains the opkey of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +sim.getOpKey(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.getOpKey9+ + +getOpKey(slotId: number): Promise + +Obtains the opkey of the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ---------------- | ----------------------------------------- | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.getOpKey(0); +promise.then(data => { + console.log(`getOpKey success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getOpKey fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sim.getOpName9+ + +getOpName(slotId: number, callback: AsyncCallback): void + +Obtains the OpName of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback | Yes | Callback used to return the result. | + +**Example** + +```js +sim.getOpName(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sim.getOpName9+ + +getOpName(slotId: number): Promise + +Obtains the OpName of the SIM card in the specified slot. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------ | +| Promise | Promise used to return the result.| + +**Example** + +```js +let promise = sim.getOpName(0); +promise.then(data => { + console.log(`getOpName success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getOpName fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## SimState + +Enumerates SIM card states. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| --------------------- | ---- | ---------------------------------------------------------- | +| SIM_STATE_UNKNOWN | 0 | The SIM card is in **unknown** state; that is, the SIM card status cannot be obtained. | +| SIM_STATE_NOT_PRESENT | 1 | The SIM card is in **not present** state; that is, no SIM card is inserted into the card slot. | +| SIM_STATE_LOCKED | 2 | The SIM card is in **locked** state; that is, the SIM card is locked by the personal identification number (PIN), PIN unblocking key (PUK), or network. | +| SIM_STATE_NOT_READY | 3 | The SIM card is in **not ready** state; that is, the SIM card has been installed but cannot work properly. | +| SIM_STATE_READY | 4 | The SIM card is in **ready** state; that is, the SIM card has been installed and is working properly. | +| SIM_STATE_LOADED | 5 | The SIM card is in **loaded** state; that is, the SIM card is present and all its files have been loaded.| + +## CardType7+ + +Enumerates SIM card types. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name| Value| Description| +| ----- | ----- | ----- | +|UNKNOWN_CARD | -1 | Unknown| +|SINGLE_MODE_SIM_CARD | 10 | Single-card (SIM)| +|SINGLE_MODE_USIM_CARD | 20 | Single-card (USIM)| +|SINGLE_MODE_RUIM_CARD | 30 | Single-card (RUIM)| +|DUAL_MODE_CG_CARD | 40 | Dual-card (CDMA+GSM)| +|CT_NATIONAL_ROAMING_CARD | 41 | China Telecom internal roaming card| +|CU_DUAL_MODE_CARD | 42 | China Unicom dual-mode card| +|DUAL_MODE_TELECOM_LTE_CARD | 43 | China Telecom dual-mode LTE card| +|DUAL_MODE_UG_CARD | 50 | Dual-mode card (UMTS+GSM)| +|SINGLE_MODE_ISIM_CARD8+ | 60 | Single-card (ISIM)| + +## LockType8+ + +Enumerates lock types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| -------- | ---- | ----------- | +| PIN_LOCK | 1 | SIM card password lock.| +| FDN_LOCK | 2 | Fixed dialing lock. | + +## LockState8+ + +Enumerates lock states. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| -------- | ---- | ---------- | +| LOCK_OFF | 0 | The lock is off.| +| LOCK_ON | 1 | The lock is on.| + +## PersoLockType8+ + +Enumerates personalized lock types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| ------------ | ---- | ----------------------------------------------- | +| PN_PIN_LOCK | 0 | Personalized network PIN lock. For details, see *3GPP TS 22.022 [33]*. | +| PN_PUK_LOCK | 1 | Personalized network PUK lock. | +| PU_PIN_LOCK | 2 | Personalized network subset PIN lock. For details, see *3GPP TS 22.022 [33]*. | +| PU_PUK_LOCK | 3 | Personalized network subset PUK lock. | +| PP_PIN_LOCK | 4 | Personalized service provider PIN lock. For details, see *3GPP TS 22.022 [33]*.| +| PP_PUK_LOCK | 5 | Personalized service provider PUK lock. | +| PC_PIN_LOCK | 6 | Personalized corporate PIN lock. For details, see *3GPP TS 22.022 [33]*. | +| PC_PUK_LOCK | 7 | Personalized corporate PUK lock. | +| SIM_PIN_LOCK | 8 | Personalized SIM card PIN lock. For details, see *3GPP TS 22.022 [33]*. | +| SIM_PUK_LOCK | 9 | Personalized SIM card PUK lock. | + +## LockStatusResponse7+ + +Defines the lock status response. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| --------------- | ------ | ------------------ | +| result | number | Operation result. | +| remain?: number | number | Remaining attempts (can be null).| + +## LockInfo8+ + +Defines the lock information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| -------- | ------------------------ | ------ | +| lockType | [LockType](#locktype8) | Lock type.| +| password | string | Password. | +| state | [LockState](#lockstate8) | Lock state.| + +## PersoLockInfo8+ + +Defines the personalized lock information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| -------- | -------------------------------- | ------------ | +| lockType | [PersoLockType](#persolocktype8) | Personalized lock type.| +| password | string | Password. | + +## IccAccountInfo7+ + +Defines the ICC account information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ---------- | ------- | ---------------- | +| simId | number | SIM card ID. | +| slotIndex | number | Card slot ID. | +| isEsim | boolean | Whether the SIM card is an eSim card.| +| isActive | boolean | Whether the card is activated. | +| iccId | string | ICCID number. | +| showName | string | SIM card display name. | +| showNumber | string | SIM card display number. | + +## OperatorConfig8+ + +Defines the carrier configuration. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description| +| ----- | ------ | ---- | +| field | string | Field| +| value | string | Value | + +## DiallingNumbersInfo8+ + +Defines the contact number information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ------------ | ------ | -------- | +| alphaTag | string | Alpha tag. | +| number | string | Contact number. | +| recordNumber | number | Record number.| +| pin2 | string | PIN 2.| + +## ContactType8+ + +Enumerates contact types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| :-------------- | ---- | ---------- | +| GENERAL_CONTACT | 1 | Common contact number.| +| FIXED_DIALING | 2 | Fixed dialing number. | diff --git a/en/application-dev/reference/apis/js-apis-sms.md b/en/application-dev/reference/apis/js-apis-sms.md index 25069b318add375d68d97084e45b08c1f69f3804..fa226f072e2a1c4aa568937455e7ee78e3513469 100644 --- a/en/application-dev/reference/apis/js-apis-sms.md +++ b/en/application-dev/reference/apis/js-apis-sms.md @@ -174,7 +174,7 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: Clears the default configuration.| +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: clearing the default configuration| | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** @@ -202,7 +202,7 @@ This is a system API. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: Clears the default configuration.| +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: clearing the default configuration| **Return value** @@ -360,7 +360,7 @@ promise.then(data => { hasSmsCapability(): boolean -Checks whether the current device can send and receive SMS messages. This API works in synchronous mode. +Checks whether the current device can send and receive SMS messages. This API returns the result synchronously. **System capability**: SystemCapability.Telephony.SmsMms @@ -375,6 +375,739 @@ let result = sms.hasSmsCapability(); console.log(`hasSmsCapability: ${JSON.stringify(result)}`); ``` +## sms.splitMessage8+ + +splitMessage(content: string, callback: AsyncCallback>): void + +Splits an SMS message into multiple segments. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SEND_MESSAGES + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------- | ---- | ----------------------------- | +| content | string | Yes | SMS message content. The value cannot be null.| +| callback | AsyncCallback> | Yes | Callback used to return the result. | + +**Example** + +```js +string content= "long message"; +sms.splitMessage(content, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.splitMessage8+ + +splitMessage(content: string): Promise> + +Splits an SMS message into multiple segments. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SEND_MESSAGES + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------ | ---- | ---------------------------- | +| content | string | Yes | SMS message content. The value cannot be null.| + +**Return value** + +| Type | Description | +| ----------------------- | ----------------------------------- | +| Promise> | Promise used to return the result.| + +**Example** + +```js +string content = "long message"; +let promise = sms.splitMessage(content); +promise.then(data => { + console.log(`splitMessage success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`splitMessage fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.addSimMessage7+ + +addSimMessage(options: SimMessageOptions, callback: AsyncCallback): void + +Adds a SIM message. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS,ohos.permission.SEND_MESSAGES + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------- | ---- | --------------- | +| options | [SimMessageOptions](#simmessageoptions7) | Yes | SIM message options.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +let simMessageOptions = { + slotId = 0, + smsc = "test", + pdu = "xxxxxx", + status = 0 +}; +sms.addSimMessage(simMessageOptions, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.addSimMessage7+ + +addSimMessage(options: SimMessageOptions): Promise + +Adds a SIM message. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS,ohos.permission.SEND_MESSAGES + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------------------------------- | ---- | --------------- | +| options | [SimMessageOptions](#simmessageoptions7) | Yes | SIM message options.| + +**Return value** + +| Type | Description | +| ------------------- | ----------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let simMessageOptions = { + slotId = 0, + smsc = "test", + pdu = "xxxxxx", + status = 0 +}; +let promise = sms.addSimMessage(simMessageOptions); +promise.then(data => { + console.log(`addSimMessage success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`addSimMessage fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.delSimMessage7+ + +delSimMessage(slotId: number, msgIndex: number, callback: AsyncCallback): void + +Deletes a SIM message. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS,ohos.permission.SEND_MESSAGES + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ----------------------------------------- | +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| msgIndex | number | Yes | Message index. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +let slotId = 0; +let msgIndex = 1; +sms.delSimMessage(slotId, msgIndex, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.delSimMessage7+ + +delSimMessage(slotId: number, msgIndex: number): Promise + +Deletes a SIM message. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS,ohos.permission.SEND_MESSAGES + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ----------------------------------------- | +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| msgIndex | number | Yes | Message index. | + +**Return value** + +| Type | Description | +| ------------------- | ----------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let slotId = 0; +let msgIndex = 1; +let promise = sms.delSimMessage(slotId, msgIndex); +promise.then(data => { + console.log(`delSimMessage success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`delSimMessage fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.updateSimMessage7+ + +updateSimMessage(options: UpdateSimMessageOptions, callback: AsyncCallback): void + +Updates a SIM message. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS,ohos.permission.SEND_MESSAGES + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------------------- | ---- | ------------------- | +| options | [UpdateSimMessageOptions](#updatesimmessageoptions7) | Yes | SIM message updating options.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +let updateSimMessageOptions = { + slotId = 0, + msgIndex = 1, + newStatus = 0, + pdu = "xxxxxxx", + smsc = "test" +}; +sms.updateSimMessage(updateSimMessageOptions, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.updateSimMessage7+ + +updateSimMessage(options: UpdateSimMessageOptions): Promise + +Updates a SIM message. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS,ohos.permission.SEND_MESSAGES + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------------------------------------------- | ---- | ------------------- | +| options | [UpdateSimMessageOptions](#updatesimmessageoptions7) | Yes | SIM message updating options.| + +**Return value** + +| Type | Description | +| ------------------- | ----------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let updateSimMessageOptions = { + slotId = 0, + msgIndex = 1, + newStatus = 0, + pdu = "xxxxxxx", + smsc = "test" +}; +let promise = sms.updateSimMessage(updateSimMessageOptions); +promise.then(data => { + console.log(`updateSimMessage success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`updateSimMessage fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.getAllSimMessages7+ + +getAllSimMessages(slotId: number, callback: AsyncCallback>): void + +Obtains all SIM card messages. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------------------- | ---- | ----------------------------------------- | +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| callback | AsyncCallback> | Yes | Callback used to return the result. | + +**Example** + +```js +let slotId = 0; +sms.getAllSimMessages(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.getAllSimMessages7+ + +getAllSimMessages(slotId: number): Promise> + +Obtains all SIM card messages. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ----------------------------------------- | +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2| + +**Return value** + +| Type | Description | +| ------------------------------------------------------- | ---------------------------------- | +| PromiseArray<[SimShortMessage](#simshortmessage8)\>> | Promise used to return the result.| + +**Example** + +```js +let slotId = 0; +let promise = sms.getAllSimMessages(slotId); +promise.then(data => { + console.log(`getAllSimMessages success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getAllSimMessages fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.setCBConfig7+ + +setCBConfig(options: CBConfigOptions, callback: AsyncCallback): void + +Sets the cell broadcast configuration. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------ | ---- | ------------ | +| options | [CBConfigOptions](#cbconfigoptions8) | Yes | Cell broadcast configuration options.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +let cbConfigOptions = { + slotId = 0, + smsc = "test", + pdu = "xxxxxxxx", + status = 0 +}; +sms.setCBConfig(cbConfigOptions, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.setCBConfig7+ + +setCBConfig(options: CBConfigOptions): Promise + +Sets the cell broadcast configuration. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.RECEIVE_SMS + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------------ | ---- | ------------ | +| options | [CBConfigOptions](#cbconfigoptions8) | Yes | Cell broadcast configuration options.| + +**Return value** + +| Type | Description | +| ------------------- | ----------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +let cbConfigOptions = { + slotId = 0, + smsc = "test", + pdu = "xxxxxxxx", + status = 0 +}; +let promise = sms.setCBConfig(cbConfigOptions); +promise.then(data => + console.log(`setCBConfig success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`setCBConfig fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.getSmsSegmentsInfo8+ + +getSmsSegmentsInfo(slotId: number, message: string, force7bit: boolean, callback: AsyncCallback): void + +Obtains SMS message segment information. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| message | string | Yes | SMS message. | +| force7bit | boolean | Yes | Whether to use 7-bit coding. | +| callback | AsyncCallback<[SmsSegmentsInfo](# { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.getSmsSegmentsInfo8+ + +getSmsSegmentsInfo(slotId: number, message: string, force7bit: boolean): Promise + +Obtains SMS message segment information. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------- | ---- | ----------------------------------------- | +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| message | string | Yes | Message | +| force7bit | boolean | Yes | Whether to use 7-bit coding. | + +**Return value** + +| Type | Description | +| ------------------------------------------------------- | ----------------------------- | +| Promise<[SmsSegmentsInfo](# + console.log(`getSmsSegmentsInfo success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getSmsSegmentsInfo fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.isImsSmsSupported8+ + +isImsSmsSupported(callback: AsyncCallback): void + +Checks whether SMS is supported on IMS. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ---------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.| + +**Example** + +```js +sms.isImsSmsSupported((err, data) => { + console.log(`callback: err->${JSON.(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.isImsSmsSupported8+ + +isImsSmsSupported(): Promise + +Checks whether SMS is supported on IMS. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Return value** + +| Type | Description | +| ---------------------- | ----------------------- | +| Promise<boolean> | Promise used to return the result.| + +**Example** + +```js +let promise = sms.isImsSmsSupported(); +promise.then(data => { + console.log(`isImsSmsSupported success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`isImsSmsSupported fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.getImsShortMessageFormat8+ + +getImsShortMessageFormat(callback: AsyncCallback): void + +Obtains the SMS format supported by the IMS. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------- | ---- | ---------- | +| callback | AsyncCallback<string> | Yes | Callback used to return the result.| + +**Example** + +```js +sms.getImsShortMessageFormat((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.getImsShortMessageFormat8+ + +getImsShortMessageFormat(): Promise + +Obtains the SMS format supported by the IMS. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Return value** + +| Type | Description | +| --------------------- | -------------------------- | +| Promise<string> | Promise used to return the result. | + +**Example** + +```js +let promise = sms.getImsShortMessageFormat(); +promise.then(data => { + console.log(`getImsShortMessageFormat success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getImsShortMessageFormat fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.decodeMms8+ + +decodeMms(mmsFilePathName: string | Array, callback: AsyncCallback): void + +Decodes MMS messages. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | ------------------------------------------------------- | ---- | -------------- | +| mmsFilePathName | string \|Array | Yes | MMS message file path.| +| callback | AsyncCallback<[MmsInformation](#mmsinformation8)> | Yes | Callback used to return the result. | + +**Example** + +```js +let mmsFilePathName = "filename"; +sms.decodeMms(mmsFilePathName, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.decodeMms8+ + +decodeMms(mmsFilePathName: string | Array): Promise + +Decodes MMS messages. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | ----------------------- | ---- | -------------- | +| mmsFilePathName | string \|Array | Yes | MMS message file path.| + +**Return value** + +| Type | Description | +| --------------------------------------------------------- | --------------------------- | +| Promise<<[MmsInformation](#mmsinformation8)>> | Promise used to return the result.| + +**Example** + +```js +let mmsFilePathName = "filename"; +let promise = sms.getSmscAddr(mmsFilePathName); +promise.then(data => { + console.log(`decodeMms success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`decodeMms fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## sms.encodeMms8+ + +encodeMms(mms: MmsInformation, callback: AsyncCallback>): void + +Encodes MMS messages. This API uses an asynchronous callback to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------- | ---- | ---------- | +| mms | [MmsInformation](#mmsinformation8) | Yes | MMS message information.| +| callback | AsyncCallback<Array> | Yes | Callback used to return the result.| + +**Example** + +```js +let mmsAcknowledgeInd = { + transactionId = "100", + version = 0x10, + reportAllowed = 128 +}; +let mmsInformation = { + messageType = 133, + mmsType = mmsAcknowledgeInd +}; +sms.encodeMms(mmsInformation, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## sms.encodeMms8+ + +encodeMms(mms: MmsInformation): Promise> + +Encodes MMS messages. This API uses a promise to return the result. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------- | ---- | ---------- | +| mms | [MmsInformation](#mmsinformation8) | Yes | MMS message information.| + +**Return value** + +| Type | Description | +| ----------------------------- | ----------------------------------- | +| Promise<Array> | Promise used to return the result.| + +**Example** + +```js +let mmsAcknowledgeInd = { + transactionId = "100", + version = 0x10, + reportAllowed = 128 +}; +let mmsInformation = { + messageType = 133, + mmsType = mmsAcknowledgeInd +}; +let promise = sms.encodeMms(mmsInformation); +promise.then(data => { + console.log(`encodeMms success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`encodeMms fail, promise: err->${JSON.stringify(err)}`); +}); +``` + ## ShortMessage Defines an SMS message instance. @@ -383,7 +1116,7 @@ Defines an SMS message instance. | Name | Type | Description | | ------------------------ | --------------------------------------- | ------------------------------------------------------------ | -| hasReplyPath | boolean | Whether the received SMS contains **TP-Reply-Path**. The default value is **false**.
TP-Reply-Path: The device returns a response based on the SMSC that sends the SMS message.| +| hasReplyPath | boolean | Whether the received SMS contains **TP-Reply-Path**. The default value is **false**.
**TP-Reply-Path**: The device returns a response based on the SMSC that sends the SMS message.| | isReplaceMessage | boolean | Whether the received SMS message is a **replace short message**. The default value is **false**.
For details, see section 9.2.3.9 in **3GPP TS 23.040**.| | isSmsStatusReportMessage | boolean | Whether the received SMS message is an SMS delivery status report. The default value is **false**.
**SMS-Status-Report**: a message sent from the SMSC to the mobile station to show the SMS message delivery status.| | messageClass | [ShortMessageClass](#shortmessageclass) | Enumerates SMS message types. | @@ -464,3 +1197,422 @@ Enumerates SMS message sending results. | SEND_SMS_FAILURE_UNKNOWN | 1 | Failed to send the SMS message due to an unknown reason. | | SEND_SMS_FAILURE_RADIO_OFF | 2 | Failed to send the SMS message because the modem is shut down. | | SEND_SMS_FAILURE_SERVICE_UNAVAILABLE | 3 | Failed to send the SMS message because the network is unavailable or SMS message sending or receiving is not supported.| + + +## MmsInformation8+ + +Defines the MMS message information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| ----------- | ------------------------------------------------------------ | ---- | --------- | +| messageType | [MessageType](#messagetype8) | Yes | Message type. | +| mmsType | [MmsSendReq](#mmssendreq8) \|[MmsSendConf](#mmssendconf8) \|[MmsNotificationInd](#mmsnotificationind8) \|[MmsRespInd](#mmsrespind8) \|[MmsRetrieveConf](#mmsretrieveconf8)\|[MmsAcknowledgeInd](#mmsacknowledgeind8)\|[MmsDeliveryInd](#mmsdeliveryind8)\|[MmsReadOrigInd](#mmsreadorigind8)\|[MmsReadRecInd](#mmsreadrecind8)| Yes | PDU header type.| +| attachment | Array<[MmsAttachment](#mmsattachment8)\> | No | Attachment. | + +## MmsSendReq8+ + +Defines an MMS message sending request. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| ---------------- | ------------------------------------ | ---- | ------------ | +| from | [MmsAddress](#mmsaddress8) | Yes | MMS message source. | +| transactionId | string | Yes | Transaction ID. | +| contentType | string | Yes | Content type. | +| version | [MmsVersionType](#mmsversiontype8) | Yes | Version. | +| to | Array<[MmsAddress](#mmsaddress8)\> | No | Address to which the message is sent. | +| date | number | No | Date. | +| cc | Array<[MmsAddress](#mmsaddress8)\> | No | Carbon copy. | +| bcc | Array<[MmsAddress](#mmsaddress8)\> | No | Blind carbon copy. | +| subject | string | No | Subject. | +| messageClass | number | No | Message class. | +| expiry | number | No | Expiration. | +| priority | [MmsPriorityType](#mmsprioritytype8) | No | Priority. | +| senderVisibility | number | No | Sender visibility.| +| deliveryReport | number | No | Delivery report. | +| readReport | number | No | Read report. | + +## MmsSendConf8+ + +Defines the MMS message sending configuration. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| ------------- | ---------------------------------- | ---- | -------- | +| responseState | number | Yes | Response status.| +| transactionId | string | Yes | Transaction ID. | +| version | [MmsVersionType](#mmsversiontype8) | Yes | Version. | +| messageId | string | No | Message ID. | + +## MmsNotificationInd8+ + +Defines an MMS notification index. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| --------------- | ---------------------------------- | ---- | -------- | +| transactionId | string | Yes | Transaction ID. | +| messageClass | number | Yes | Message class. | +| messageSize | number | Yes | Message size.| +| expiry | number | Yes | Expiration. | +| contentLocation | string | Yes | Content location.| +| version | [MmsVersionType](#mmsversiontype8) | Yes | Version. | +| from | [MmsAddress](#mmsaddress8) | No | Source. | +| subject | string | No | Subject. | +| deliveryReport | number | No | Status report.| +| contentClass | number | No | Content class. | + +## MmsAcknowledgeInd8+ + +Defines an MMS confirmation index. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| ------------- | ---------------------------------- | ---- | -------- | +| transactionId | string | Yes | Transaction ID. | +| version | [MmsVersionType](#mmsversiontype8) | Yes | Version. | +| reportAllowed | [ReportType](#reporttype8) | No | Report allowed.| + +## MmsRetrieveConf8+ + +Defines the MMS message retrieval configuration. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| -------------- | ------------------------------------ | ---- | -------- | +| transactionId | string | Yes | Transaction ID. | +| messageId | string | Yes | Message ID. | +| date | number | Yes | Date. | +| contentType | string | Yes | Content type.| +| to | Array<[MmsAddress](#mmsaddress8)\> | Yes | Address to which the message is sent. | +| version | [MmsVersionType](#mmsversiontype8) | Yes | Version | +| from | [MmsAddress](#mmsaddress8) | No | Source. | +| cc | Array<[MmsAddress](#mmsaddress8)\> | No | Carbon copy. | +| subject | string | No | Subject. | +| priority | [MmsPriorityType](#mmsprioritytype8) | No | Priority. | +| deliveryReport | number | No | Status report.| +| readReport | number | No | Read report.| +| retrieveStatus | number | No | Retrieval status.| +| retrieveText | string | No | Retrieval text.| + +## MmsReadOrigInd8+ + +Defines the original MMS message reading index. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| ---------- | ---------------------------------- | ---- | -------- | +| version | [MmsVersionType](#mmsversiontype8) | Yes | Version. | +| messageId | string | Yes | Message ID. | +| to | Array<[MmsAddress](#mmsaddress8)\> | Yes | Address to which the message is sent. | +| from | [MmsAddress](#mmsaddress8) | Yes | Source. | +| date | number | Yes | Date. | +| readStatus | number | Yes | Read status.| + +## MmsAttachment8+ + +Defines the attachment of an MMS message. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| ----------------------- | ------------------------------------ | ---- | ------------------ | +| contentId | string | Yes | Content ID. | +| contentLocation | string | Yes | Content location. | +| contentDisposition | [DispositionType](#dispositiontype8) | Yes | Content disposition. | +| contentTransferEncoding | string | Yes | Encoding for content transfer. | +| contentType | string | Yes | Content type. | +| isSmil | boolean | Yes | Whether the synchronized multimedia integration language is used.| +| path | string | No | Path. | +| inBuff | Array | No | In the buffer | +| fileName | string | No | File name. | +| charset | [MmsCharSets](#mmscharsets8) | No | Character set. | + +## MmsAddress8+ + +Defines an MMSC address. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| ------- | ---------------------------- | ---- | ------ | +| address | string | Yes | MMSC address. | +| charset | [MmsCharSets](#mmscharsets8) | Yes | Character set.| + +## MessageType8+ + +Enumerates message types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Value | Description | +| ------------------------- | ---- | -------------------- | +| TYPE_MMS_SEND_REQ | 128 | MMS message sending request. | +| TYPE_MMS_SEND_CONF | 129 | MMS message sending configuration. | +| TYPE_MMS_NOTIFICATION_IND | 130 | MMS notification index. | +| TYPE_MMS_RESP_IND | 131 | MMS message response index. | +| TYPE_MMS_RETRIEVE_CONF | 132 | MMS message retrieval configuration. | +| TYPE_MMS_ACKNOWLEDGE_IND | 133 | MMS message acknowledgement index. | +| TYPE_MMS_DELIVERY_IND | 134 | MMS message delivery index. | +| TYPE_MMS_READ_REC_IND | 135 | MMS message reading and receiving index.| +| TYPE_MMS_READ_ORIG_IND | 136 | Original MMS message reading index.| + +## MmsPriorityType8+ + +Enumerates MMS message priorities. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Value | Description | +| ---------- | ---- | -------------- | +| MMS_LOW | 128 | Low priority. | +| MMS_NORMAL | 129 | Normal priority.| +| MMS_HIGH | 130 | High priority. | + +## MmsVersionType8+ + +Enumerates MMS versions. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Value | Description | +| --------------- | ---- | ----------- | +| MMS_VERSION_1_0 | 0x10 | MMS version 1_0.| +| MMS_VERSION_1_1 | 0x11 | MMS version 1_1.| +| MMS_VERSION_1_2 | 0x12 | MMS version 1_2.| +| MMS_VERSION_1_3 | 0x13 | MMS version 1_3.| + +## MmsCharSets8+ + +Enumerates MMS character sets. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Value | Description | +| --------------- | ------ | ------------------- | +| BIG5 | 0X07EA | BIG5 format. | +| ISO_10646_UCS_2 | 0X03E8 | ISO_10646_UCS_2 format.| +| ISO_8859_1 | 0X04 | ISO_8859_1 format. | +| ISO_8859_2 | 0X05 | ISO_8859_2 format. | +| ISO_8859_3 | 0X06 | ISO_8859_3 format. | +| ISO_8859_4 | 0X07 | ISO_8859_4 format. | +| ISO_8859_5 | 0X08 | ISO_8859_5 format. | +| ISO_8859_6 | 0X09 | ISO_8859_6 format. | +| ISO_8859_7 | 0X0A | ISO_8859_7 format. | +| ISO_8859_8 | 0X0B | ISO_8859_8 format. | +| ISO_8859_9 | 0X0C | ISO_8859_9 format. | +| SHIFT_JIS | 0X11 | SHIFT_JIS format. | +| US_ASCII | 0X03 | US_ASCII format. | +| UTF_8 | 0X6A | UTF_8 format. | + +## DispositionType8+ + +Enumerates disposition types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Value | Description | +| ---------- | ---- | -------- | +| FROM_DATA | 0 | Data source.| +| ATTACHMENT | 1 | Attachment. | +| INLINE | 2 | Inlining. | + +## ReportType8+ + +Enumerates report types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Value | Description| +| ------- | ---- | ---- | +| MMS_YES | 128 | YES | +| MMS_NO | 129 | NO | + +## CBConfigOptions8+ + +Defines the cell broadcast configuration options. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| -------------- | -------------------- | ---- | ------------ | +| slotId | number | Yes | Card slot ID. | +| enable | boolean | Yes | Whether to enable cell broadcast. | +| startMessageId | number | Yes | Start message ID. | +| endMessageId | number | Yes | End message ID. | +| ranType | [RanType](#rantype7) | Yes | RAN type.| + +## SimMessageStatus7+ + +Defines the SIM message status. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Value | Description | +| ------------------------- | ---- | --------------------------- | +| SIM_MESSAGE_STATUS_FREE | 0 | Free state. | +| SIM_MESSAGE_STATUS_READ | 1 | Read state. | +| SIM_MESSAGE_STATUS_UNREAD | 3 | Unread state. | +| SIM_MESSAGE_STATUS_SENT | 5 | Storage of sent messages (applicable only to SMS).| +| SIM_MESSAGE_STATUS_UNSENT | 7 | Storage of unsent messages (applicable only to SMS).| + +## RanType7+ + +Enumerates RAN types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Value | Description| +| --------- | ---- | ---- | +| TYPE_GSM | 1 | GSM | +| TYPE_CDMA | 2 | CMDA | + +## SmsEncodingScheme8+ + +Enumerates SMS encoding schemes. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Value | Description | +| -------------------- | ---- | ------------ | +| SMS_ENCODING_UNKNOWN | 0 | Unknown code.| +| SMS_ENCODING_7BIT | 1 | 7-digit code. | +| SMS_ENCODING_8BIT | 2 | 8-digit code. | +| SMS_ENCODING_16BIT | 3 | 16-digit code.| + +## SimMessageOptions7+ + +Defines the SIM message options. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name| Type | Mandatory| Description | +| ------ | -------------------------------------- | ---- | -------------- | +| slotId | number | Yes | Card slot ID. | +| smsc | string | Yes | Short message service center.| +| pdu | string | Yes | Protocol data unit. | +| status | [SimMessageStatus](#simmessagestatus7) | Yes | Message status. | + +## UpdateSimMessageOptions7+ + +Defines the updating SIM message options. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| --------- | -------------------------------------- | ---- | -------------- | +| slotId | number | Yes | Card slot ID. | +| msgIndex | number | Yes | Message index. | +| newStatus | [SimMessageStatus](#simmessagestatus7) | Yes | New status. | +| pdu | string | Yes | Protocol data unit. | +| smsc | string | Yes | Short message service center.| + +## SimShortMessage8+ + +Defines a SIM message. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| ---------------- | -------------------------------------- | ---- | ------------- | +| shortMessage | [ShortMessage](#shortmessage) | Yes | SMS message. | +| simMessageStatus | [SimMessageStatus](#simmessagestatus7) | Yes | SIM message status.| +| indexOnSim | number | Yes | SIM card index. | + +## MmsDeliveryInd8+ + +Defines an MMS message delivery index. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| --------- | ---------------------------------- | ---- | ------ | +| messageId | string | Yes | Message ID.| +| date | number | Yes | Date. | +| to | Array<[MmsAddress](#mmsaddress8)\> | Yes | Address to which the message is sent.| +| status | number | Yes | Status. | +| version | [MmsVersionType](#mmsversiontype8) | Yes | Version. | + +## MmsRespInd8+ + +Defines an MMS response index. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| ------------- | ---------------------------------- | ---- | -------- | +| transactionId | string | Yes | Event ID. | +| status | number | Yes | Status. | +| version | [MmsVersionType](#mmsversiontype8) | Yes | Version. | +| reportAllowed | [ReportType](#reporttype8) | No | Report allowed.| + +## SmsSegmentsInfo8+ + +Defines the SMS message segment information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.SmsMms + +| Name | Type | Mandatory| Description | +| -------------------- | ---------------------------------------- | ---- | ------------ | +| splitCount | number | Yes | Split count. | +| encodeCount | number | Yes | Encoding count. | +| encodeCountRemaining | number | Yes | Remaining encoding count.| +| scheme | [SmsEncodingScheme](#smsencodingscheme8) | Yes | Encoding scheme.| diff --git a/en/application-dev/reference/apis/js-apis-system-mediaquery.md b/en/application-dev/reference/apis/js-apis-system-mediaquery.md index f2057a86685a5d212e84caf27e69468b8169c267..841cebeb1da0380128d3704650a0aaf9ef095d5f 100644 --- a/en/application-dev/reference/apis/js-apis-system-mediaquery.md +++ b/en/application-dev/reference/apis/js-apis-system-mediaquery.md @@ -1,7 +1,9 @@ # Media Query +The **mediaquery** module provides different styles for different media types. -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** + +> **NOTE** > > - The APIs of this module are no longer maintained since API version 7. You are advised to use [`@ohos.mediaquery`](js-apis-mediaquery.md) instead. > - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -38,11 +40,7 @@ Creates a **MediaQueryList** object based on the query condition. **Example** ``` -export default { - matchMedia() { - var mMediaQueryList = mediaquery.matchMedia('(max-width: 466)'); - }, -} +var mMediaQueryList = mediaquery.matchMedia('(max-width: 466)'); ``` ## MediaQueryEvent @@ -95,11 +93,16 @@ Adds a listener for this **MediaQueryList** object. The listener must be added b | Name | Type | Mandatory | Description | | -------- | -------------------------------- | ---- | -------------- | -| callback | (event: MediaQueryEvent) => void | Yes | Callback invoked when the matching condition changes.| +| callback | (event: MediaQueryEvent) => void | Yes | Callback invoked when the query condition changes.| **Example** ``` +function maxWidthMatch(e){ + if(e.matches){ + // do something + } +} mMediaQueryList.addListener(maxWidthMatch); ``` @@ -116,10 +119,15 @@ Removes the listener for this **MediaQueryList** object. | Name | Type | Mandatory | Description | | -------- | --------------------------------- | ---- | -------------- | -| callback | (event: MediaQueryEvent) => void) | Yes | Callback invoked when the matching condition changes.| +| callback | (event: MediaQueryEvent) => void) | Yes | Callback invoked when the query condition changes.| **Example** ``` +function maxWidthMatch(e){ + if(e.matches){ + // do something + } +} mMediaQueryList.removeListener(maxWidthMatch); ``` diff --git a/en/application-dev/reference/apis/js-apis-tagSession.md b/en/application-dev/reference/apis/js-apis-tagSession.md new file mode 100644 index 0000000000000000000000000000000000000000..5ed3760a0cf3664cc6991a73489dd7f53ab9d83b --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-tagSession.md @@ -0,0 +1,127 @@ +# Standard NFC Tag Session + +The **tagSession** module provides common APIs for establishing connections and transferring data. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## **Modules to Import** + +```js +import tag from '@ohos.nfc.tag'; +``` + +## tagSession + +Provides common APIs for establishing connections and transferring data. **tagSession** is the base class of all [NFC tag technologies](js-apis-nfctech.md). + +A child class instance is required to access the following interfaces. You can use **get**XX**Tag()** to obtain a child class instance. + +The specific method varies with the NFC tag technology in use. For details, see [nfcTag](js-apis-nfcTag.md). + +### tagSession.connectTag + +connectTag(): boolean; + +Connects to this tag. + +Call this method to set up a connection before reading data from or writing data to a tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let isNfcConnected = tag.getXXXTag(taginfo).connectTag(); +console.log("isNfcConnected:" +isNfcConnected); +``` + +### tagSession.reset() + +reset(): void + +Resets the connection to this tag and restores the default timeout duration for writing data to the tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let reset = tag.getXXXTag(taginfo).reset(); +console.log("reset:" +reset); +``` + +### tagSession.isTagConnected + +isTagConnected(): boolean + +Checks whether the tag is connected. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| boolean | Returns **true** if the tag is connected; returns **false** otherwise.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an Object given by nfc service when tag is dispatched. +let isTagConnected = tag.getXXXTag(taginfo).isTagConnected(); +console.log("isTagConnected:" +isTagConnected); +``` + +### tagSession.getMaxSendLength + +getMaxSendLength(): number + +Obtains the maximum length of the data that can be sent to the tag. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Core + +**Return value** + +| **Type**| **Description** | +| ------------------ | --------------------------| +| number | Maximum data length obtained.| + +**Example** + +```js +import tag from '@ohos.nfc.tag'; + +// tagInfo is an object given by the NFC service when a tag is dispatched. +let mazSendLen = tag.getXXXTag(taginfo).getMaxSendLength(); +console.log("mazSendLen:" +mazSendLen); +``` diff --git a/en/application-dev/reference/apis/js-apis-telephony-data.md b/en/application-dev/reference/apis/js-apis-telephony-data.md index 4a711c1f7cbf0defdbcd9ea0c28a08e981c594a9..7d8018a4e82916df0c218a10ca7d5e8fdb9e6364 100644 --- a/en/application-dev/reference/apis/js-apis-telephony-data.md +++ b/en/application-dev/reference/apis/js-apis-telephony-data.md @@ -79,7 +79,7 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | --------------------- | ---- | ------------------------------------------------------------ | -| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: Clears the default configuration.| +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: clearing the default configuration| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** @@ -106,7 +106,7 @@ This is a system API. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: Clears the default configuration.| +| slotId | number | Yes | SIM card slot ID.
- **0**: card slot 1
- **1**: card slot 2
- **-1**: clearing the default configuration| **Return value** @@ -274,7 +274,7 @@ promise.then((data) => { isCellularDataRoamingEnabled(slotId: number, callback: AsyncCallback\): void -Checks whether roaming is enabled for the cellular data service. This API uses an asynchronous callback to return the result. +Checks whether the cellular data roaming service is enabled. This API uses an asynchronous callback to return the result. **Required permission**: ohos.permission.GET_NETWORK_INFO @@ -285,7 +285,7 @@ Checks whether roaming is enabled for the cellular data service. This API uses a | Name | Type | Mandatory| Description | | -------- | ------------------------ | ---- | ------------------------------------------------------------ | | slotId | number | Yes | Card slot ID.
**0**: card slot 1
**1**: card slot 2 | -| callback | AsyncCallback\ | Yes | Callback used to return the result.
- **true**: Roaming is enabled for the cellular data service.
- **false**: Roaming is disabled for the cellular data service.| +| callback | AsyncCallback\ | Yes | Callback used to return the result.
- **true**: The cellular data roaming service is enabled.
- **false**: The cellular data roaming service is disabled. | **Example** @@ -299,7 +299,7 @@ data.isCellularDataRoamingEnabled(0,(err, data) => { isCellularDataRoamingEnabled(slotId: number): Promise\ -Checks whether roaming is enabled for the cellular data service. This API uses a promise to return the result. +Checks whether the cellular data roaming service is enabled. This API uses a promise to return the result. **Required permission**: ohos.permission.GET_NETWORK_INFO @@ -315,7 +315,7 @@ Checks whether roaming is enabled for the cellular data service. This API uses a | Type | Description | | ------------------ | ------------------------------------------------------------ | -| Promise\ | Promise used to return the result.
- **true**: Roaming is enabled for the cellular data service.
- **false**: Roaming is disabled for the cellular data service.| +| Promise\ | Promise used to return the result.
- **true**: The cellular data roaming service is enabled.
- **false**: The cellular data roaming service is disabled.| **Example** @@ -328,6 +328,241 @@ promise.then((data) => { }); ``` +## data.enableCellularData + +enableCellularData(callback: AsyncCallback): void + +Enables the cellular data service. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CellularData + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ---------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js +data.enableCellularData((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## data.enableCellularData + +enableCellularData(): Promise + +Enables the cellular data service. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CellularData + +**Return value** + +| Type | Description | +| --------------- | ----------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let promise = data.enableCellularData(); +promise.then((data) => { + console.log(`enableCellularData success, promise: data->${JSON.stringify(data)}`); +}).catch((err) => { + console.error(`enableCellularData fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## data.disableCellularData + +disableCellularData(callback: AsyncCallback): void + +Disables the cellular data service. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CellularData + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ---------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js +data.disableCellularData((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## data.disableCellularData + +disableCellularData(): Promise + +Disables the cellular data service. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CellularData + +**Return value** + +| Type | Description | +| --------------- | --------------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let promise = data.disableCellularData(); +promise.then((data) => { + console.log(`disableCellularData success, promise: data->${JSON.stringify(data)}`); +}).catch((err) => { + console.error(`disableCellularData fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## data.enableCellularDataRoaming + +enableCellularDataRoaming(slotId: number, callback: AsyncCallback): void + +Enables the cellular data roaming service. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CellularData + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ---------------------------------------- | +| slotId | number | Yes | Card slot ID.
**0**: card slot 1
**1**: card slot 2| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```js +data.enableCellularDataRoaming(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## data.enableCellularDataRoaming + +enableCellularDataRoaming(slotId: number): Promise + +Enables the cellular data roaming service. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CellularData + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------------------------- | +| slotId | number | Yes | Card slot ID.
**0**: card slot 1
**1**: card slot 2| + +**Return value** + +| Type | Description | +| --------------- | ------------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let promise = data.enableCellularDataRoaming(0); +promise.then((data) => { + console.log(`enableCellularDataRoaming success, promise: data->${JSON.stringify(data)}`); +}).catch((err) => { + console.error(`enableCellularDataRoaming fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## data.disableCellularDataRoaming + +disableCellularDataRoaming(slotId: number, callback: AsyncCallback): void + +Disables the cellular data roaming service. This API uses an asynchronous callback to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CellularData + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ---------------------------------------- | +| slotId | number | Yes | Card slot ID.
**0**: card slot 1
**1**: card slot 2| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```js +data.disableCellularDataRoaming(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## data.disableCellularDataRoaming + +disableCellularDataRoaming(slotId: number): Promise + +Disables the cellular data roaming service. This API uses a promise to return the result. + +This is a system API. + +**Required permission**: ohos.permission.SET_TELEPHONY_STATE + +**System capability**: SystemCapability.Telephony.CellularData + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------------------------- | +| slotId | number | Yes | Card slot ID.
**0**: card slot 1
**1**: card slot 2| + +**Return value** + +| Type | Description | +| --------------- | ------------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +let promise = data.disableCellularDataRoaming(0); +promise.then((data) => { + console.log(`disableCellularDataRoaming success, promise: data->${JSON.stringify(data)}`); +}).catch((err) => { + console.error(`disableCellularDataRoaming fail, promise: err->${JSON.stringify(err)}`); +}); +``` + + ## DataFlowType Defines the cellular data flow type. diff --git a/en/application-dev/reference/apis/js-apis-usb.md b/en/application-dev/reference/apis/js-apis-usb.md index 71b0490ea8c610dc0169222042ec7770c19d0a83..82932c99be0a0c8c39ab989d656cb6b0fcde99f5 100644 --- a/en/application-dev/reference/apis/js-apis-usb.md +++ b/en/application-dev/reference/apis/js-apis-usb.md @@ -26,6 +26,7 @@ Obtains the USB device list. | Array<Readonly<[USBDevice](#usbdevice)>> | Device information list. | - **Example** + ```js let devicesList = usb.getDevices(); console.log(`devicesList = ${JSON.stringify(devicesList)}`); @@ -93,16 +94,19 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | device | [USBDevice](#usbdevice) | Yes| USB device information. | - **Return value** + | Type| Description| | -------- | -------- | | Readonly<[USBDevicePipe](#usbdevicepipe)> | USB device pipe for data transfer. | - **Example** + ```js let devicepipe= usb.connectDevice(device); console.log(`devicepipe = ${JSON.stringify(devicepipe)}`); @@ -118,16 +122,19 @@ Checks whether the application has the permission to access the device. **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | deviceName | string | Yes| Device name. | - **Return value** + | Type| Description| | -------- | -------- | | boolean | Returns **true** if the application has the permission to access the device; returns **false** otherwise. | - **Example** + ```js let devicesName="1-1"; let bool = usb.hasRight(devicesName); @@ -144,16 +151,19 @@ Requests the temporary permission for the application to access the USB device. **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | deviceName | string | Yes| Device name. | - **Return value** + | Type| Description| | -------- | -------- | | Promise<boolean> | Returns **true** if the temporary device access permissions are granted; returns **false** otherwise. | - **Example** + ```js let devicesName="1-1"; usb.requestRight(devicesName).then((ret) => { @@ -172,6 +182,7 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | @@ -179,11 +190,13 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi | force | boolean | No| Whether to forcibly claim the USB interface. The default value is **false**, indicating not to forcibly claim the USB interface. | - **Return value** + | Type| Description| | -------- | -------- | | number | Returns **0** if the USB interface is successfully claimed; returns an error code otherwise. | - **Example** + ```js let ret = usb.claimInterface(devicepipe, interfaces); console.log(`claimInterface = ${ret}`); @@ -201,17 +214,20 @@ Before you do this, ensure that you have claimed the interface by calling [usb.c **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | | iface | [USBInterface](#usbinterface) | Yes| USB interface, which is used to determine the index of the interface to release. | - **Return value** + | Type| Description| | -------- | -------- | | number | Returns **0** if the USB interface is successfully released; returns an error code otherwise. | - **Example** + ```js let ret = usb.releaseInterface(devicepipe, interfaces); console.log(`releaseInterface = ${ret}`); @@ -229,17 +245,20 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | | config | [USBConfig](#usbconfig) | Yes| USB configuration to set. | - **Return value** + | Type| Description| | -------- | -------- | | number | Returns **0** if the USB configuration is successfully set; returns an error code otherwise. | - **Example** + ```js let ret = usb.setConfiguration(devicepipe, config); console.log(`setConfiguration = ${ret}`); @@ -256,17 +275,20 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | | iface | [USBInterface](#usbinterface) | Yes| USB interface to set. | - **Return value** + | Type| Description| | -------- | -------- | | number | Returns **0** if the USB interface is successfully set; returns an error code otherwise. | - **Example** + ```js let ret = usb.setInterface(devicepipe, interfaces); console.log(`setInterface = ${ret}`); @@ -284,16 +306,19 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | - **Return value** + | Type| Description| | -------- | -------- | | Uint8Array | Raw descriptor data. The value **undefined** indicates that the operation has failed. | - **Example** + ```js let ret = usb.getRawDescriptor(devicepipe); ``` @@ -310,16 +335,19 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| Device pipe, which is used to determine the bus number and device address. | - **Return value** + | Type| Description| | -------- | -------- | | number | File descriptor of the USB device. The value **-1** indicates that the operation has failed. | - **Example** + ```js let ret = usb.getFileDescriptor(devicepipe); ``` @@ -336,6 +364,7 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device. | @@ -343,11 +372,13 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi | timeout | number | No| Timeout duration. The default value is **0**, indicating no timeout. | - **Return value** + | Type| Description| | -------- | -------- | | Promise<number> | Returns the size of the transmitted or received data block if the control transfer is successful; returns **-1** if an exception occurs. | - **Example** + ```js usb.controlTransfer(devicepipe, USBControlParams).then((ret) => { console.log(`controlTransfer = ${JSON.stringify(ret)}`); @@ -366,6 +397,7 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe, which is used to determine the USB device. | @@ -374,11 +406,13 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi | timeout | number | No| Timeout duration. The default value is **0**, indicating no timeout. | - **Return value** + | Type| Description| | -------- | -------- | | Promise<number> | Returns the size of the transmitted or received data block if the control transfer is successful; returns **-1** if an exception occurs. | - **Example** + ```js // Call usb.getDevices to obtain a data set. Then, obtain a USB device and its access permission. // Pass the obtained USB device as a parameter to usb.connectDevice. Then, call usb.connectDevice to connect the USB device. @@ -400,16 +434,19 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **System capability**: SystemCapability.USB.USBManager - **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | pipe | [USBDevicePipe](#usbdevicepipe) | Yes| USB device pipe. | - **Return value** + | Type| Description| | -------- | -------- | | number | Returns **0** if the USB device pipe is closed successfully; returns an error code otherwise. | - **Example** + ```js let ret = usb.closePipe(devicepipe); console.log(`closePipe = ${ret}`); @@ -556,3 +593,68 @@ Enumerates request directions. | -------- | -------- | -------- | | USB_REQUEST_DIR_TO_DEVICE | 0 | Request for writing data from the host to the device. | | USB_REQUEST_DIR_FROM_DEVICE | 0x80 | Request for reading data from the device to the host. | + +## FunctionType9+ + +Enumerates function types for the USB device. + +This is a system API. + +**System capability**: SystemCapability.USB.USBManager + +| Name | Value | Description | +| ------------ | ---- | ---------- | +| NONE | 0 | No function.| +| ACM | 1 | ACM function. | +| ECM | 2 | ECM function. | +| HDC | 4 | HDC function. | +| MTP | 8 | Not supported currently.| +| PTP | 16 | Not supported currently.| +| RNDIS | 32 | Not supported currently.| +| MIDI | 64 | Not supported currently.| +| AUDIO_SOURCE | 128 | Not supported currently.| +| NCM | 256 | Not supported currently.| + +## PortModeType9+ + +Enumerates USB port mode types. + +This is a system API. + +**System capability**: SystemCapability.USB.USBManager + +| Name | Value | Description | +| --------- | ---- | ---------------------------------------------------- | +| NONE | 0 | None. | +| UFP | 1 | Upstream facing port, which functions as the sink of power supply. | +| DFP | 2 | Downstream facing port, which functions as the source of power supply. | +| DRP | 3 | Dynamic reconfiguration port (DRP), which can function as the DFP (host) or UFP (device). It is not supported currently.| +| NUM_MODES | 4 | Not supported currently. | + +## PowerRoleType9+ + +Enumerates power role types. + +This is a system API. + +**System capability**: SystemCapability.USB.USBManager + +| Name | Value | Description | +| ------ | ---- | ---------- | +| NONE | 0 | None. | +| SOURCE | 1 | External power supply.| +| SINK | 2 | Internal power supply.| + +## DataRoleType9+ + +Enumerates data role types. + +This is a system API. + +**System capability**: SystemCapability.USB.USBManager + +| Name | Value | Description | +| ------ | ---- | ------------ | +| NONE | 0 | None. | +| HOST | 1 | USB host.| +| DEVICE | 2 | USB device.| diff --git a/en/application-dev/reference/apis/js-apis-wifi.md b/en/application-dev/reference/apis/js-apis-wifi.md index 602a3b7e2a318119b1e8dbfa80a59fdc65a6bede..f49a5fb22443b5c66641581fccb6b4a4f3133232 100644 --- a/en/application-dev/reference/apis/js-apis-wifi.md +++ b/en/application-dev/reference/apis/js-apis-wifi.md @@ -1,4 +1,5 @@ # WLAN +The WLAN module provides basic wireless local area network (WLAN) functions, peer-to-peer (P2P) functions, and WLAN message notification services. It allows applications to communicate with other devices over WLAN. > **NOTE**
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -10,20 +11,54 @@ import wifi from '@ohos.wifi'; ``` +## wifi.enableWifi + +enableWifi(): boolean + +Enables WLAN. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.disableWifi + +disableWifi(): boolean + +Disables WLAN. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + ## wifi.isWifiActive isWifiActive(): boolean -Checks whether the WLAN is activated. +Checks whether WLAN is enabled. **Required permissions**: ohos.permission.GET_WIFI_INFO **System capability**: SystemCapability.Communication.WiFi.STA **Return value** -| **Type**| **Description**| -| -------- | -------- | -| boolean | Returns **true** if the WLAN is activated; returns **false** otherwise.| + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if WLAN is enabled; returns **false** otherwise.| ## wifi.scan @@ -32,14 +67,14 @@ scan(): boolean Starts a scan for WLAN. -**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.LOCATION +**Required permissions**: **ohos.permission.SET_WIFI_INFO** and **ohos.permission.LOCATION** **System capability**: SystemCapability.Communication.WiFi.STA **Return value** -| **Type**| **Description**| -| -------- | -------- | -| boolean | Returns **true** if the scan is successful; returns **false** otherwise.| + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| ## wifi.getScanInfos @@ -48,14 +83,14 @@ getScanInfos(): Promise<Array<WifiScanInfo>> Obtains the scan result. This API uses a promise to return the result. -**Required permissions**: at least one of ohos.permission.GET_WIFI_INFO, ohos.permission.GET_WIFI_PEERS_MAC, and ohos.permission.LOCATION +**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.GET_WIFI_PEERS_MAC (or ohos.permission.LOCATION) **System capability**: SystemCapability.Communication.WiFi.STA **Return value** -| **Type**| **Description**| -| -------- | -------- | -| Promise< Array<[WifiScanInfo](#wifiscaninfo)> > | Promise used to return the hotspots detected.| + | **Type**| **Description**| + | -------- | -------- | + | Promise< Array<[WifiScanInfo](#wifiscaninfo)> > | Promise used to return the detected hotspots.| ## wifi.getScanInfos @@ -64,14 +99,14 @@ getScanInfos(callback: AsyncCallback<Array<WifiScanInfo>>): void Obtains the scan result. This API uses an asynchronous callback to return the result. -**Required permissions**: at least one of ohos.permission.GET_WIFI_INFO, ohos.permission.GET_WIFI_PEERS_MAC, and ohos.permission.LOCATION +**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.GET_WIFI_PEERS_MAC (or ohos.permission.LOCATION) **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback< Array<[WifiScanInfo](#wifiscaninfo)>> | Yes| Callback invoked to return the hotspots detected.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback< Array<[WifiScanInfo](#wifiscaninfo)>> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the detected hotspots. Otherwise, **err** is a non-zero value and **data** is empty.| **Example** ```js @@ -120,18 +155,21 @@ Obtains the scan result. This API uses an asynchronous callback to return the re Represents WLAN hotspot information. +**System capability**: SystemCapability.Communication.WiFi.STA + | **Name**| **Type**| **Readable/Writable**| **Description**| | -------- | -------- | -------- | -------- | | ssid | string | Read only| Hotspot service set identifier (SSID), in UTF-8 format.| | bssid | string | Read only| Basic service set identifier (BSSID) of the hotspot.| | capabilities | string | Read only| Hotspot capabilities.| -| securityType | [WifiSecurityType](#WifiSecurityType) | Read only| WLAN security type.| +| securityType | [WifiSecurityType](#wifisecuritytype) | Read only| WLAN security type.| | rssi | number | Read only| Received signal strength indicator (RSSI) of the hotspot, in dBm.| | band | number | Read only| Frequency band of the WLAN access point (AP).| | frequency | number | Read only| Frequency of the WLAN AP.| -| channelWidth | number | Read only| Bandwidth of the WLAN AP.| -| centerFrequency0 | number | Read only| Center frequency.| -| centerFrequency1 | number | Read only| Center frequency.| +| channelWidth | number | Read only| Channel width of the WLAN AP.| +| centerFrequency09+ | number | Read only| Center frequency.| +| centerFrequency19+ | number | Read only| Center frequency.| +| infoElems9+ | Array<[WifiInfoElem](#wifiinfoelem9)> | Read only| Information elements.| | timestamp | number | Read only| Timestamp.| @@ -139,103 +177,467 @@ Represents WLAN hotspot information. Enumerates the WLAN security types. +**System capability**: SystemCapability.Communication.WiFi.Core + | **Name**| **Default Value**| **Description**| | -------- | -------- | -------- | -| WIFI_SEC_TYPE_INVALID | 0 | Invalid security type| -| WIFI_SEC_TYPE_OPEN | 1 | Open security type| -| WIFI_SEC_TYPE_WEP | 2 | Wired Equivalent Privacy (WEP)| -| WIFI_SEC_TYPE_PSK | 3 | Pre-shared key (PSK)| -| WIFI_SEC_TYPE_SAE | 4 | Simultaneous Authentication of Equals (SAE)| +| WIFI_SEC_TYPE_INVALID | 0 | Invalid security type.| +| WIFI_SEC_TYPE_OPEN | 1 | Open security type.| +| WIFI_SEC_TYPE_WEP | 2 | Wired Equivalent Privacy (WEP).| +| WIFI_SEC_TYPE_PSK | 3 | Pre-shared key (PSK).| +| WIFI_SEC_TYPE_SAE | 4 | Simultaneous Authentication of Equals (SAE).| +| WIFI_SEC_TYPE_EAP9+ | 5 | Extensible Authentication protocol (EAP).| +| WIFI_SEC_TYPE_EAP_SUITE_B9+ | 6 | Suite B 192-bit encryption.| +| WIFI_SEC_TYPE_OWE9+ | 7 | Opportunistic Wireless Encryption (OWE).| +| WIFI_SEC_TYPE_WAPI_CERT9+ | 8 | WLAN Authentication and Privacy Infrastructure (WAPI) in certificate-based mode (WAPI-CERT).| +| WIFI_SEC_TYPE_WAPI_PSK9+ | 9 | WAPI-PSK.| -## wifi.addUntrustedConfig7+ +## WifiInfoElem9+ -addUntrustedConfig(config: WifiDeviceConfig): Promise<boolean> +Represents a WLAN information element. -Adds untrusted WLAN configuration. This API uses a promise to return the result. +**System capability**: SystemCapability.Communication.WiFi.STA -**Required permissions**: - ohos.permission.SET_WIFI_INFO +| **Name**| **Type**| **Readable/Writable**| **Description**| +| -------- | -------- | -------- | -------- | +| eid | number | Read only| ID of the information element.| +| content | Uint8Array | Read only| Content of the information element.| -**System capability**: - SystemCapability.Communication.WiFi.STA + +## WifiChannelWidth9+ + +Enumerates the Wi-Fi channel widths. + +**System capability**: SystemCapability.Communication.WiFi.STA + +| **Name**| **Default Value**| **Description**| +| -------- | -------- | -------- | +| WIDTH_20MHZ | 0 | 20 MHz.| +| WIDTH_40MHZ | 1 | 40 MHz.| +| WIDTH_80MHZ | 2 | 80 MHz.| +| WIDTH_160MHZ | 3 | 160 MHz.| +| WIDTH_80MHZ_PLUS | 4 | 80 MHz+.| +| WIDTH_INVALID | 5 | Invalid value.| + + +## wifi.getScanInfosSync9+ + +getScanInfosSync():  Array<[WifiScanInfo](#wifiscaninfo)> + +Obtains the scan result. This API returns the result synchronously. + +**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.GET_WIFI_PEERS_MAC (or ohos.permission.LOCATION) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + |  Array<[WifiScanInfo](#wifiscaninfo)> | Scan result obtained.| + + +## wifi.addDeviceConfig + +addDeviceConfig(config: WifiDeviceConfig): Promise<number> + +Adds network configuration. This API uses a promise to return the result. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.SET_WIFI_CONFIG + +**System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| config | [WifiDeviceConfig](#WifiDeviceConfig) | Yes| WLAN configuration to add.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to add.| **Return value** -| **Type**| **Description**| -| -------- | -------- | -| Promise<boolean> | Promise used to return the operation result. The value **true** indicates that the operation is successful; **false** indicates the opposite.| + | **Type**| **Description**| + | -------- | -------- | + | Promise<number> | Promise used to return the WLAN configuration ID. If **-1** is returned, the operation has failed.| ## WifiDeviceConfig Represents the WLAN configuration. +**System capability**: SystemCapability.Communication.WiFi.STA + | **Name**| **Type**| **Readable/Writable**| **Description**| | -------- | -------- | -------- | -------- | -| ssid | string | Read only| Hotspot service set identifier (SSID), in UTF-8 format.| +| ssid | string | Read only| SSID of the hotspot, in UTF-8 format.| | bssid | string | Read only| BSSID of the hotspot.| -| preSharedKey | string | Read only| Private key of the hotspot.| +| preSharedKey | string | Read only| PSK of the hotspot.| | isHiddenSsid | boolean | Read only| Whether to hide the network.| -| securityType | [WifiSecurityType](#WifiSecurityType) | Read only| Security type.| +| securityType | [WifiSecurityType](#wifisecuritytype) | Read only| Security type.| +| creatorUid | number | Read only| User ID, which is available only to system applications.| +| disableReason | number | Read only| Reason for disabling WLAN. This parameter is available only to system applications.| +| netId | number | Read only| Allocated network ID, which is available only to system applications.| +| randomMacType | number | Read only| Random MAC type, which is available only to system applications.| +| randomMacAddr | string | Read only| Random MAC address, which is available only for system applications.| +| ipType | [IpType](#iptype7) | Read only| IP address type, which is available only to system applications.| +| staticIp | [IpConfig](#ipconfig7) | Read only| Static IP address configuration, which is available only to system applications.| +| eapConfig9+ | [WifiEapConfig](#wifieapconfig9) | Read only| EAP configuration, which is available only to system applications.| + + +## IpType7+ + +Enumerate the IP address types. + +**System capability**: SystemCapability.Communication.WiFi.STA + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| STATIC | 0 | Static IP address.| +| DHCP | 1 | IP address allocated by DHCP.| +| UNKNOWN | 2 | Not specified.| + + +## IpConfig7+ + +Represents IP configuration information. + +**System capability**: SystemCapability.Communication.WiFi.STA + +| **Name**| **Type**| **Readable/Writable**| **Description**| +| -------- | -------- | -------- | -------- | +| ipAddress | number | Read only| IP address.| +| gateway | number | Read only| Gateway.| +| dnsServers | number[] | Read only| Domain name server (DNS) information.| +| domains | Array<string> | Read only| Domain information.| + + +## WifiEapConfig9+ + +Represents EAP configuration information. + +**System capability**: SystemCapability.Communication.WiFi.STA + +| **Name**| **Type**| **Readable/Writable**| **Description**| +| -------- | -------- | -------- | -------- | +| eapMethod | [EapMethod](#eapmethod9) | Read only| EAP authentication method.| +| phase2Method | [Phase2Method](#phase2method9) | Read only| Phase 2 authentication method.| +| identity | string | Read only| Identity Information.| +| anonymousIdentity | string | Read only| Anonymous identity.| +| password | string | Read only| Password.| +| caCertAliases | string | Read only| CA certificate alias.| +| caPath | string | Read only| CA certificate path.| +| clientCertAliases | string | Read only| Client certificate alias.| +| altSubjectMatch | string | Read only| A string to match the alternate subject.| +| domainSuffixMatch | string | Read only| A string to match the domain suffix.| +| realm | string | Read only| Realm for the passpoint credential.| +| plmn | string | Read only| Public land mobile network (PLMN) of the passpoint credential provider.| +| eapSubId | number | Read only| Sub-ID of the SIM card.| + + +## EapMethod9+ + +Enumerates the EAP authentication methods. + +**System capability**: SystemCapability.Communication.WiFi.STA + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| EAP_NONE | 0 | Not specified.| +| EAP_PEAP | 1 | PEAP.| +| EAP_TLS | 2 | TLS.| +| EAP_TTLS | 3 | TTLS.| +| EAP_PWD | 4 | Password.| +| EAP_SIM | 5 | SIM.| +| EAP_AKA | 6 | AKA.| +| EAP_AKA_PRIME | 7 | AKA Prime.| +| EAP_UNAUTH_TLS | 8 | UNAUTH TLS.| + + +## Phase2Method9+ + +Enumerates the Phase 2 authentication methods. + +**System capability**: SystemCapability.Communication.WiFi.STA + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| PHASE2_NONE | 0 | Not specified.| +| PHASE2_PAP | 1 | PAP.| +| PHASE2_MSCHAP | 2 | MS-CHAP.| +| PHASE2_MSCHAPV2 | 3 | MS-CHAPv2.| +| PHASE2_GTC | 4 | GTC .| +| PHASE2_SIM | 5 | SIM.| +| PHASE2_AKA | 6 | AKA.| +| PHASE2_AKA_PRIME | 7 | AKA Prime.| + + +## wifi.addDeviceConfig + +addDeviceConfig(config: WifiDeviceConfig, callback: AsyncCallback<number>): void + +Adds network configuration. This API uses an asynchronous callback to return the result. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.SET_WIFI_CONFIG + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to add.| + | callback | AsyncCallback<number> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the network configuration ID. If **data** is **-1**, the operation has failed. If **err** is not **0**, an error has occurred.| + + +## wifi.addUntrustedConfig7+ + +addUntrustedConfig(config: WifiDeviceConfig): Promise<boolean> + +Adds the configuration of an untrusted network. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.SET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to add.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | Promise<boolean> | Promise used to return the result. If the operation is successful, **true** is returned; otherwise, **false** is returned.| ## wifi.addUntrustedConfig7+ addUntrustedConfig(config: WifiDeviceConfig, callback: AsyncCallback<boolean>): void -Adds untrusted WLAN configuration. This API uses an asynchronous callback to return the result. +Adds the configuration of an untrusted network. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.SET_WIFI_INFO **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| config | [WifiDeviceConfig](#WifiDeviceConfig) | Yes| WLAN configuration to add.| -| callback | AsyncCallback<boolean> | Yes| Callback used to return the operation result. The value **true** indicates that the operation is successful; **false** indicates the opposite.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to add.| + | callback | AsyncCallback<boolean> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is **true**. If the operation fails, **data** is **false**. If **err** is not **0**, an error has occurred.| ## wifi.removeUntrustedConfig7+ removeUntrustedConfig(config: WifiDeviceConfig): Promise<boolean> -Removes untrusted WLAN configuration. This API uses a promise to return the result. +Removes the configuration of an untrusted network. This API uses a promise to return the result. **Required permissions**: ohos.permission.SET_WIFI_INFO **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| config | [WifiDeviceConfig](#WifiDeviceConfig) | Yes| WLAN configuration to remove. | + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to remove.| **Return value** -| **Type**| **Description**| -| -------- | -------- | -| Promise<boolean> | Promise used to return the operation result. The value **true** indicates that the operation is successful; **false** indicates the opposite.| + | **Type**| **Description**| + | -------- | -------- | + | Promise<boolean> | Promise used to return the result. If the operation is successful, **true** is returned; otherwise, **false** is returned.| ## wifi.removeUntrustedConfig7+ removeUntrustedConfig(config: WifiDeviceConfig, callback: AsyncCallback<boolean>): void -Removes untrusted WLAN configuration. This API uses an asynchronous callback to return the result. +Removes the configuration of an untrusted network. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.SET_WIFI_INFO **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| config | [WifiDeviceConfig](#WifiDeviceConfig) | Yes| WLAN configuration to remove. | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the operation result. The value **true** indicates that the operation is successful; **false** indicates the opposite.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to remove.| + | callback | AsyncCallback<boolean> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is **true**. If the operation fails, **data** is **false**. If **err** is not **0**, an error has occurred.| + + +## wifi.addCandidateConfig9+ + +addCandidateConfig(config: WifiDeviceConfig): Promise<number> + +Adds the configuration of a candidate network. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.SET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to add.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | Promise<number> | Promise used to return the network configuration ID.| + + +## wifi.addCandidateConfig9+ + +addCandidateConfig(config: WifiDeviceConfig, callback: AsyncCallback<number>): void + +Adds the configuration of a candidate network. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.SET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to add.| + | callback | AsyncCallback<number> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the network configuration ID. If **data** is **-1**, the operation has failed. If **err** is not **0**, an error has occurred.| + + +## wifi.removeCandidateConfig9+ + +removeCandidateConfig(config: WifiDeviceConfig): Promise<boolean> + +Removes the configuration of a candidate network. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.SET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to remove.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | Promise<void> | Promise used to return the result. If the operation is successful, **true** is returned; otherwise, **false** is returned.| + + +## wifi.removeCandidateConfig9+ + +removeCandidateConfig(config: WifiDeviceConfig, callback: AsyncCallback<boolean>): void + +Removes the configuration of a candidate network. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.SET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration to remove.| + | callback | AsyncCallback<void> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is **true**. If the operation fails, **data** is **false**. If **err** is not **0**, an error has occurred.| + + +## wifi.getCandidateConfigs9+ + +getCandidateConfigs():  Array<[WifiDeviceConfig](#wifideviceconfig)> + +Obtains candidate network configuration. + +**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + |  Array<[WifiDeviceConfig](#wifideviceconfig)> | Candidate network configuration obtained.| + + +## wifi.connectToCandidateConfig9+ + +connectToCandidateConfig(networkId: number): boolean + +Connects to a candidate network. + +**Required permissions**: ohos.permission.SET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | networkId | number | Yes| ID of the candidate network configuration.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.connectToNetwork + +connectToNetwork(networkId: number): boolean + +Connects to the specified network. +This is a system API. + +**Required permissions**: ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | networkId | number | Yes| Network configuration ID.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.connectToDevice + +connectToDevice(config: WifiDeviceConfig): boolean + +Connects to the specified network. +This is a system API. + +**Required permissions**: + ohos.permission.SET_WIFI_INFO, ohos.permission.SET_WIFI_CONFIG, and ohos.permissio.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: + SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| WLAN configuration.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.disconnect + +disconnect(): boolean + +Connects to the specified network. +This is a system API. + +**Required permissions**: + ohos.permission.SET_WIFI_INFO and ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: + SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| ## wifi.getSignalLevel @@ -249,15 +651,15 @@ Obtains the WLAN signal level. **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| rssi | number | Yes| RSSI of the hotspot, in dBm. | -| band | number | Yes| Frequency band of the WLAN AP.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | rssi | number | Yes| RSSI of the hotspot, in dBm.| + | band | number | Yes| Frequency band of the WLAN AP.| **Return value** -| **Type**| **Description**| -| -------- | -------- | -| number | Signal level obtained. The value range is [0, 4].| + | **Type**| **Description**| + | -------- | -------- | + | number | Signal level obtained. The value range is [0, 4].| ## wifi.getLinkedInfo @@ -271,9 +673,9 @@ Obtains WLAN connection information. This API uses a promise to return the resul **System capability**: SystemCapability.Communication.WiFi.STA **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[WifiLinkedInfo](#WifiLinkedInfo)> | Promise used to return the WLAN connection information obtained.| + | Type| Description| + | -------- | -------- | + | Promise<[WifiLinkedInfo](#wifilinkedinfo)> | Promise used to return the WLAN connection information obtained.| ## wifi.getLinkedInfo @@ -287,9 +689,9 @@ Obtains WLAN connection information. This API uses an asynchronous callback to r **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[WifiLinkedInfo](#WifiLinkedInfo)> | Yes| Callback invoked to return the WLAN connection information obtained.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[WifiLinkedInfo](#wifilinkedinfo)> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the WLAN connection information obtained. If **err** is not **0**, an error has occurred.| **Example** ```js @@ -315,25 +717,34 @@ Obtains WLAN connection information. This API uses an asynchronous callback to r Represents the WLAN connection information. +**System capability**: SystemCapability.Communication.WiFi.STA + | Name| Type| Readable/Writable| Description| | -------- | -------- | -------- | -------- | -| ssid | string | Read only| Hotspot SSID, in UTF-8 format.| +| ssid | string | Read only| SSID, in UTF-8 format.| | bssid | string | Read only| BSSID of the hotspot.| -| rssi | number | Read only| RSSI of the hotspot, in dBm. | +| networkId | number | Read only| Network configuration ID, which is available only to system applications.| +| rssi | number | Read only| RSSI of the hotspot, in dBm.| | band | number | Read only| Frequency band of the WLAN AP.| | linkSpeed | number | Read only| Speed of the WLAN AP.| | frequency | number | Read only| Frequency of the WLAN AP.| | isHidden | boolean | Read only| Whether to hide the WLAN AP.| | isRestricted | boolean | Read only| Whether to restrict data volume at the WLAN AP.| +| chload | number | Read only| Channel load. A larger value indicates a higher load. This parameter is only available to system applications.| +| snr | number | Read only| Signal-to-noise ratio (SNR), which is available only to system applications.| +| macType9+ | number | Read only| MAC address type.| | macAddress | string | Read only| MAC address of the device.| | ipAddress | number | Read only| IP address of the device that sets up the WLAN connection.| -| connState | [ConnState](#ConnState) | Read only| WLAN connection state.| +| suppState | [SuppState](#suppstate) | Read only| Supplicant state, which is available only to system applications.| +| connState | [ConnState](#connstate) | Read only| WLAN connection state.| ## ConnState Enumerates the WLAN connection states. +**System capability**: SystemCapability.Communication.WiFi.STA + | Name| Default Value| Description| | -------- | -------- | -------- | | SCANNING | 0 | The device is scanning for available APs.| @@ -346,6 +757,28 @@ Enumerates the WLAN connection states. | UNKNOWN | 7 | Failed to set up a WLAN connection.| +## SuppState + +Enumerates the supplicant states. + +**System capability**: SystemCapability.Communication.WiFi.STA + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| DISCONNECTED | 0 | The supplicant is disconnected from the AP.| +| INTERFACE_DISABLED | 1 | The network interface is disabled.| +| INACTIVE | 2 | The supplicant is inactive.| +| SCANNING | 3 | The supplicant is scanning for a WLAN connection.| +| AUTHENTICATING | 4 | The supplicant is being authenticated.| +| ASSOCIATING | 5 | The supplicant is being associated with an AP.| +| ASSOCIATED | 6 | The supplicant is associated with an AP.| +| FOUR_WAY_HANDSHAKE | 7 | A four-way handshake is being performed for the supplicant.| +| GROUP_HANDSHAKE | 8 | A group handshake is being performed for the supplicant.| +| COMPLETED | 9 | The authentication is complete.| +| UNINITIALIZED | 10 | The supplicant failed to set up a connection.| +| INVALID | 11 | Invalid value.| + + ## wifi.isConnected7+ isConnected(): boolean @@ -357,9 +790,41 @@ Checks whether the WLAN is connected. **System capability**: SystemCapability.Communication.WiFi.STA **Return value** -| **Type**| **Description**| + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the WLAN is connected; returns **false** otherwise.| + + +## wifi.getSupportedFeatures7+ + +getSupportedFeatures(): number + +Obtains the features supported by this device. +This is a system API. + +**Required permissions**: ohos.permission.GET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.Core + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | number | Feature value.| + +**Feature IDs** + +| Value| Description| | -------- | -------- | -| boolean | Returns **true** if the WLAN is connected; returns **false** otherwise.| +| 0x0001 | WLAN infrastructure mode| +| 0x0002 | 5 GHz feature| +| 0x0004 | Generic Advertisement Service (GAS)/Access Network Query Protocol (ANQP) feature| +| 0x0008 | Wi-Fi Direct| +| 0x0010 | SoftAP| +| 0x0040 | Wi-Fi AWare| +| 0x8000 | WLAN AP/STA concurrency| +| 0x8000000 | WPA3 Personal (WPA-3 SAE)| +| 0x10000000 | WPA3-Enterprise Suite B | +| 0x20000000 | Enhanced open feature| ## wifi.isFeatureSupported7+ @@ -368,135 +833,430 @@ isFeatureSupported(featureId: number): boolean Checks whether the device supports the specified WLAN feature. -**Required permissions**: ohos.permission.GET_WIFI_INFO +**Required permissions**: ohos.permission.GET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.Core + +**Parameters** + + | **Name**| **Type**| Mandatory| **Description**| + | -------- | -------- | -------- | -------- | + | featureId | number | Yes| Feature ID.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the feature is supported; returns **false** otherwise.| + + +## wifi.getDeviceMacAddress7+ + +getDeviceMacAddress(): string[] + +Obtains the device MAC address. +This is a system API. + +**Required permissions**: ohos.permission.GET_WIFI_LOCAL_MAC and ohos.permission.GET_WIFI_INFO (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | string[] | MAC address obtained.| + + +## wifi.getIpInfo7+ + +getIpInfo(): IpInfo + +Obtains IP information. + +**Required permissions**: ohos.permission.GET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | [IpInfo](#ipinfo7) | IP information obtained.| + + +## IpInfo7+ + +Represents IP information. + +**System capability**: SystemCapability.Communication.WiFi.STA + +| **Name**| **Type**| **Readable/Writable**| **Description**| +| -------- | -------- | -------- | -------- | +| ipAddress | number | Read only| IP address.| +| gateway | number | Read only| Gateway.| +| netmask | number | Read only| Subnet mask.| +| primaryDns | number | Read only| IP address of the preferred DNS server.| +| secondDns | number | Read only| IP address of the alternate DNS server.| +| serverIp | number | Read only| IP address of the DHCP server.| +| leaseDuration | number | Read only| Lease duration of the IP address.| + + +## wifi.getCountryCode7+ + +getCountryCode(): string + +Obtains the country code. + +**Required permissions**: ohos.permission.GET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.Core + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | string | Country code obtained.| + + +## wifi.reassociate7+ + +reassociate(): boolean + +Re-associates with the network. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.reconnect7+ + +reconnect(): boolean + +Reconnects to the network. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.getDeviceConfigs7+ + +getDeviceConfigs():  Array<[WifiDeviceConfig](#wifideviceconfig)> + +Obtains network configuration. +This is a system API. + +**Required permissions**: ohos.permission.GET_WIFI_INFO, ohos.permission.LOCATION, and ohos.permission.GET_WIFI_CONFIG + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + |  Array<[WifiDeviceConfig](#wifideviceconfig)> | Array of network configuration obtained.| + + +## wifi.updateNetwork7+ + +updateNetwork(config: WifiDeviceConfig): boolean + +Updates network configuration. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.SET_WIFI_CONFIG + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiDeviceConfig](#wifideviceconfig) | Yes| New WLAN configuration.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.disableNetwork7+ + +disableNetwork(netId: number): boolean + +Disables network configuration. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | netId | number | Yes| ID of the network configuration to disable.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.removeAllNetwork7+ + +removeAllNetwork(): boolean + +Removes the configuration of all networks. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.removeDevice7+ + +removeDevice(id: number): boolean + +Removes the configuration of a network. +This is a system API. + +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.STA + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | id | number | Yes| ID of the network configuration to remove.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.enableHotspot7+ + +enableHotspot(): boolean + +Enables this hotspot. +This is a system API. + +**Required permissions**: ohos.permission.MANAGE_WIFI_HOTSPOT (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.AP.Core + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.disableHotspot7+ + +disableHotspot(): boolean + +Disables this hotspot. +This is a system API. + +**Required permissions**: ohos.permission.MANAGE_WIFI_HOTSPOT (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.AP.Core + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.isHotspotDualBandSupported7+ + +isHotspotDualBandSupported(): boolean + +Checks whether the hotspot supports dual band. +This is a system API. + +**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.MANAGE_WIFI_HOTSPOT (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.AP.Core + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the feature is supported; returns **false** otherwise.| + + +## wifi.isHotspotActive7+ + +isHotspotActive(): boolean -**System capability**: SystemCapability.Communication.WiFi.Core +Checks whether this hotspot is active. +This is a system API. -**Parameters** +**Required permissions**: ohos.permission.GET_WIFI_INFO -| **Name**| **Type**| Mandatory| **Description**| -| -------- | -------- | -------- | -------- | -| featureId | number | Yes| Feature ID.| +**System capability**: SystemCapability.Communication.WiFi.AP.Core **Return value** -| **Type**| **Description**| -| -------- | -------- | -| boolean | Returns **true** if the feature is supported; returns **false** otherwise.| - -**Feature IDs** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the hotspot is active; returns **false** otherwise.| -| Value| Description| -| -------- | -------- | -| 0x0001 | WLAN infrastructure mode| -| 0x0002 | 5 GHz bandwidth| -| 0x0004 | Generic Advertisement Service (GAS)/Access Network Query Protocol (ANQP) feature| -| 0x0008 | Wi-Fi Direct| -| 0x0010 | SoftAP| -| 0x0040 | Wi-Fi AWare| -| 0x8000 | WLAN AP/STA concurrency| -| 0x8000000 | WPA3 Personal (WPA-3 SAE)| -| 0x10000000 | WPA3-Enterprise Suite-B | -| 0x20000000 | Enhanced open feature| +## wifi.setHotspotConfig7+ -## wifi.getIpInfo7+ +setHotspotConfig(config: HotspotConfig): boolean -getIpInfo(): IpInfo +Sets hotspot configuration. +This is a system API. -Obtains IP information. +**Required permissions**: ohos.permission.SET_WIFI_INFO and ohos.permission.GET_WIFI_CONFIG -**Required permissions**: ohos.permission.GET_WIFI_INFO +**System capability**: SystemCapability.Communication.WiFi.AP.Core -**System capability**: SystemCapability.Communication.WiFi.STA +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | config | [HotspotConfig](#hotspotconfig7) | Yes| Hotspot configuration to set.| **Return value** -| **Type**| **Description**| -| -------- | -------- | -| [IpInfo](#IpInfo) | IP information obtained.| + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -## IpInfo7+ +## HotspotConfig7+ -Represents IP information. +Represents the hotspot configuration. + +**System capability**: SystemCapability.Communication.WiFi.AP.Core | **Name**| **Type**| **Readable/Writable**| **Description**| | -------- | -------- | -------- | -------- | -| ipAddress | number | Read only| IP address| -| gateway | number | Read only| Gateway| -| netmask | number | Read only| Subnet mask| -| primaryDns | number | Read only| IP address of the preferred DNS server| -| secondDns | number | Read only| IP address of the alternate DNS server| -| serverIp | number | Read only| IP address of the DHCP server| -| leaseDuration | number | Read only| Lease duration of the IP address| +| ssid | string | Read only| SSID, in UTF-8 format.| +| securityType | [WifiSecurityType](#wifisecuritytype) | Read only| Security type.| +| band | number | Read only| Hotspot band. The value **1** stands for 2.4 GHz, the value **2** for 5 GHz, and the value **3** for dual band.| +| preSharedKey | string | Read only| SPK of the hotspot.| +| maxConn | number | Read only| Maximum number of connections allowed.| -## wifi.getCountryCode7+ +## wifi.getHotspotConfig7+ -getCountryCode(): string +getHotspotConfig(): HotspotConfig -Obtains the country code. +obtains hotspot configuration. +This is a system API. -**Required permissions**: ohos.permission.GET_WIFI_INFO +**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.GET_WIFI_CONFIG -**System capability**: SystemCapability.Communication.WiFi.Core +**System capability**: SystemCapability.Communication.WiFi.AP.Core **Return value** -| **Type**| **Description**| -| -------- | -------- | -| string | Country code obtained.| + | **Type**| **Description**| + | -------- | -------- | + | [HotspotConfig](#hotspotconfig7) | Hotspot configuration obtained.| -## wifi.getP2pLinkedInfo8+ +## wifi.getStations7+ -getP2pLinkedInfo(): Promise<WifiP2pLinkedInfo> +getStations():  Array<[StationInfo](#stationinfo7)> -Obtains peer-to-peer (P2P) connection information. This API uses a promise to return the result. +Obtains information about the connected stations. +This is a system API. -**Required permissions**: ohos.permission.GET_WIFI_INFO +**Required permissions**: ohos.permission.GET_WIFI_INFO, ohos.permission.LOCATION, and ohos.permission.MANAGE_WIFI_HOTSPOT (available only to system applications) -**System capability**: SystemCapability.Communication.WiFi.P2P +**System capability**: SystemCapability.Communication.WiFi.AP.Core **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[WifiP2pLinkedInfo](#WifiP2pLinkedInfo)> | Promise used to return the P2P connection information obtained.| + | **Type**| **Description**| + | -------- | -------- | + |  Array<[StationInfo](#stationinfo7)> | Connected stations obtained.| + + +## StationInfo7+ + +Represents the station information. + +**System capability**: SystemCapability.Communication.WiFi.AP.Core + +| **Name**| **Type**| **Readable/Writable**| **Description**| +| -------- | -------- | -------- | -------- | +| name | string | Read only| Device name.| +| macAddress | string | Read only| MAC address.| +| ipAddress | string | Read only| IP address.| ## wifi.getP2pLinkedInfo8+ -getP2pLinkedInfo(callback: AsyncCallback<WifiP2pLinkedInfo>): void +getP2pLinkedInfo(): Promise<WifiP2pLinkedInfo> -Obtains P2P connection information. This API uses an asynchronous callback to return the result. +Obtains P2P link information. This API uses a promise to return the result. **Required permissions**: ohos.permission.GET_WIFI_INFO **System capability**: SystemCapability.Communication.WiFi.P2P -**Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[WifiP2pLinkedInfo](#WifiP2pLinkedInfo)> | Yes| Callback used to return the P2P connection information obtained.| +**Return value** + | Type| Description| + | -------- | -------- | + | Promise<[WifiP2pLinkedInfo](#wifip2plinkedinfo8)> | Promise used to return the P2P link information obtained.| + ## WifiP2pLinkedInfo8+ -Represents the WLAN connection information. +Represents the P2P link information. + +**System capability**: SystemCapability.Communication.WiFi.P2P | Name| Type| Readable/Writable| Description| | -------- | -------- | -------- | -------- | -| connectState | [P2pConnectState](#P2pConnectState) | Read only| P2P connection state.| -| isGroupOwner | boolean | Read only| Whether it is a group owner.| -| groupOwnerAddr | string | Read only| MAC address of the group owner.| +| connectState | [P2pConnectState](#p2pconnectstate8) | Read only| P2P connection state.| +| isGroupOwner | boolean | Read only| Whether the device is the group owner.| +| groupOwnerAddr | string | Read only| MAC address of the group. ## P2pConnectState8+ Enumerates the P2P connection states. +**System capability**: SystemCapability.Communication.WiFi.P2P + | Name| Default Value| Description| | -------- | -------- | -------- | -| DISCONNECTED | 0 | Disconnected| -| CONNECTED | 1 | Connected| +| DISCONNECTED | 0 | Disconnected.| +| CONNECTED | 1 | Connected.| + + +## wifi.getP2pLinkedInfo8+ + +getP2pLinkedInfo(callback: AsyncCallback<WifiP2pLinkedInfo>): void + +Obtains P2P link information. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.P2P + +**Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[WifiP2pLinkedInfo](#wifip2plinkedinfo8)> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the P2P link information. If **err** is not **0**, an error has occurred.| ## wifi.getCurrentGroup8+ @@ -510,162 +1270,124 @@ Obtains the current P2P group information. This API uses a promise to return the **System capability**: SystemCapability.Communication.WiFi.P2P **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[WifiP2pGroupInfo](#WifiP2pGroupInfo)> | Promise used to return the P2P group information obtained.| + | Type| Description| + | -------- | -------- | + | Promise<[WifiP2pGroupInfo](#wifip2pgroupinfo8)> | Promise used to return the group information obtained.| ## wifi.getCurrentGroup8+ getCurrentGroup(callback: AsyncCallback<WifiP2pGroupInfo>): void -Obtains the P2P group information. This API uses an asynchronous callback to return the result. +Obtains the current P2P group information. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[WifiP2pGroupInfo](#WifiP2pGroupInfo)> | Yes| Callback used to return the P2P group information obtained.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[WifiP2pGroupInfo](#wifip2pgroupinfo8)> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the group information obtained. If **err** is not **0**, an error has occurred.| -## wifi.getP2pGroups9+ -getP2pGroups(): Promise<Array<WifiP2pGroupInfo> +## wifi.getP2pPeerDevices8+ + +getP2pPeerDevices(): Promise<WifiP2pDevice[]> -Obtains information about all P2P groups. This API uses a promise to return the result. +Obtains the peer device list in a P2P connection. This API uses a promise to return the result. **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION **System capability**: SystemCapability.Communication.WiFi.P2P **Return value** -| Type| Description| -| -------- | -------- | -| Promise< Array<[WifiP2pGroupInfo](#WifiP2pGroupInfo)> > | Information about all created P2P groups obtained.| + | Type| Description| + | -------- | -------- | + | Promise<[WifiP2pDevice[]](#wifip2pdevice8)> | Promise used to return the peer device list.| -## wifi.getP2pGroups9+ -getP2pGroups(callback: AsyncCallback<Array<WifiP2pGroupInfo>): void +## wifi.getP2pPeerDevices8+ -Obtains information about all P2P groups. This API uses an asynchronous callback to return the result. +getP2pPeerDevices(callback: AsyncCallback<WifiP2pDevice[]>): void + +Obtains the peer device list in a P2P connection. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback< Array<[WifiP2pGroupInfo](#WifiP2pGroupInfo)>> | Yes| Callback invoked to return the P2P group information obtained.| - -## WifiP2pGroupInfo8+ + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[WifiP2pDevice[]](#wifip2pdevice8)> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the peer device list obtained. If **err** is not **0**, an error has occurred.| -Represents the P2P group information. - -| Name| Type| Readable/Writable| Description| -| -------- | -------- | -------- | -------- | -| isP2pGo | boolean | Read only| Whether it is a group.| -| ownerInfo | [WifiP2pDevice](#WifiP2pDevice) | Read only| Device information of the group.| -| passphrase | string | Read only| Private key of the group.| -| interface | string | Read only| Interface name.| -| groupName | string | Read only| Group name.| -| networkId | number | Read only| Network ID.| -| frequency | number | Read only| Frequency of the group.| -| clientDevices | [WifiP2pDevice[]](#WifiP2pDevice) | Read only| List of connected devices.| -| goIpAddress | string | Read only| IP address of the group.| ## WifiP2pDevice8+ Represents the P2P device information. +**System capability**: SystemCapability.Communication.WiFi.P2P + | Name| Type| Readable/Writable| Description| | -------- | -------- | -------- | -------- | | deviceName | string | Read only| Device name.| | deviceAddress | string | Read only| MAC address of the device.| | primaryDeviceType | string | Read only| Type of the primary device.| -| deviceStatus | [P2pDeviceStatus](#P2pDeviceStatus) | Read only| Device status.| +| deviceStatus | [P2pDeviceStatus](#p2pdevicestatus8) | Read only| Device status.| | groupCapabilitys | number | Read only| Group capabilities.| -## P2pDeviceStatus8+ - -Enumerates the device states. - -| Name| Default Value| Description| -| -------- | -------- | -------- | -| CONNECTED | 0 | Connected| -| INVITED | 1 | Invited| -| FAILED | 2 | Failed| -| AVAILABLE | 3 | Available| -| UNAVAILABLE | 4 | Unavailable| - - -## wifi.getP2pPeerDevices8+ - -getP2pPeerDevices(): Promise<WifiP2pDevice[]> -Obtains the list of peer devices in a P2P connection. This API uses a promise to return the result. +## P2pDeviceStatus8+ -**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION +Enumerates the P2P device states. **System capability**: SystemCapability.Communication.WiFi.P2P -**Return value** -| Type| Description| -| -------- | -------- | -| Promise<[WifiP2pDevice[]](#WifiP2pDevice)> | Promise used to return the peer device list obtained.| - - -## wifi.getP2pPeerDevices8+ - -getP2pPeerDevices(callback: AsyncCallback<WifiP2pDevice[]>): void - -Obtains the list of peer devices in a P2P connection. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION - -**System capability**: SystemCapability.Communication.WiFi.P2P +| Name| Default Value| Description| +| -------- | -------- | -------- | +| CONNECTED | 0 | Connected.| +| INVITED | 1 | Invited.| +| FAILED | 2 | Failed.| +| AVAILABLE | 3 | Available.| +| UNAVAILABLE | 4 | Unavailable.| -**Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[WifiP2pDevice[]](#WifiP2pDevice)> | Yes| Callback used to return the peer device list obtained.| ## wifi.getP2pLocalDevice9+ getP2pLocalDevice(): Promise<WifiP2pDevice> -Obtains local device information. This API uses a promise to return the result. +Obtains the local device information in a P2P connection. This API uses a promise to return the result. **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.GET_WIFI_CONFIG **System capability**: SystemCapability.Communication.WiFi.P2P **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[WifiP2pDevice](#WifiP2pDevice)> | Promise used to return the local device information obtained.| + | Type| Description| + | -------- | -------- | + | Promise<[WifiP2pDevice](#wifip2pdevice8)> | Promise used to return the local device information obtained.| -## wifi.getP2pLocalDevice8+ +## wifi.getP2pLocalDevice9+ getP2pLocalDevice(callback: AsyncCallback<WifiP2pDevice>): void -Obtains local device information. This API uses an asynchronous callback to return the result. +Obtains the local device information in a P2P connection. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.GET_WIFI_CONFIG **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[WifiP2pDevice](#WifiP2pDevice)> | Yes| Callback invoked to returnthe local device information obtained.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[WifiP2pDevice](#wifip2pdevice8)> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the local device information obtained. If **err** is not **0**, an error has occurred.| + ## wifi.createGroup8+ -createGroup(config: WifiP2PConfig): boolean; +createGroup(config: WifiP2PConfig): boolean Creates a P2P group. @@ -675,41 +1397,47 @@ Creates a P2P group. **Parameters** -| **Name**| **Type**| Mandatory| **Description**| -| -------- | -------- | -------- | -------- | -| config | [WifiP2PConfig](#WifiP2PConfig) | Yes| Group configuration.| + | **Name**| **Type**| Mandatory| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiP2PConfig](#wifip2pconfig8) | Yes| Group configuration.| **Return value** -| Type| Description| -| -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + ## WifiP2PConfig8+ Represents P2P configuration. +**System capability**: SystemCapability.Communication.WiFi.P2P + | Name| Type| Readable/Writable| Description| | -------- | -------- | -------- | -------- | | deviceAddress | string | Read only| Device address.| -| netId | number | Read only| Network ID. The value **-1** indicates that a temporary group, and **-2** indicates that a persistent group.| -| passphrase | string | Read only| Private key of the group.| +| netId | number | Read only| Network ID. The value **-1** indicates a temporary group, and **-2** indicates a persistent group.| +| passphrase | string | Read only| Passphrase of the group.| | groupName | string | Read only| Name of the group.| -| goBand | [GroupOwnerBand](#GroupOwnerBand) | Read only| Bandwidth of the group.| +| goBand | [GroupOwnerBand](#groupownerband8) | Read only| Frequency band of the group.| ## GroupOwnerBand8+ -Enumerates the P2P group bandwidths. +Enumerates the P2P group frequency bands. + +**System capability**: SystemCapability.Communication.WiFi.P2P | Name| Default Value| Description| | -------- | -------- | -------- | -| GO_BAND_AUTO | 0 | Auto| -| GO_BAND_2GHZ | 1 | 2 GHz| -| GO_BAND_5GHZ | 2 | 5 GHz| +| GO_BAND_AUTO | 0 | Auto.| +| GO_BAND_2GHZ | 1 | 2 GHz.| +| GO_BAND_5GHZ | 2 | 5 GHz.| + ## wifi.removeGroup8+ -removeGroup(): boolean; +removeGroup(): boolean Removes this P2P group. @@ -718,14 +1446,14 @@ Removes this P2P group. **System capability**: SystemCapability.Communication.WiFi.P2P **Return value** -| Type| Description| -| -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| ## wifi.p2pConnect8+ -p2pConnect(config: WifiP2PConfig): boolean; +p2pConnect(config: WifiP2PConfig): boolean Sets up a P2P connection. @@ -735,14 +1463,14 @@ Sets up a P2P connection. **Parameters** -| **Name**| **Type**| Mandatory| **Description**| -| -------- | -------- | -------- | -------- | -| config | [WifiP2PConfig](#WifiP2PConfig) | Yes| Connection configuration.| + | **Name**| **Type**| Mandatory| **Description**| + | -------- | -------- | -------- | -------- | + | config | [WifiP2PConfig](#wifip2pconfig8) | Yes| Connection configuration.| **Return value** -| Type| Description| -| -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -792,7 +1520,7 @@ Sets up a P2P connection. } wifi.on("p2pPeerDeviceChange", recvP2pPeerDeviceChangeFunc); - var recvP2pPersistentGroupChangeFunc = result => { + var recvP2pPersistentGroupChangeFunc = () => { console.info("p2p persistent group change receive event"); wifi.getCurrentGroup((err, data) => { @@ -814,7 +1542,7 @@ Sets up a P2P connection. ## wifi.p2pCancelConnect8+ -p2pCancelConnect(): boolean; +p2pCancelConnect(): boolean Cancels this P2P connection. @@ -823,14 +1551,14 @@ Cancels this P2P connection. **System capability**: SystemCapability.Communication.WiFi.P2P **Return value** -| Type| Description| -| -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| ## wifi.startDiscoverDevices8+ -startDiscoverDevices(): boolean; +startDiscoverDevices(): boolean Starts to discover devices. @@ -839,14 +1567,14 @@ Starts to discover devices. **System capability**: SystemCapability.Communication.WiFi.P2P **Return value** -| Type| Description| -| -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| ## wifi.stopDiscoverDevices8+ -stopDiscoverDevices(): boolean; +stopDiscoverDevices(): boolean Stops discovering devices. @@ -855,9 +1583,106 @@ Stops discovering devices. **System capability**: SystemCapability.Communication.WiFi.P2P **Return value** -| Type| Description| -| -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.deletePersistentGroup8+ + +deletePersistentGroup(netId: number): boolean + +Deletes a persistent group. + +**Required permissions**: ohos.permission.GET_WIFI_INFO + +**System capability**: SystemCapability.Communication.WiFi.P2P + +**Parameters** + + | **Name**| **Type**| Mandatory| **Description**| + | -------- | -------- | -------- | -------- | + | netId | number | Yes| ID of a group to delete.| + +**Return value** + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## wifi.getP2pGroups9+ +This is a system API. + +getP2pGroups(): Promise<Array<WifiP2pGroupInfo>> + +Obtains information about all P2P groups. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.WiFi.P2P + +**Return value** + | Type| Description| + | -------- | -------- | + | Promise< Array<[WifiP2pGroupInfo](#wifip2pgroupinfo8)> > | Promise used to return the group information obtained.| + + +## WifiP2pGroupInfo8+ + +Represents the P2P group information. + +**System capability**: SystemCapability.Communication.WiFi.P2P + +| Name| Type| Readable/Writable| Description| +| -------- | -------- | -------- | -------- | +| isP2pGo | boolean | Read only| Whether the device is the group owner.| +| ownerInfo | [WifiP2pDevice](#wifip2pdevice8) | Read only| Device information of the group.| +| passphrase | string | Read only| Passphrase of the group.| +| interface | string | Read only| Interface name.| +| groupName | string | Read only| Group name.| +| networkId | number | Read only| Network ID.| +| frequency | number | Read only| Frequency of the group.| +| clientDevices | [WifiP2pDevice[]](#wifip2pdevice8) | Read only| List of connected devices.| +| goIpAddress | string | Read only| IP address of the group.| + + +## wifi.getP2pGroups9+ + +getP2pGroups(callback: AsyncCallback<Array<WifiP2pGroupInfo>>): void + +Obtains information about all P2P groups. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.WiFi.P2P + +**Parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback< Array<[WifiP2pGroupInfo](#wifip2pgroupinfo8)>> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the group information obtained. If **err** is not **0**, an error has occurred.| + + +## wifi.setDeviceName8+ + +setDeviceName(devName: string): boolean + +Sets the device name. +This is a system API. + +**Required permissions**: + ohos.permission.SET_WIFI_INFO and ohos.permission.MANAGE_WIFI_CONNECTION (available only to system applications) + +**System capability**: SystemCapability.Communication.WiFi.P2P + +**Parameters** + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | devName | string | Yes| Device name to set.| + +**Return value** + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| ## wifi.on('wifiStateChange')7+ @@ -871,10 +1696,10 @@ Registers the WLAN state change events. **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **wifiStateChange**.| -| callback | Callback<number> | Yes| Callback invoked to return the WLAN state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **wifiStateChange**.| + | callback | Callback<number> | Yes| Callback invoked to return the WLAN state.| **WLAN states** @@ -897,10 +1722,10 @@ Unregisters the WLAN state change events. **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **wifiStateChange**.| -| callback | Callback<number> | No| Callback used to return the WLAN state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **wifiStateChange**.| + | callback | Callback<number> | No| Callback used to return the WLAN state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| **Example** ```js @@ -930,10 +1755,10 @@ Registers the WLAN connection state change events. **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **wifiConnectionChange**.| -| callback | Callback<number> | Yes| Callback invoked to return the WLAN connection state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **wifiConnectionChange**.| + | callback | Callback<number> | Yes| Callback invoked to return the WLAN connection state.| **WLAN connection states** @@ -954,10 +1779,10 @@ Unregisters the WLAN connection state change events. **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **wifiConnectionChange**.| -| callback | Callback<number> | No| Callback used to return the WLAN connection state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **wifiConnectionChange**.| + | callback | Callback<number> | No| Callback used to return the WLAN connection state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('wifiScanStateChange')7+ @@ -971,10 +1796,10 @@ Registers the WLAN scan state change events. **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **wifiScanStateChange**.| -| callback | Callback<number> | Yes| Callback invoked to return the WLAN scan state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **wifiScanStateChange**.| + | callback | Callback<number> | Yes| Callback invoked to return the WLAN scan state.| **WLAN scan states** @@ -1013,10 +1838,10 @@ Registers the RSSI change events. **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **wifiRssiChange**.| -| callback | Callback<number> | Yes| Callback invoked to return the RSSI, in dBm.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **wifiRssiChange**.| + | callback | Callback<number> | Yes| Callback invoked to return the RSSI, in dBm.| ## wifi.off('wifiRssiChange')7+ @@ -1030,10 +1855,10 @@ Unregisters the RSSI change events. **System capability**: SystemCapability.Communication.WiFi.STA **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **wifiRssiChange**.| -| callback | Callback<number> | No| Callback used to return the RSSI, in dBm. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **wifiRssiChange**.| + | callback | Callback<number> | No| Callback used to return the RSSI. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('hotspotStateChange')7+ @@ -1047,10 +1872,10 @@ Registers the hotspot state change events. **System capability**: SystemCapability.Communication.WiFi.AP.Core **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **hotspotStateChange**.| -| callback | Callback<number> | Yes| Callback invoked to return the hotspot state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **hotspotStateChange**.| + | callback | Callback<number> | Yes| Callback invoked to return the hotspot state.| **Hotspot states** @@ -1073,10 +1898,10 @@ Unregisters the hotspot state change events. **System capability**: SystemCapability.Communication.WiFi.AP.Core **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **hotspotStateChange**.| -| callback | Callback<number> | No| Callback used to return the hotspot state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **hotspotStateChange**.| + | callback | Callback<number> | No| Callback used to return the hotspot state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('p2pStateChange')8+ @@ -1090,10 +1915,10 @@ Registers the P2P state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pStateChange**.| -| callback | Callback<number> | Yes| Callback invoked to return the P2P state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pStateChange**.| + | callback | Callback<number> | Yes| Callback invoked to return the P2P state.| **P2P states** @@ -1116,10 +1941,10 @@ Unregisters the P2P state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pStateChange**.| -| callback | Callback<number> | No| Callback used to return the P2P state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pStateChange**.| + | callback | Callback<number> | No| Callback used to return the P2P state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('p2pConnectionChange')8+ @@ -1133,10 +1958,10 @@ Registers the P2P connection state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pConnectionChange**.| -| callback | Callback<[WifiP2pLinkedInfo](#WifiP2pLinkedInfo)> | Yes| Callback invoked to return the P2P connection state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pConnectionChange**.| + | callback | Callback<[WifiP2pLinkedInfo](#wifip2plinkedinfo8)> | Yes| Callback invoked to return the P2P connection state.| ## wifi.off('p2pConnectionChange')8+ @@ -1150,10 +1975,10 @@ Unregisters the P2P connection state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pConnectionChange**.| -| callback | Callback<[WifiP2pLinkedInfo](#WifiP2pLinkedInfo)> | No| Callback used to return the P2P connection state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pConnectionChange**.| + | callback | Callback<[WifiP2pLinkedInfo](#wifip2plinkedinfo8)> | No| Callback used to return the P2P connection state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('p2pDeviceChange')8+ @@ -1167,10 +1992,10 @@ Registers the P2P device state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pDeviceChange**.| -| callback | Callback<[WifiP2pDevice](#WifiP2pDevice)> | Yes| Callback invoked to return the P2P device state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pDeviceChange**.| + | callback | Callback<[WifiP2pDevice](#wifip2pdevice8)> | Yes| Callback invoked to return the P2P device state.| ## wifi.off('p2pDeviceChange')8+ @@ -1184,10 +2009,10 @@ Unregisters the P2P device state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pDeviceChange**.| -| callback | Callback<[WifiP2pDevice](#WifiP2pDevice)> | No| Callback used to return the P2P device state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pDeviceChange**.| + | callback | Callback<[WifiP2pDevice](#wifip2pdevice8)> | No| Callback used to return the P2P device state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('p2pPeerDeviceChange')8+ @@ -1201,10 +2026,10 @@ Registers the P2P peer device state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pPeerDeviceChange**.| -| callback | Callback<[WifiP2pDevice[]](#WifiP2pDevice)> | Yes| Callback invoked to return the P2P peer device state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pPeerDeviceChange**.| + | callback | Callback<[WifiP2pDevice[]](#wifip2pdevice8)> | Yes| Callback invoked to return the P2P peer device state.| ## wifi.off('p2pPeerDeviceChange')8+ @@ -1218,10 +2043,10 @@ Unregisters the P2P peer device state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pPeerDeviceChange**.| -| callback | Callback<[WifiP2pDevice[]](#WifiP2pDevice)> | No| Callback used to return the P2P peer device state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pPeerDeviceChange**.| + | callback | Callback<[WifiP2pDevice[]](#wifip2pdevice8)> | No| Callback used to return the peer device state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('p2pPersistentGroupChange')8+ @@ -1235,10 +2060,10 @@ Registers the P2P persistent group state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pPersistentGroupChange**.| -| callback | Callback<void> | Yes| Callback invoked to return the P2P persistent group state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pPersistentGroupChange**.| + | callback | Callback<void> | Yes| Callback invoked to return the P2P persistent group state.| ## wifi.off('p2pPersistentGroupChange')8+ @@ -1252,10 +2077,10 @@ Unregisters the P2P persistent group state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pPersistentGroupChange**.| -| callback | Callback<void> | No| Callback used to return the P2P persistent group state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pPersistentGroupChange**.| + | callback | Callback<void> | No| Callback used to return the P2P persistent group state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| ## wifi.on('p2pDiscoveryChange')8+ @@ -1269,10 +2094,10 @@ Registers the P2P device discovery state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pDiscoveryChange**.| -| callback | Callback<number> | Yes| Callback invoked to return the P2P device discovery state.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pDiscoveryChange**.| + | callback | Callback<number> | Yes| Callback invoked to return the P2P device discovery state.| **P2P discovered device states** @@ -1293,7 +2118,7 @@ Unregisters the P2P device discovery state change events. **System capability**: SystemCapability.Communication.WiFi.P2P **Parameters** -| **Name**| **Type**| **Mandatory**| **Description**| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is **p2pDiscoveryChange**.| -| callback | Callback<number> | No| Callback used to return the P2P device discovery state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **p2pDiscoveryChange**.| + | callback | Callback<number> | No| Callback used to return the P2P device discovery state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| diff --git a/en/application-dev/reference/apis/js-apis-wifiext.md b/en/application-dev/reference/apis/js-apis-wifiext.md index 2e2e9394b2a4361fa8adad332c459d4ff33a4e4d..f54b65d4b492cf65bb367b52a021cb1f061af6bb 100644 --- a/en/application-dev/reference/apis/js-apis-wifiext.md +++ b/en/application-dev/reference/apis/js-apis-wifiext.md @@ -1,6 +1,7 @@ # WLAN +This **wifiext** module provides WLAN extension interfaces for non-universal products. -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. The APIs described in this document are used only for non-universal products, such as routers. @@ -17,13 +18,11 @@ enableHotspot(): boolean; Enables the WLAN hotspot. -- Required permissions: - ohos.permission.MANAGE_WIFI_HOTSPOT_EXT +**Required permissions**: ohos.permission.MANAGE_WIFI_HOTSPOT_EXT -- System capability: - SystemCapability.Communication.WiFi.AP.Extension +**System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Return value +**Return value** | **Type**| **Description**| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| @@ -35,13 +34,11 @@ disableHotspot(): boolean; Disables the WLAN hotspot. -- Required permissions: - ohos.permission.MANAGE_WIFI_HOTSPOT_EXT +**Required permissions**: ohos.permission.MANAGE_WIFI_HOTSPOT_EXT -- System capability: - SystemCapability.Communication.WiFi.AP.Extension +**System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Return value +**Return value** | **Type**| **Description**| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| @@ -51,24 +48,24 @@ Disables the WLAN hotspot. getSupportedPowerModel(): Promise<Array<PowerModel>> -Obtains the supported power models. The method uses a promise to return the result. +Obtains the supported power models. This API uses a promise to return the result. -- Required permissions: - ohos.permission.GET_WIFI_INFO +**Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: - SystemCapability.Communication.WiFi.AP.Extension +**System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Return value +**Return value** | Type| Description| | -------- | -------- | - | Promise<Array<[PowerModel](#PowerModel)>> | Promise used to return the power models obtained.| + | Promise<Array<[PowerModel](#powermodel)>> | Promise used to return the power models obtained.| ## PowerModel Enumerates of the power models. +**System capability**: SystemCapability.Communication.WiFi.AP.Extension + | Name| Default Value| Description| | -------- | -------- | -------- | | SLEEPING | 0 | Sleeping| @@ -80,54 +77,48 @@ Enumerates of the power models. getSupportedPowerModel(callback: AsyncCallback<Array<PowerModel>>): void -Obtains the supported power models. The method uses an asynchronous callback to return the result. +Obtains the supported power models. This API uses an asynchronous callback to return the result. -- Required permissions: - ohos.permission.GET_WIFI_INFO +**Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: - SystemCapability.Communication.WiFi.AP.Extension +**System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Parameters +**Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[PowerModel](#PowerModel)> | Yes| Callback used to return the power models obtained.| + | callback | AsyncCallback<[PowerModel](#powermodel)> | Yes| Callback invoked to return the result. If the operation is successful, **err** is 0 and **data** is the power models obtained. If **err** is not **0**, an error has occurred.| ## wifiext.getPowerModel getPowerModel(): Promise<PowerModel> -Obtains the power model. The method uses a promise to return the result. +Obtains the power model. This API uses a promise to return the result. -- Required permissions: - ohos.permission.GET_WIFI_INFO +**Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: - SystemCapability.Communication.WiFi.AP.Extension +**System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Return value +**Return value** | Type| Description| | -------- | -------- | - | Promise<[PowerModel](#PowerModel)> | Promise used to return the power model obtained.| + | Promise<[PowerModel](#powermodel)> | Promise used to return the power model obtained.| ## wifiext.getPowerModel getPowerModel(callback: AsyncCallback<PowerModel>): void -Obtains the power model. The method uses an asynchronous callback to return the result. +Obtains the power model. This API uses an asynchronous callback to return the result. -- Required permissions: - ohos.permission.GET_WIFI_INFO +**Required permissions**: ohos.permission.GET_WIFI_INFO -- System capability: - SystemCapability.Communication.WiFi.AP.Extension +**System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Parameters +**Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[PowerModel](#PowerModel)> | Yes| Callback invoked to return the power mode obtained.| + | callback | AsyncCallback<[PowerModel](#powermodel)> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **0** and **data** is the power mode obtained. If **err** is not **0**, an error has occurred.| ## wifiext.setPowerModel @@ -136,18 +127,16 @@ setPowerModel(model: PowerModel) : boolean; Sets the power model. -- Required permissions: - ohos.permission.MANAGE_WIFI_HOTSPOT_EXT +**Required permissions**: ohos.permission.MANAGE_WIFI_HOTSPOT_EXT -- System capability: - SystemCapability.Communication.WiFi.AP.Extension +**System capability**: SystemCapability.Communication.WiFi.AP.Extension -- Parameters +**Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | model | AsyncCallback<[PowerModel](#PowerModel)> | Yes| Power model to set.| + | model | AsyncCallback<[PowerModel](#powermodel)> | Yes| Power model to set.| -- Return value +**Return value** | **Type**| **Description**| | -------- | -------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| diff --git a/en/application-dev/reference/apis/js-apis-window.md b/en/application-dev/reference/apis/js-apis-window.md index b5eab0ff1825741b77cf81ae966c499aff4c1398..76bba2f5b15c6a9da9b2f4bb4f5201f4552a9cbd 100644 --- a/en/application-dev/reference/apis/js-apis-window.md +++ b/en/application-dev/reference/apis/js-apis-window.md @@ -25,21 +25,24 @@ Enumerates the window types. | Name | Value| Description | | ----------------- | ------ | ------------------ | -| TYPE_APP | 0 | Application subwindow. This type can be used only in the FA model.| +| TYPE_APP | 0 | Application subwindow.
**Model restriction**: This API can be used only in the FA model.| | TYPE_SYSTEM_ALERT | 1 | System alert window.| -| TYPE_INPUT_METHOD9+ | 2 | Input method window. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_STATUS_BAR9+ | 3 | Status bar. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_PANEL9+ | 4 | Notification panel. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_KEYGUARD9+ | 5 | Lock screen. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_VOLUME_OVERLAY9+ | 6 | Volume bar. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_NAVIGATION_BAR9+ | 7 | Navigation bar. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_FLOAT9+ | 8 | Floating window. This type can be used only in the stage model.
**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW| -| TYPE_WALLPAPER9+ | 9 | Wallpaper. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_DESKTOP9+ | 10 | Home screen. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_LAUNCHER_RECENT9+ | 11 | Recent tasks screen. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_LAUNCHER_DOCK9+ | 12 | Dock bar on the home screen. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_VOICE_INTERACTION9+ | 13 | Voice assistant. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| -| TYPE_POINTER9+ | 14 | Mouse. This type can be used only in the stage model.
This is a system API and cannot be called by third-party applications.| +| TYPE_INPUT_METHOD9+ | 2 | Input method window.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_STATUS_BAR9+ | 3 | Status bar.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_PANEL9+ | 4 | Notification panel.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_KEYGUARD9+ | 5 | Lock screen.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_VOLUME_OVERLAY9+ | 6 | Volume bar.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_NAVIGATION_BAR9+ | 7 | Navigation bar.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_FLOAT9+ | 8 | Floating window.
**Model restriction**: This API can be used only in the stage model.
**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW| +| TYPE_WALLPAPER9+ | 9 | Wallpaper.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_DESKTOP9+ | 10 | Home screen.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_LAUNCHER_RECENT9+ | 11 | Recent tasks screen.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_LAUNCHER_DOCK9+ | 12 | Dock bar on the home screen.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_VOICE_INTERACTION9+ | 13 | Voice assistant.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_POINTER9+ | 14 | Mouse.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_FLOAT_CAMERA9+ | 15 | Floating camera window.
**Model restriction**: This API can be used only in the stage model.
**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW| +| TYPE_DIALOG9+ | 16 | Modal window.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| +| TYPE_SCREENSHOT9+ | 17 | Screenshot window.
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.| ## AvoidAreaType7+ @@ -58,7 +61,7 @@ Enumerates the types of the area where the window cannot be displayed. Enumerates the window modes. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -74,7 +77,7 @@ This is a system API and cannot be called by third-party applications. Enumerates the window layout modes. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -119,11 +122,26 @@ Enumerates the window orientations. | AUTO_ROTATION_LANDSCAPE_RESTRICTED | 10 | Switched-determined auto rotation in the horizontal direction.| | LOCKED | 11 | Locked.| +## BlurStyle9+ + +Enumerates the window blur styles. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Value | Description | +| ------- | ---- | -------------------- | +| OFF | 0 | Blur disabled. | +| THIN | 1 | Thin blur.| +| REGULAR | 2 | Regular blur.| +| THICK | 3 | Thick blur.| + ## SystemBarRegionTint8+ Describes the callback for a single system bar. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -139,7 +157,7 @@ This is a system API and cannot be called by third-party applications. Describes the callback for the current system bar. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -169,7 +187,7 @@ Describes the area where the window cannot be displayed. | Name | Type | Readable| Writable| Description | | ---------- | ------------- | ---- | ---- | ------------------ | -| visible9+ | boolean | Yes | Yes | Whether the area is visible.| +| visible9+ | boolean | Yes | Yes | Whether the window can be displayed in the area.| | leftRect | [Rect](#rect) | Yes | Yes | Rectangle on the left of the screen.| | topRect | [Rect](#rect) | Yes | Yes | Rectangle at the top of the screen.| | rightRect | [Rect](#rect) | Yes | Yes | Rectangle on the right of the screen.| @@ -192,20 +210,20 @@ Describes the window properties. **System capability**: SystemCapability.WindowManager.WindowManager.Core -| Name | Type | Readable| Writable| Description | -| ------------------------------- | ------------------------- | ---- | ---- | -------------------------------------------- | -| windowRect7+ | [Rect](#rect) | Yes | Yes | Window size. | -| type7+ | [WindowType](#windowtype) | Yes | Yes | Window type. | -| isFullScreen | boolean | Yes | Yes | Whether the window is displayed in full screen mode. The default value is `false`. | -| isLayoutFullScreen7+ | boolean | Yes | Yes | Whether the window layout is in full-screen mode (whether the window is immersive). The default value is `false`. | -| focusable7+ | boolean | Yes | No | Whether the window can gain focus. The default value is `true`. | -| touchable7+ | boolean | Yes | No | Whether the window is touchable. The default value is `true`. | -| brightness | number | Yes | Yes | Screen brightness. The value ranges from 0 to 1. The value `1` indicates the maximum brightness. | -| dimBehindValue(deprecated) | number | Yes | Yes | Dimness of the window that is not on top. The value ranges from 0 to 1. The value `1` indicates the maximum dimness.
**NOTE**
This attribute is deprecated since API version 9.
| -| isKeepScreenOn | boolean | Yes | Yes | Whether the screen is always on. The default value is `false`. | -| isPrivacyMode7+ | boolean | Yes | Yes | Whether the window is in privacy mode. The default value is `false`. | -| isRoundCorner7+ | boolean | Yes | Yes | Whether the window has rounded corners. The default value is `false`. | -| isTransparent7+ | boolean | Yes | Yes | Whether the window is transparent. The default value is `false`. | +| Name | Type | Readable| Writable| Description | +| ------------------------------------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ | +| windowRect7+ | [Rect](#rect) | Yes | Yes | Window size. | +| type7+ | [WindowType](#windowtype) | Yes | Yes | Window type. | +| isFullScreen | boolean | Yes | Yes | Whether the window is displayed in full screen mode. The default value is `false`. | +| isLayoutFullScreen7+ | boolean | Yes | Yes | Whether the window layout is in full-screen mode (whether the window is immersive). The default value is `false`. | +| focusable7+ | boolean | Yes | No | Whether the window can gain focus. The default value is `true`. | +| touchable7+ | boolean | Yes | No | Whether the window is touchable. The default value is `true`. | +| brightness | number | Yes | Yes | Screen brightness. The value ranges from 0 to 1. The value `1` indicates the maximum brightness. | +| dimBehindValue(deprecated) | number | Yes | Yes | Dimness of the window that is not on top. The value ranges from 0 to 1. The value `1` indicates the maximum dimness.
**NOTE**
This property is supported since API version 7 and deprecated since API version 9.
| +| isKeepScreenOn | boolean | Yes | Yes | Whether the screen is always on. The default value is `false`. | +| isPrivacyMode7+ | boolean | Yes | Yes | Whether the window is in privacy mode. The default value is `false`. | +| isRoundCorner(deprecated) | boolean | Yes | Yes | Whether the window has rounded corners. The default value is `false`.
**NOTE**
This property is supported since API version 7 and deprecated since API version 9.
| +| isTransparent7+ | boolean | Yes | Yes | Whether the window is transparent. The default value is `false`. | ## ColorSpace8+ @@ -218,13 +236,58 @@ Describes the color gamut mode. | DEFAULT | 0 | Default color gamut mode.| | WIDE_GAMUT | 1 | Wide color gamut mode. | +## ScaleOptions9+ + +Describes the scale parameters. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type| Readable| Writable| Description | +| ------ | -------- | ---- | ---- | -------------------------------------------------- | +| x | number | No | Yes | Scale factor of the x-axis. The default value is `1.0`. | +| y | number | No | Yes | Scale factor of the y-axis. The default value is `1.0`. | +| pivotX | number | No | Yes | X coordinate of the scale center. The value ranges from 0.0 to 1.0, and the default value is `0.5`.| +| pivotY | number | No | Yes | Y coordinate of the scale center. The value ranges from 0.0 to 1.0, and the default value is `0.5`.| + +## RotateOptions9+ + +Describes the rotation parameters. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type| Readable| Writable| Description | +| ------ | -------- | ---- | ---- | -------------------------------------------------- | +| x | number | No | Yes | Rotation angle around the x-axis. The default value is `0.0`. | +| y | number | No | Yes | Rotation angle around the y-axis. The default value is `0.0`. | +| z | number | No | Yes | Rotation angle around the z-xis. The default value is `0.0`. | +| pivotX | number | No | Yes | X coordinate of the rotation center. The value ranges from 0.0 to 1.0, and the default value is `0.5`.| +| pivotY | number | No | Yes | Y coordinate of the rotation center. The value ranges from 0.0 to 1.0, and the default value is `0.5`.| + +## TranslateOptions9+ + +Describes the translation parameters. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name| Type| Readable| Writable| Description | +| ---- | -------- | ---- | ---- | ---------------------------- | +| x | number | No | Yes | Distance to translate along the x-axis. The default value is `0.0`.| +| y | number | No | Yes | Distance to translate along the y-axis. The default value is `0.0`.| +| z | number | No | Yes | Distance to translate along the z-axis. The default value is `0.0`.| + ## window.create7+ create(id: string, type: WindowType, callback: AsyncCallback<Window>): void Creates a subwindow. This API uses an asynchronous callback to return the result. -This API can be used only in the FA model. +**Model restriction**: This API can be used only in the FA model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -240,13 +303,14 @@ This API can be used only in the FA model. ```js var windowClass = null; - let promise = window.create("first", window.WindowType.TYPE_APP); - promise.then((data)=> { - windowClass = data; - console.info('SubWindow created. Data: ' + JSON.stringify(data)); - }).catch((err)=>{ - console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err)); - }); +window.create("first", window.WindowType.TYPE_APP,(err,data) => { + if(err.code){ + console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err)); + return; + } + windowClass = data; + console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); +}); ``` ## window.create7+ @@ -255,7 +319,7 @@ create(id: string, type: WindowType): Promise<Window> Creates a subwindow. This API uses a promise to return the result. -This API can be used only in the FA model. +**Model restriction**: This API can be used only in the FA model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -279,7 +343,7 @@ var windowClass = null; let promise = window.create("first", window.WindowType.TYPE_APP); promise.then((data)=> { windowClass = data; - console.info('SubWindow created. Data: ' + JSON.stringify(data)); + console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); }).catch((err)=>{ console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err)); }); @@ -300,7 +364,7 @@ Creates a subwindow (in API version 8) or a system window (from API version 9). | ctx | Context | Yes | Current application context.
For the definition of `Context` of API version 8, see [Context](js-apis-Context.md).
For the definition of `Context` of API version 9, see [ServiceExtensionContext](js-apis-service-extension-context.md).| | id | string | Yes | Window ID. | | type | [WindowType](#windowtype) | Yes | Window type. | -| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the window created. | +| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow created. | **Example** @@ -308,11 +372,11 @@ Creates a subwindow (in API version 8) or a system window (from API version 9). var windowClass = null; window.create(this.context, "alertWindow", window.WindowType.TYPE_SYSTEM_ALERT, (err, data) => { if (err.code) { - console.error('Failed to create the Window. Cause: ' + JSON.stringify(err)); + console.error('Failed to create the window. Cause: ' + JSON.stringify(err)); return; } windowClass = data; - console.info('Window created. Data: ' + JSON.stringify(data)); + console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data)); windowClass.resetSize(500, 1000); }); ``` @@ -337,7 +401,7 @@ Creates a subwindow (in API version 8) or a system window (from API version 9). | Type | Description | | -------------------------------- | --------------------------------------- | -| Promise<[Window](#window)> | Promise used to return the window created. | +| Promise<[Window](#window)> | Promise used to return the subwindow created.| **Example** @@ -345,8 +409,8 @@ Creates a subwindow (in API version 8) or a system window (from API version 9). var windowClass = null; let promise = window.create(this.context, "alertWindow", window.WindowType.TYPE_SYSTEM_ALERT); promise.then((data)=> { - windowClass = data; - console.info('Window created. Data:' + JSON.stringify(data)); + windowClass = data; + console.info('Succeeded in creating the window. Data:' + JSON.stringify(data)); }).catch((err)=>{ console.error('Failed to create the Window. Cause:' + JSON.stringify(err)); }); @@ -377,7 +441,7 @@ var windowClass = null; return; } windowClass = data; - console.info('window found. Data: ' + JSON.stringify(data)); + console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); }); ``` @@ -408,7 +472,7 @@ var windowClass = null; let promise = window.find("alertWindow"); promise.then((data)=> { windowClass = data; - console.info('window found. Data: ' + JSON.stringify(data)); + console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); }).catch((err)=>{ console.error('Failed to find the Window. Cause: ' + JSON.stringify(err)); }); @@ -420,7 +484,7 @@ getTopWindow(callback: AsyncCallback<Window>): void Obtains the top window of the current application. This API uses an asynchronous callback to return the result. -This API can be used only in the FA model. +**Model restriction**: This API can be used only in the FA model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -450,7 +514,7 @@ getTopWindow(): Promise<Window> Obtains the top window of the current application. This API uses a promise to return the result. -This API can be used only in the FA model. +**Model restriction**: This API can be used only in the FA model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -540,7 +604,7 @@ minimizeAll(id: number, callback: AsyncCallback<void>): void Minimizes all windows on a display. This API uses an asynchronous callback to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -548,7 +612,7 @@ This is a system API and cannot be called by third-party applications. | Name | Type | Mandatory| Description | | -------- | ------------------------- | ---- | -------------- | -| id | number | Yes | ID of the [display](js-apis-display.md#display). | +| id | number | Yes | ID of the [display](js-apis-display.md#display).| | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** @@ -578,7 +642,7 @@ minimizeAll(id: number): Promise<void> Minimizes all windows on a display. This API uses a promise to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -620,7 +684,7 @@ toggleShownStateForAllAppWindows(callback: AsyncCallback<void>): void Hides or restores the application's windows during quick multi-window switching. This API uses an asynchronous callback to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -647,7 +711,7 @@ toggleShownStateForAllAppWindows(): Promise<void> Hides or restores the application's windows during quick multi-window switching. This API uses a promise to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -673,7 +737,7 @@ setWindowLayoutMode(mode: WindowLayoutMode, callback: AsyncCallback<void>) Sets the window layout mode. This API uses an asynchronous callback to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -697,7 +761,7 @@ setWindowLayoutMode(mode: WindowLayoutMode): Promise<void> Sets the window layout mode. This API uses a promise to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -730,7 +794,7 @@ on(type: 'systemBarTintChange', callback: Callback<SystemBarTintState>): v Enables listening for properties changes of the status bar and navigation bar. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -755,7 +819,7 @@ off(type: 'systemBarTintChange', callback?: Callback<SystemBarTintState >) Disables listening for properties changes of the status bar and navigation bar. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -784,7 +848,7 @@ hide (callback: AsyncCallback<void>): void Hides this window. This API uses an asynchronous callback to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -802,7 +866,7 @@ windowClass.hide((err, data) => { console.error('Failed to hide the window. Cause: ' + JSON.stringify(err)); return; } - console.info('window hidden. data: ' + JSON.stringify(data)); + console.info('Succeeded in hiding the window. data: ' + JSON.stringify(data)); }) ``` @@ -812,7 +876,7 @@ hide(): Promise<void> Hides this window. This API uses a promise to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -827,12 +891,67 @@ This is a system API and cannot be called by third-party applications. ```js let promise = windowClass.hide(); promise.then((data)=> { - console.info('window hidden. Data: ' + JSON.stringify(data)); + console.info('Succeeded in hiding the window. Data: ' + JSON.stringify(data)); }).catch((err)=>{ console.error('Failed to hide the window. Cause: ' + JSON.stringify(err)); }) ``` +### hideWithAnimation9+ + +hideWithAnimation(callback: AsyncCallback<void>): void + +Hides this window and plays an animation during the process. This API uses an asynchronous callback to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +windowClass.hideWithAnimation((err, data) => { + if (err.code) { + console.error('Failed to hide the window with animation. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in hiding the window with animation. data: ' + JSON.stringify(data)); +}) +``` + +### hideWithAnimation9+ + +hideWithAnimation(): Promise<void> + +Hides this window and plays an animation during the process. This API uses a promise to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```js +let promise = windowClass.hideWithAnimation(); +promise.then((data)=> { + console.info('Succeeded in hiding the window with animation. Data: ' + JSON.stringify(data)); +}).catch((err)=>{ + console.error('Failed to hide the window with animation. Cause: ' + JSON.stringify(err)); +}) +``` + ### show7+ show(callback: AsyncCallback<void>): void @@ -884,6 +1003,61 @@ promise.then((data)=> { }) ``` +### showWithAnimation9+ + +showWithAnimation(callback: AsyncCallback<void>): void + +Shows this window and plays an animation during the process. This API uses an asynchronous callback to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +windowClass.showWithAnimation((err, data) => { + if (err.code) { + console.error('Failed to show the window with animation. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in showing the window with animation. Data: ' + JSON.stringify(data)); +}) +``` + +### showWithAnimation9+ + +showWithAnimation(): Promise<void> + +Shows this window and plays an animation during the process. This API uses a promise to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```js +let promise = windowClass.showWithAnimation(); +promise.then((data)=> { + console.info('Succeeded in showing the window with animation. Data: ' + JSON.stringify(data)); +}).catch((err)=>{ + console.error('Failed to show the window with animation. Cause: ' + JSON.stringify(err)); +}) +``` + ### destroy7+ destroy(callback: AsyncCallback<void>): void @@ -959,7 +1133,7 @@ windowClass.moveTo(300, 300, (err, data)=>{ console.error('Failed to move the window. Cause:' + JSON.stringify(err)); return; } - console.info('Window moved. Data: ' + JSON.stringify(data)); + console.info('Succeeded in moving the window. Data: ' + JSON.stringify(data)); }); ``` @@ -990,7 +1164,7 @@ Moves this window. This API uses a promise to return the result. ```js let promise = windowClass.moveTo(300, 300); promise.then((data)=> { - console.info('Window moved. Data: ' + JSON.stringify(data)); + console.info('Succeeded in moving the window. Data: ' + JSON.stringify(data)); }).catch((err)=>{ console.error('Failed to move the window. Cause: ' + JSON.stringify(err)); }) @@ -1020,7 +1194,7 @@ windowClass.resetSize(500, 1000, (err, data) => { console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); return; } - console.info('Window size changed. Data: ' + JSON.stringify(data)); + console.info('Succeeded in changing the window size. Data: ' + JSON.stringify(data)); }); ``` @@ -1050,19 +1224,23 @@ Changes the size of this window. This API uses a promise to return the result. ```js let promise = windowClass.resetSize(500, 1000); promise.then((data)=> { - console.info('Window size changed. Data: ' + JSON.stringify(data)); + console.info('Succeeded in changing the window size. Data: ' + JSON.stringify(data)); }).catch((err)=>{ console.error('Failed to change the window size. Cause: ' + JSON.stringify(err)); }); ``` -### setWindowType7+ +### setWindowType(deprecated) setWindowType(type: WindowType, callback: AsyncCallback<void>): void Sets the type of this window. This API uses an asynchronous callback to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. + +> **NOTE**
This API is supported since API version 7 and deprecated since API version 9. +> +> **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1086,13 +1264,17 @@ windowClass.setWindowType(type, (err, data) => { }); ``` -### setWindowType7+ +### setWindowType(deprecated) setWindowType(type: WindowType): Promise<void> Sets the type of this window. This API uses a promise to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. + +> **NOTE**
This API is supported since API version 7 and deprecated since API version 9. +> +> **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1183,7 +1365,7 @@ Obtains the area where this window cannot be displayed, for example, the system | Name | Type | Mandatory| Description | | -------- |-----------------------------------------------| ---- | ------------------------------------------------------------ | -| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. `TYPE_SYSTEM` indicates the default area of the system. `TYPE_CUTOUT` indicates the notch. **TYPE_SYSTEM_GESTURE** indicates the gesture area. **TYPE_KEYBOARD** indicates the soft keyboard area.| +| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. `TYPE_SYSTEM` indicates the default area of the system. `TYPE_CUTOUT` indicates the notch. `TYPE_SYSTEM_GESTURE` indicates the gesture area. `TYPE_KEYBOARD` indicates the soft keyboard area.| | callback | AsyncCallback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. | **Example** @@ -1211,7 +1393,7 @@ Obtains the area where this window cannot be displayed, for example, the system | Name| Type | Mandatory| Description | | ------ |----------------------------------| ---- | ------------------------------------------------------------ | -| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. `TYPE_SYSTEM` indicates the default area of the system. `TYPE_CUTOUT` indicates the notch. **TYPE_SYSTEM_GESTURE** indicates the gesture area. **TYPE_KEYBOARD** indicates the soft keyboard area.| +| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. `TYPE_SYSTEM` indicates the default area of the system. `TYPE_CUTOUT` indicates the notch. `TYPE_SYSTEM_GESTURE` indicates the gesture area. `TYPE_KEYBOARD` indicates the soft keyboard area.| **Return value** @@ -1368,13 +1550,14 @@ Sets whether to display the status bar and navigation bar in this window. This A **Example** ```js -var names = ["status", "navigation"]; +// In this example, the status bar and navigation bar are not displayed. +var names = []; windowClass.setSystemBarEnable(names, (err, data) => { if (err.code) { - console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); + console.error('Failed to set the system bar to be invisible. Cause:' + JSON.stringify(err)); return; } - console.info('Succeeded in setting the system bar to be visible. Data: ' + JSON.stringify(data)); + console.info('Succeeded in setting the system bar to be invisible. Data: ' + JSON.stringify(data)); }); ``` @@ -1401,12 +1584,13 @@ Sets whether to display the status bar and navigation bar in this window. This A **Example** ```js -var names = ["status", "navigation"]; +// In this example, the status bar and navigation bar are not displayed. +var names = []; let promise = windowClass.setSystemBarEnable(names); promise.then((data)=> { - console.info('Succeeded in setting the system bar to be visible. Data: ' + JSON.stringify(data)); + console.info('Succeeded in setting the system bar to be invisible. Data: ' + JSON.stringify(data)); }).catch((err)=>{ - console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); + console.error('Failed to set the system bar to be invisible. Cause:' + JSON.stringify(err)); }); ``` @@ -1611,7 +1795,7 @@ loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void Loads content from a page associated with a local storage to this window. This API uses an asynchronous callback to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1620,14 +1804,14 @@ This API can be used only in the stage model. | Name | Type | Mandatory| Description | | -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | Yes | Path of the page from which the content will be loaded. | -| storage | LocalStorage | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| +| storage | [LocalStorage](../../ui/ui-ts-local-storage.md) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** ```ts class myAbility extends Ability { - storage : LocalStorage + storage : LocalStorage onWindowStageCreate(windowStage) { this.storage = new LocalStorage(); this.storage.setOrCreate("storageSimpleProp",121); @@ -1649,7 +1833,7 @@ loadContent(path: string, storage: LocalStorage): Promise<void> Loads content from a page associated with a local storage to this window. This API uses a promise to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1658,7 +1842,7 @@ This API can be used only in the stage model. | Name | Type | Mandatory| Description | | ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | Yes | Path of the page from which the content will be loaded. | -| storage | LocalStorage | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| +| storage | [LocalStorage](../../ui/ui-ts-local-storage.md) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| **Return value** @@ -1670,7 +1854,7 @@ This API can be used only in the stage model. ```ts class myAbility extends Ability { - storage : LocalStorage + storage : LocalStorage onWindowStageCreate(windowStage) { this.storage = new LocalStorage(); this.storage.setOrCreate("storageSimpleProp",121); @@ -1786,9 +1970,9 @@ windowClass.off('windowSizeChange'); on(type: 'systemAvoidAreaChange', callback: Callback<[AvoidArea](#avoidarea7)>): void Enables listening for changes to the area where the window cannot be displayed. -> **NOTE** +> **NOTE**
This API is supported since API version 7 and deprecated since API version 9. Use [on('avoidAreaChange')](#onavoidareachange9) instead. > -> This API is deprecated since API version 9. Use [on('avoidAreaChange')](#onavoidareachange9) instead. +> **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1812,9 +1996,9 @@ windowClass.on('systemAvoidAreaChange', (data) => { off(type: 'systemAvoidAreaChange', callback?: Callback<[AvoidArea](#avoidarea7)>): void Disables listening for changes to the area where the window cannot be displayed. -> **NOTE** +> **NOTE**
This API is supported since API version 7 and deprecated since API version 9. Use [off('avoidAreaChange')](#offavoidareachange9) instead. > -> This API is deprecated since API version 9. Use [off('avoidAreaChange')](#offavoidareachange9) instead. +> **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1850,8 +2034,8 @@ Enables listening for changes to the area where the window cannot be displayed. **Example** ```js -windowClass.on('avoidAreaChange', (type, data) => { - console.info('Succeeded in enabling the listener for system avoid area changes. type:' + JSON.stringify(type) + 'Data: ' + JSON.stringify(data)); +windowClass.on('avoidAreaChange', (data) => { + console.info('Succeeded in enabling the listener for system avoid area changes. type:' + JSON.stringify(data.type) + ', area: ' + JSON.stringify(data.area)); }); ``` @@ -1925,7 +2109,8 @@ windowClass.off('keyboardHeightChange'); on(type: 'touchOutside', callback: Callback<void>): void Enables listening for click events outside this window. -This is a system API and cannot be called by third-party applications. + +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1949,7 +2134,8 @@ windowClass.on('touchOutside', () => { off(type: 'touchOutside', callback?: Callback<void>): void Disables listening for click events outside this window. -This is a system API and cannot be called by third-party applications. + +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1966,6 +2152,209 @@ This is a system API and cannot be called by third-party applications. windowClass.off('touchOutside'); ``` +### on('screenshot')9+ + +on(type: 'screenshot', callback: Callback<void>): void + +Subscribes to screenshot events. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Event type. The value is fixed at **'screenshot'**, indicating the screenshot event.| +| callback | Callback<void> | Yes | Callback invoked when a screenshot event occurs. | + +**Example** + +```js +windowClass.on('screenshot', () => { + console.info('screenshot happened'); +}); +``` + +### off('screenshot')9+ + +off(type: 'screenshot', callback?: Callback<void>): void + +Unsubscribes from screenshot events. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Event type. The value is fixed at **'screenshot'**, indicating the screenshot event.| +| callback | Callback<void> | No | Callback invoked when a screenshot event occurs.| + +**Example** + +```js +var callback = ()=>{ + console.info('screenshot happened'); +} +windowClass.on('screenshot', callback) +windowClass.off('screenshot', callback) + +// If multiple callbacks are enabled in on(), they will all be disabled. +windowClass.off('screenshot'); +``` + +### on('dialogTargetTouch')9+ + +on(type: 'dialogTargetTouch', callback: Callback<void>): void + +Subscribes to click events of the target window in the modal window mode. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Event type. The value is fixed at **'dialogTargetTouch'**, indicating the click event of the target window in the modal window mode.| +| callback | Callback<void>| Yes | Callback invoked when the click event occurs in the target window of the modal window mode.| + +**Example** + +```js +windowClass.on('dialogTargetTouch', () => { + console.info('touch dialog target'); +}); +``` + +### off('dialogTargetTouch')9+ + +off(type: 'dialogTargetTouch', callback?: Callback<void>): void + +Unsubscribes from click events of the target window in the modal window mode. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Event type. The value is fixed at **'dialogTargetTouch'**, indicating the click event of the target window in the modal window mode.| +| callback | Callback<void> | No | Callback invoked when the click event occurs in the target window of the modal window mode.| + +**Example** + +```js +windowClass.off('dialogTargetTouch'); +``` + +### bindDialogTarget9+ + +bindDialogTarget(token: rpc.RemoteObject, deathCallback: Callback<void>, callback: AsyncCallback<void>): void + +Binds the modal window to the target window, and adds a callback to listen for modal window destruction events. This API uses an asynchronous callback to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ------------------------- | ---- | -------------------- | +| token | [rpc.RemoteObject](js-apis-rpc.md#remoteobject) | Yes | Token of the target window.| +| deathCallback | Callback<void> | Yes | Callback used to listen for modal window destruction events.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + +```js +class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } +} +class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + } + addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + isObjectDead(): boolean { + return false; + } +} +let token = new TestRemoteObject("testObject"); +windowClass.bindDialogTarget(token, () => { + console.info('Dialog Window Need Destroy.'); +}, (err, data) => { + if (err.code) { + console.error('Failed to bind dialog target. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in binding dialog target. Data:' + JSON.stringify(data)); +}); +``` + +### bindDialogTarget9+ + +bindDialogTarget(token: rpc.RemoteObject, deathCallback: Callback<void>): Promise<void> + +Binds the modal window to the target window, and adds a callback to listen for modal window destruction events. This API uses a promise to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ------------------------- | ---- | -------------------- | +| token | [rpc.RemoteObject](js-apis-rpc.md#remoteobject) | Yes | Token of the target window.| +| deathCallback | Callback<void> | Yes | Callback used to listen for modal window destruction events.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```js +class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } +} +class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + } + addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + isObjectDead(): boolean { + return false; + } +} +let token = new TestRemoteObject("testObject"); +let promise = windowClass.bindDialogTarget(token, () => { + console.info('Dialog Window Need Destroy.'); +}); +promise.then((data)=> { + console.info('Succeeded in binding dialog target. Data:' + JSON.stringify(data)); +}).catch((err)=>{ + console.error('Failed to bind dialog target. Cause:' + JSON.stringify(err)); +}); +``` + ### isSupportWideGamut8+ isSupportWideGamut(callback: AsyncCallback<boolean>): void @@ -2138,7 +2527,7 @@ Sets the background color for this window. This API uses an asynchronous callbac | Name | Type | Mandatory| Description | | -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| color | string | Yes | Background color to set. The value is a hexadecimal color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| +| color | string | Yes | Background color to set. The value is a hexadecimal color and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** @@ -2166,7 +2555,7 @@ Sets the background color for this window. This API uses a promise to return the | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | -| color | string | Yes | Background color to set. The value is a hexadecimal color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| +| color | string | Yes | Background color to set. The value is a hexadecimal color and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| **Return value** @@ -2186,26 +2575,49 @@ promise.then((data)=> { }); ``` -### setBrightness +### setWakeUpScreen()9+ -setBrightness(brightness: number, callback: AsyncCallback<void>): void +setWakeUpScreen(wakeUp: boolean): void; -Sets the screen brightness for this window. This API uses an asynchronous callback to return the result. +Wakes up the screen. + +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core **Parameters** -| Name | Type | Mandatory| Description | -| ---------- | ------------------------- | ---- | ------------------------------------ | -| brightness | number | Yes | Brightness to set, which ranges from 0 to 1. The value `1` indicates the brightest.| -| callback | AsyncCallback<void> | Yes | Callback used to return the result. | +| Name | Type | Mandatory| Description | +| ---------------- | ------- | ---- | ---------------------------- | +| wakeUp | boolean | Yes | Whether to wake up the screen.| **Example** ```js -var brightness = 1; -windowClass.setBrightness(brightness, (err, data) => { +var wakeUp = true; +windowClass.setWakeUpScreen(wakeUp); +``` + +### setBrightness + +setBrightness(brightness: number, callback: AsyncCallback<void>): void + +Sets the screen brightness for this window. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------- | ---- | ------------------------------------ | +| brightness | number | Yes | Brightness to set, which ranges from 0 to 1. The value `1` indicates the brightest.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +var brightness = 1; +windowClass.setBrightness(brightness, (err, data) => { if (err.code) { console.error('Failed to set the brightness. Cause: ' + JSON.stringify(err)); return; @@ -2253,8 +2665,10 @@ setDimBehind(dimBehindValue: number, callback: AsyncCallback<void>): void Sets the dimness of the window that is not on top. This API uses an asynchronous callback to return the result. > **NOTE** -> -> This API is deprecated since API version 9. +> +> This API cannot be used. +> +> This API is supported since API version 7 and deprecated since API version 9. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2284,8 +2698,10 @@ setDimBehind(dimBehindValue: number): Promise<void> Sets the dimness of the window that is not on top. This API uses a promise to return the result. > **NOTE** -> -> This API is deprecated since API version 9. +> +> This API cannot be used. +> +> This API is supported since API version 7 and deprecated since API version 9. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2428,7 +2844,7 @@ let promise = windowClass.setKeepScreenOn(isKeepScreenOn); promise.then((data) => { console.info('Succeeded in setting the screen to be always on. Data: ' + JSON.stringify(data)); }).catch((err)=>{ - console.info('Failed to set the screen to be always on. Cause: ' + JSON.stringify(err)); + console.info('Failed to set the screen to be always on. Cause: ' + JSON.stringify(err)); }); ``` @@ -2439,8 +2855,10 @@ setOutsideTouchable(touchable: boolean, callback: AsyncCallback<void>): vo Sets whether the area outside the subwindow is touchable. This API uses an asynchronous callback to return the result. > **NOTE** -> -> This API is deprecated since API version 9. +> +> This API cannot be used. +> +> This API is supported since API version 7 and deprecated since API version 9. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2470,8 +2888,10 @@ setOutsideTouchable(touchable: boolean): Promise<void> Sets whether the area outside the subwindow is touchable. This API uses a promise to return the result. > **NOTE** -> -> This API is deprecated since API version 9. +> +> This API cannot be used. +> +> This API is supported since API version 7 and deprecated since API version 9. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2502,7 +2922,7 @@ promise.then((data)=> { setPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void -Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. +Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. When in privacy mode, the window content cannot be captured or recorded. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2531,7 +2951,7 @@ windowClass.setPrivacyMode(isPrivacyMode, (err, data) => { setPrivacyMode(isPrivacyMode: boolean): Promise<void> -Sets whether this window is in privacy mode. This API uses a promise to return the result. +Sets whether this window is in privacy mode. This API uses a promise to return the result. When in privacy mode, the window content cannot be captured or recorded. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2559,6 +2979,25 @@ promise.then((data)=> { }); ``` +### setSnapshotSkip9+ +setSnapshotSkip(isSkip: boolean): void + +Sets whether to ignore this window during screen capturing or recording. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------- | ------- | ---- | -------------------- | +| isSkip | boolean | Yes | Whether to ignore the window. The default value is `false`.
The value `true` means that the window is ignored, and `false` means the opposite.
| +```js +var isSkip = true; +windowClass.setSnapshotSkip(isSkip); +``` + ### setTouchable7+ setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void @@ -2626,7 +3065,7 @@ setForbidSplitMove(isForbidSplitMove: boolean, callback: AsyncCallback<void&g Sets whether this window is forbidden to move in split-screen mode. This API uses an asynchronous callback to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2657,7 +3096,7 @@ setForbidSplitMove(isForbidSplitMove: boolean): Promise<void> Sets whether this window is forbidden to move in split-screen mode. This API uses a promise to return the result. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2685,11 +3124,330 @@ promise.then((data)=> { }); ``` +### snapshot9+ + +snapshot(callback: AsyncCallback<image.PixelMap>): void + +Captures this window. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ------------------------- | ---- | -------------------- | +| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. | + +**Example** + +```js +windowClass.snapshot((err, data) => { + if (err.code) { + console.error('Failed to snapshot window. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); + data.release(); // Release the memory in time after the PixelMap is used. +}); +``` + +### snapshot9+ + +snapshot(): Promise<image.PixelMap> + +Captures this window. This API uses a promise to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return the window screenshot.| + +**Example** + +```js +let promise = windowClass.snapshot(); +promise.then((pixelMap)=> { + console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); + pixelMap.release(); // Release the memory in time after the PixelMap is used. +}).catch((err)=>{ + console.error('Failed to snapshot window. Cause:' + JSON.stringify(err)); +}); +``` + +### setBlur9+ + +setBlur(radius: number): void + +Blurs this window. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| radius | number | Yes | Radius of the blur. The value is greater than or equal to 0. The value `0` means that the blur is disabled for the window.| + +**Example** + +```js +windowClass.setBlur(4.0); +``` + +### setBackdropBlur9+ + +setBackdropBlur(radius: number): void + +Blurs the background of this window. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| radius | number | Yes | Radius of the blur. The value is greater than or equal to 0. The value `0` means that the blur is disabled for the background of the window.| + +**Example** + +```js +windowClass.setBackdropBlur(4.0); +``` + +### setBackdropBlurStyle9+ + +setBackdropBlurStyle(blurStyle: BlurStyle): void + +Sets the blur style for the background of this window. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | --------- | ---- | ---------------------- | +| blurStyle | [BlurStyle](#blurstyle9) | Yes | Blur style to set for the background of the window.| + +**Example** + +```js +windowClass.setBackdropBlurStyle(window.BlurType.THIN); +``` + +### setShadow9+ + +setShadow(radius: number, color?: string, offsetX?: number, offsetY?: number): void + +Sets the shadow for the window borders. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| radius | number | Yes | Radius of the blur for the borders. The value is greater than or equal to 0. The value `0` means that the shadow is disabled for the window borders.| +| color | string | No | Color of the shadow. The value is a hexadecimal color and is case insensitive, for example, `#00FF00` or `#FF00FF00`.| +| offsetX | number | No | Offset of the shadow along the x-axis, in pixels. | +| offsetY | number | No | Offset of the shadow along the y-axis, in pixels. | + +**Example** + +```js +windowClass.setShadow(4.0, '#FF00FF00', 2, 3); +``` + +### setCornerRadius9+ + +setCornerRadius(cornerRadius: number): void + +Sets the radius of the rounded corners for this window. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ------- | ---- | -------------------- | +| radius | number | Yes | Radius of the rounded corners. The value is greater than or equal to 0. The value `0` means that the window does not use rounded corners.| + +**Example** + +```js +windowClass.setCornerRadius(4.0); +``` + +### opacity9+ + +opacity(opacity: number): void + +Sets the opacity for this window. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------ | ---- | --------------------- | +| opacity | number | Yes | Opacity to set. The value ranges from 0.0 to 1.0.| + +**Example** + +```js +windowClass.opacity(0.5); +``` + +### scale9+ + +scale(scaleOptions: ScaleOptions): void + +Sets the scale parameters for this window. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ------------------------------ | ---- | ---------- | +| scaleOptions | [ScaleOptions](#scaleoptions9) | Yes | Scale parameters to set.| + +**Example** + +```js +var obj : window.ScaleOptions; +obj.x = 2.0; +obj.y = 1.0; +obj.pivotX = 0.5; +obj.pivotY = 0.5; +windowClass.scale(obj); +``` + +### rotate9+ + +rotate(rotateOptions: RotateOptions): void + +Sets the rotation parameters for this window. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------- | -------------------------------- | ---- | ---------- | +| rotateOptions | [RotateOptions](#rotateoptions9) | Yes | Rotation parameters to set.| + +**Example** + +```js +var obj : window.RotateOptions; +obj.x = 1.0; +obj.y = 1.0; +obj.z = 45.0; +obj.pivotX = 0.5; +obj.pivotY = 0.5; +windowClass.rotate(obj); +``` + +### translate9+ + +translate(translateOptions: TranslateOptions): void + +Sets the translation parameters for this window. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------------- | -------------------------------------- | ---- | ---------- | +| translateOptions | [TranslateOptions](#translateoptions9) | Yes | Translation parameters to set.| + +**Example** + +```js +var obj : window.TranslateOptions; +obj.x = 100.0; +obj.y = 0.0; +obj.z = 0.0; +windowClass.translate(obj); +``` + +### getTransitionController9+ + + getTransitionController(): TransitionController + +Obtains the transition animation controller. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Return value** + +| Type | Description | +| ---------------------------------------------- | ---------------- | +| [TransitionController](#transitioncontroller9) | Transition animation controller.| + +**Example** + +```js +let controller = windowClass.getTransitionController(); // Obtain the transition animation controller. +controller.animationForHidden = (context : window.TransitionContext) => { + let toWindow = context.toWindow + animateTo({ + duration: 1000, // Animation duration. + tempo: 0.5, // Playback speed. + curve: Curve.EaseInOut, // Animation curve. + delay: 0, // Animation delay. + iterations: 1, // Number of playback times. + playMode: PlayMode.Normal // Animation mode. + }, () => { + var obj : window.TranslateOptions; + obj.x = 100.0; + obj.y = 0.0; + obj.z = 0.0; + toWindow.translate(obj); // Set the transition animation. + console.info('toWindow translate end'); + } + ) + context.completeTransition(true) + console.info('complete transition end'); +} +windowClass.showWithAnimation((err, data) => { + if (err.code) { + console.error('Failed to show the window with animation. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in showing the window with animation. Data: ' + JSON.stringify(data)); +}) +``` + ## WindowStageEventType9+ Describes the lifecycle of a window stage. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2712,7 +3470,7 @@ getMainWindow(callback: AsyncCallback<Window>): void Obtains the main window of this window stage. This API uses an asynchronous callback to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2747,7 +3505,7 @@ getMainWindow(): Promise<Window> Obtains the main window of this window stage. This API uses a promise to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2781,7 +3539,7 @@ createSubWindow(name: string, callback: AsyncCallback<Window>): void Creates a subwindow for this window stage. This API uses an asynchronous callback to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2818,7 +3576,7 @@ createSubWindow(name: string): Promise<Window> Creates a subwindow for this window stage. This API uses a promise to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2858,7 +3616,7 @@ getSubWindow(callback: AsyncCallback<Array<Window>>): void Obtains all the subwindows of this window stage. This API uses an asynchronous callback to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2893,7 +3651,7 @@ getSubWindow(): Promise<Array<Window>> Obtains all the subwindows of this window stage. This API uses a promise to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2927,7 +3685,7 @@ loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void Loads content from a page associated with a local storage to the main window in this window stage. This API uses an asynchronous callback to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2936,7 +3694,7 @@ This API can be used only in the stage model. | Name | Type | Mandatory| Description | | -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | Yes | Path of the page from which the content will be loaded. | -| storage | LocalStorage | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| +| storage | [LocalStorage](../../ui/ui-ts-local-storage.md) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** @@ -2944,7 +3702,7 @@ This API can be used only in the stage model. ```ts import Ability from '@ohos.application.Ability'; class myAbility extends Ability { - storage : LocalStorage + storage : LocalStorage onWindowStageCreate(windowStage) { this.storage = new LocalStorage(); this.storage.setOrCreate("storageSimpleProp",121); @@ -2966,7 +3724,7 @@ loadContent(path: string, storage?: LocalStorage): Promise<void> Loads content from a page associated with a local storage to the main window in this window stage. This API uses a promise to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -2975,7 +3733,7 @@ This API can be used only in the stage model. | Name | Type | Mandatory| Description | | ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | Yes | Path of the page from which the content will be loaded. | -| storage | LocalStorage | No | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| +| storage | [LocalStorage](../../ui/ui-ts-local-storage.md) | No | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| **Return value** @@ -2988,7 +3746,7 @@ This API can be used only in the stage model. ```ts import Ability from '@ohos.application.Ability'; class myAbility extends Ability { - storage : LocalStorage + storage : LocalStorage onWindowStageCreate(windowStage) { this.storage = new LocalStorage(); this.storage.setOrCreate("storageSimpleProp",121); @@ -3011,7 +3769,7 @@ loadContent(path: string, callback: AsyncCallback<void>): void Loads content from a page to this window stage. This API uses an asynchronous callback to return the result. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -3046,7 +3804,7 @@ on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType> Enables listening for window stage lifecycle changes. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -3077,7 +3835,7 @@ off(eventType: 'windowStageEvent', callback?: Callback<WindowStageEventType&g Disables listening for window stage lifecycle changes. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -3106,9 +3864,9 @@ disableWindowDecor(): void Disables window decorators. -This type can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. -This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -3130,7 +3888,9 @@ setShowOnLockScreen(showOnLockScreen: boolean): void Sets whether to display the window of the application on the lock screen. -This API can be used only in the stage model. +**System API**: This is a system API. + +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -3151,3 +3911,145 @@ class myAbility extends Ability { } } ``` +## TransitionContext9+ + +Provides the context for the transition animation. + +**System API**: This is a system API. + +### toWindow9+ + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Readable| Writable| Description | +| -------- | ----------------- | ---- | ---- | ---------------- | +| toWindow | [Window](#window) | Yes | Yes | Target window to display the animation.| + +### completeTransition9+ + +completeTransition(isCompleted: boolean): void + +Completes the transition. This API must be called after [animateTo()](../arkui-ts/ts-explicit-animation.md) is executed. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ------- | ---- | ------------------------------------------------------------ | +| isCompleted | boolean | Yes | Whether the transition is complete. The value `true` means that the transition is complete, and `false` means the opposite.| + +**Example** + +```js +let controller = windowClass.getTransitionController(); +controller.animationForShown = (context : window.TransitionContext) => { + let toWindow = context.toWindow + animateTo({ + duration: 1000, // Animation duration. + tempo: 0.5, // Playback speed. + curve: Curve.EaseInOut, // Animation curve. + delay: 0, // Animation delay. + iterations: 1, // Number of playback times. + playMode: PlayMode.Normal // Animation mode. + }, () => { + var obj : window.TranslateOptions; + obj.x = 100.0; + obj.y = 0.0; + obj.z = 0.0; + toWindow.translate(obj); + console.info('toWindow translate end'); + } + ) + context.completeTransition(true) + console.info('complete transition end'); +} +``` + +## TransitionController9+ + +Implements the transition animation controller. + +**System API**: This is a system API. + +### animationForShown9+ + +animationForShown(context: TransitionContext): void + +Customizes the animation when the window is shown. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------------------------------- | ---- | -------------------- | +| context | [TransitionContext](#transitioncontext9) | Yes | Context of the transition animation.| + +**Example** + +```js +let controller = windowClass.getTransitionController(); +controller.animationForShown = (context : window.TransitionContext) => { + let toWindow = context.toWindow + animateTo({ + duration: 1000, // Animation duration. + tempo: 0.5, // Playback speed. + curve: Curve.EaseInOut, // Animation curve. + delay: 0, // Animation delay. + iterations: 1, // Number of playback times. + playMode: PlayMode.Normal // Animation mode. + }, () => { + var obj : window.TranslateOptions; + obj.x = 100.0; + obj.y = 0.0; + obj.z = 0.0; + toWindow.translate(obj); + console.info('toWindow translate end'); + } + ) + context.completeTransition(true) + console.info('complete transition end'); +} +``` + +### animationForHidden9+ + +animationForHidden(context: TransitionContext): void + +Customizes the animation when the window is hidden. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------------------------------- | ---- | -------------------- | +| context | [TransitionContext](#transitioncontext9) | Yes | Context of the transition animation.| + +**Example** + +```js +let controller = windowClass.getTransitionController(); +controller.animationForHidden = (context : window.TransitionContext) => { + let toWindow = context.toWindow + animateTo({ + duration: 1000, // Animation duration. + tempo: 0.5, // Playback speed. + curve: Curve.EaseInOut, // Animation curve. + delay: 0, // Animation delay. + iterations: 1, // Number of playback times. + playMode: PlayMode.Normal // Animation mode. + }, () => { + var obj : window.TranslateOptions; + obj.x = 100.0; + obj.y = 0.0; + obj.z = 0.0; + toWindow.translate(obj); + console.info('toWindow translate end'); + } + ) + context.completeTransition(true) + console.info('complete transition end'); +} +``` diff --git a/en/application-dev/reference/apis/js-apis-windowAnimationManager.md b/en/application-dev/reference/apis/js-apis-windowAnimationManager.md new file mode 100644 index 0000000000000000000000000000000000000000..a81bb5c76c64a092ea77afb14db231040adf77ac --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-windowAnimationManager.md @@ -0,0 +1,375 @@ +# Window Animation Management +The **WindowAnimationManager** module provides APIs to listen for application start/exit events and window minimization/maximization events and associate animations with these events. + +> **NOTE** +> +> This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version. +> +> The APIs provided by this module are system APIs. + +## Modules to Import + +```js +import windowAnimationManager from '@ohos.animation.windowAnimationManager' +``` + +## windowAnimationManager.setController + +setController(controller: WindowAnimationController): void + +Sets a window animation controller. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| controller | [WindowAnimationController](#windowanimationcontroller) | Yes| Window animation controller to set.| + +**Example** + +```js +var controller = { + onStartAppFromLauncher(startingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + console.log('onStartAppFromLauncher', startingWindowTarget); + }, + onStartAppFromRecent(startingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + console.log('onStartAppFromRecent', startingWindowTarget); + }, + onStartAppFromOther(startingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + console.log('onStartAppFromOther', startingWindowTarget); + }, + onAppTransition(fromWindowTarget: WindowAnimationTarget, toWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + }, + onMinimizeWindow(minimizingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + }, + onCloseWindow(closingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + }, + onScreenUnlock(finishCallback: WindowAnimationFinishedCallback): void { + } +} + +windowAnimationManager.setController(controller) +``` + +## windowAnimationManager.minimizeWindowWithAnimation + +minimizeWindowWithAnimation(windowTarget: WindowAnimationTarget, callback: AsyncCallback<WindowAnimationFinishedCallback>): void + +Minimizes the window that displays the animation. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| windowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes| Target window to minimize.| +| callback | AsyncCallback<[WindowAnimationFinishedCallback](#windowanimationfinishedcallback)> | Yes| Callback invoked when the animation is finished.| + +**Example** + +```js +var target: WindowAnimationTarget = undefined; +var controller = { + onWindowAnimationTargetsUpdate(fullScreenWindowTarget: WindowAnimationTarget, floatingWindowTargets: Array): void { + target = fullScreenWindowTarget; + }, +} + +windowAnimationManager.setController(controller) + +var finishedCallback = null; +windowAnimationManager.minimizeWindowWithAnimation(target, (err, data) => { + if (err.code) { + console.error('Failed to minimize the window target. Cause: ' + JSON.stringify(err)); + return; + } + + finishedCallback = data; +}); + +finishedCallback.onAnimationFinish(); +``` + +## windowAnimationManager.minimizeWindowWithAnimation + +minimizeWindowWithAnimation(windowTarget: WindowAnimationTarget): Promise<WindowAnimationFinishedCallback> + +Minimizes the window that displays the animation. This API uses a promise to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| windowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes| Target window to display the animation.| + +**Return value** + +| Type | Description | +| -------------------------------- | --------------------------------------- | +| Promise<[WindowAnimationFinishedCallback](#windowanimationfinishedcallback)> | Promise used to return a call when the animation is finished.| + + +**Example** + +```js +var target: WindowAnimationTarget = undefined; +var controller = { + onWindowAnimationTargetsUpdate(fullScreenWindowTarget: WindowAnimationTarget, floatingWindowTargets: Array): void { + target = fullScreenWindowTarget; + }, +} + +windowAnimationManager.setController(controller) + +let promise = windowAnimationManager.minimizeWindowWithAnimation(target); +promise.then((data) => { + data.onAnimationFinish(); +}).catch((err)=>{ + console.error('Failed to minimize the window target. Cause: ' + JSON.stringify(err)); + return; +}); +``` + +## WindowAnimationController + +Implements the window animation controller. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +### onStartAppFromLauncher + +onStartAppFromLauncher(startingWindowTarget: WindowAnimationTarget,finishCallback: WindowAnimationFinishedCallback): void + +Called when an application is started from the home screen. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Mandatory| Description | +| -------------------- | ------------------------------------------------------------ | ---- | ------------------ | +| startingWindowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes | Target window to display the animation. | +| finishCallback | [WindowAnimationFinishedCallback](#windowanimationfinishedcallback) | Yes | Callback invoked when the animation is finished.| + +**Example** + +```js +var controller = { + onStartAppFromLauncher(startingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + console.log('onStartAppFromLauncher', startingWindowTarget); + } +} +``` + +### onStartAppFromRecent + +onStartAppFromRecent(startingWindowTarget: WindowAnimationTarget,finishCallback:WindowAnimationFinishedCallback): void + +Called when an application is started from the recent task list. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Mandatory| Description | +| -------------------- | ------------------------------------------------------------ | ---- | ------------------ | +| startingWindowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes | Target window to display the animation. | +| finishCallback | [WindowAnimationFinishedCallback](#windowanimationfinishedcallback) | Yes | Callback invoked when the animation is finished.| + +**Example** + +```js +var controller = { + onStartAppFromRecent(startingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + console.log('onStartAppFromRecent', startingWindowTarget); + } +} +``` + +### onStartAppFromOther + +onStartAppFromOther(startingWindowTarget: WindowAnimationTarget,finishCallback: WindowAnimationFinishedCallback): void + +Called when an application is started from a place other than the home screen and recent task list. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Mandatory| Description | +| -------------------- | ------------------------------------------------------------ | ---- | ------------------ | +| startingWindowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes | Target window to display the animation. | +| finishCallback | [WindowAnimationFinishedCallback](#windowanimationfinishedcallback) | Yes | Callback invoked when the animation is finished.| + +**Example** + +```js +var controller = { + onStartAppFromOther(startingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + console.log('onStartAppFromOther', startingWindowTarget); + } +} +``` + +### onAppTransition + +onAppTransition(fromWindowTarget: WindowAnimationTarget, toWindowTarget: WindowAnimationTarget,finishCallback: WindowAnimationFinishedCallback): void + +Called during application transition. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Mandatory| Description | +| -------------------- | ------------------------------- | ---- | ---------------- | +| fromWindowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes | Window that displays the animation before the transition.| +| toWindowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes | Window that displays the animation after the transition.| +| finishCallback | [WindowAnimationFinishedCallback](#windowanimationfinishedcallback) | Yes | Callback invoked when the animation is finished.| + +**Example** + +```js +var controller = { + onAppTransition(fromWindowTarget: WindowAnimationTarget, toWindowTarget: WindowAnimationTarget, + finishCallback: WindowAnimationFinishedCallback): void { + console.log('onAppTransition', fromWindowTarget); + } +} +``` + +### onMinimizeWindow + +onMinimizeWindow(minimizingWindowTarget: WindowAnimationTarget,finishCallback: WindowAnimationFinishedCallback): void + +Called when a window is minimized. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Mandatory| Description | +| -------------------- | ------------------------------- | ---- | ---------------- | +| minimizingWindowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes | Target window to display the animation. | +| finishCallback | [WindowAnimationFinishedCallback](#windowanimationfinishedcallback) | Yes | Callback invoked when the animation is finished.| + +**Example** + +```js +var controller = { + onMinimizeWindow(minimizingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + console.log('onMinimizeWindow', minimizingWindowTarget); + } +} +``` + +### onCloseWindow + +onCloseWindow(closingWindowTarget: WindowAnimationTarget,finishCallback: WindowAnimationFinishedCallback): void + +Called when a window is closed. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Mandatory| Description | +| -------------------- | ------------------------------- | ---- | ---------------- | +| closingWindowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes | Target window to display the animation. | +| finishCallback | [WindowAnimationFinishedCallback](#windowanimationfinishedcallback) | Yes | Callback invoked when the animation is finished.| + +**Example** + +```js +var controller = { + onCloseWindow(closingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + console.log('onCloseWindow', closingWindowTarget); + } +} +``` + +### onScreenUnlock + +onScreenUnlock(finishCallback: [WindowAnimationFinishedCallback](#windowanimationfinishedcallback)): void + +Called when the screen is unlocked. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Mandatory| Description | +| -------------- | ------------------------------------------------------------ | ---- | ------------------ | +| finishCallback | [WindowAnimationFinishedCallback](#windowanimationfinishedcallback) | Yes | Callback invoked when the animation is finished.| + +**Example** + +```js +var controller = { + onScreenUnlock(finishCallback: WindowAnimationFinishedCallback): void { + console.log('onScreenUnlock'.); + } +} +``` + +### onWindowAnimationTargetsUpdate + +onWindowAnimationTargetsUpdate(fullScreenWindowTarget: WindowAnimationTarget, floatingWindowTargets: Array<WindowAnimationTarget>): void + +Called when the window that displays the animation is updated. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Mandatory| Description | +| -------------------- | ------------------------------- | ---- | ---------------- | +| fullScreenWindowTarget | [WindowAnimationTarget](#windowanimationtarget) | Yes | Target window in full-screen mode.| +| floatingWindowTargets| Array<[WindowAnimationTarget](#windowanimationtarget)> | Yes | Target window in the form of a floating window.| + +**Example** + +```js +var controller = { + onWindowAnimationTargetsUpdate(fullScreenWindowTarget: WindowAnimationTarget, floatingWindowTargets: Array): void { + console.log('onWindowAnimationTargetsUpdate'.); + } +} + +windowAnimationManager.setController(controller) +``` + +## WindowAnimationFinishedCallback +Implements a callback that is invoked when the animation is finished. + +### onAnimationFinish + +onAnimationFinish():void + +Called when the animation is finished. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Example** + +```js +var controller = { + onCloseWindow(closingWindowTarget: WindowAnimationTarget, finishCallback: WindowAnimationFinishedCallback): void { + finishCallback.onAnimationFinish(); + } +} +``` + +## WindowAnimationTarget +Implements animation in a window. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Description| +| ------- | ------ | ----------------------- | +| bundleName | string | Bundle name corresponding to the target window.| +| abilityName | string | Ability name corresponding to the target window.| +| windowBounds | [RRect](#rrect) | Actual size of the target window.| +| missionId | number | Mission ID.| + +## RRect +Describes a rounded rectangle. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Description| +| ------- | ------ | ----------------------- | +| left | number | Horizontal coordinate of the upper left corner of the target window relative to the screen.| +| top | number | Vertical coordinate of the upper left corner of the target window relative to the screen.| +| width | number | Width of the target window.| +| height | number | Height of the target window.| +| radius | number | Radius of the rounded corner of the target window.| diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001250678457.gif b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001250678457.gif index 6b44b6a2adc2528e13e95bc10d2a67874226a63b..96afd9a948c90e22cd52ab4c55218bf97591b3ec 100644 Binary files a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001250678457.gif and b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001250678457.gif differ diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-progress.md b/en/application-dev/reference/arkui-ts/ts-basic-components-progress.md index 83a445ec88d1520a60093d0f7264a3511209efd9..9310f9df68a9a7a7157bf0ebe736c2e458b65efb 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-progress.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-progress.md @@ -91,7 +91,11 @@ struct ProgressExample { Text('Capsule Progress').fontSize(9).fontColor(0xCCCCCC).width('90%') Row({ space: 40 }) { Progress({ value: 10, type: ProgressType.Capsule }).width(100).height(50) - Progress({ value: 20, total: 150, type: ProgressType.Capsule }).color(Color.Grey).value(50).width(100).height(50) + Progress({ value: 20, total: 150, type: ProgressType.Capsule }) + .color(Color.Grey) + .value(50) + .width(100) + .height(50) } }.width('100%').margin({ top: 30 }) } diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-richtext.md b/en/application-dev/reference/arkui-ts/ts-basic-components-richtext.md index 4cce2c69ff96f157f8087414f65a5255ecbefff3..163c61d33fad2f5159803c59a64348d405c3a71b 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-richtext.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-richtext.md @@ -49,7 +49,9 @@ RichText\(content:string\) ## Example -``` +You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer. +```ts +// xxx.ets @Entry @Component struct RichTextExample { diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-slider.md b/en/application-dev/reference/arkui-ts/ts-basic-components-slider.md index e9c4fbdf50f75cd15b0e8457631607c41ce305ab..1b8984dc496819fdb53d8409b2e3913e3dee38f3 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-slider.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-slider.md @@ -1,11 +1,12 @@ # Slider -> **NOTE**
+> **NOTE** +> > This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. -The **<Slider>** component is used to quickly adjust settings, such as the volume and brightness. +The *\** component is used to quickly adjust settings, such as the volume and brightness. ## Required Permissions @@ -15,7 +16,7 @@ None ## Child Components -None +Not supported ## APIs @@ -44,12 +45,12 @@ Slider(value:{value?: number, min?: number, max?: number, step?: number, style?: Touch target configuration is not supported. -| Name | Type | Default Value | Description | -| ------------- | ------- | ------------- | -------------------------------------------------------------------- | -| blockColor | Color | - | Color of the slider. | -| trackColor | Color | - | Background color of the slider. | -| selectedColor | Color | - | Color of the slider rail that has been slid. | -| showSteps | boolean | false | Whether to display the current step. | +| Name | Type | Default Value | Description | +| ------------- | ------- | ------------- | ---------------------------------------- | +| blockColor | Color | - | Color of the slider. | +| trackColor | Color | - | Background color of the slider. | +| selectedColor | Color | - | Color of the slider rail that has been slid. | +| showSteps | boolean | false | Whether to display the current step. | | showTips | boolean | false | Whether to display a bubble to indicate the percentage when sliding. | @@ -62,17 +63,18 @@ Among all the universal events, only **OnAppear** and **OnDisAppear** are suppor | onChange(callback: (value: number, mode: SliderChangeMode) => void) | Callback invoked when the slider slides.
**value**: current progress.
**mode**: dragging state. | - SliderChangeMode enums - | Name | Description | - | ------ | ----------------------------------- | - | Begin | The user starts to drag the slider. | - | Moving | The user is dragging the slider. | - | End | The user stops dragging the slider. | + | Name | Value | Description | + | ------ | ----- | ----------------------------------- | + | Begin | 0 | The user starts to drag the slider. | + | Moving | 1 | The user is dragging the slider. | + | End | 2 | The user stops dragging the slider. | ## Example -``` +```ts +// xxx.ets @Entry @Component struct SliderExample { diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md b/en/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md index 3a90aab90084be24746bba23aa9b224b15b2b99f..b1179b6a10eab9948e374082b8debcdb0d613017 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-xcomponent.md @@ -1,9 +1,10 @@ # XComponent - > **NOTE**
- > This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. + > **NOTE** + > + > This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. - The **\** can accept and display the EGL/OpenGLES and media data input. + The **\** can accept and display the EGL/OpenGL ES and media data input. ## Required Permissions @@ -19,20 +20,20 @@ - Name - | Name | Type | Mandatory | Description | - | ----------- | --------------------------------------- | --------- | ------------------------------------------------------------ | - | id | string | Yes | Unique ID of the component. The value can contain a maximum of 128 characters. | - | type | string | Yes | Type of the component. The options are as follows:
- **surface**: The content of this component is displayed individually, without being combined with that of other components.
- **component**: The content of this component is displayed after having been combined with that of other components. | - | libraryname | string | No | Name of the dynamic library generated after compilation at the application native layer. | - | controller | [XComponentController](#XComponentController) | No | Controller bound to the component, which can be used to invoke methods of the component. | + | Name | Type | Mandatory | Description | + | ----------- | ---------------------------------------- | ---- | ---------------------------------------- | + | id | string | Yes | Unique ID of the component. The value can contain a maximum of 128 characters. | + | type | string | Yes | Type of the component. The options are as follows:
-**surface**: The content of this component is displayed individually, without being combined with that of other components.
-**component**: The content of this component is displayed after having been combined with that of other components.| + | libraryname | string | No | Name of the dynamic library generated after compilation at the application native layer. | + | controller | [XComponentController](#XComponentController) | No | Controller bound to the component, which can be used to invoke methods of the component. | ## Events -| Name | Description | -| ------------------------------- | ------------------------ | -| onLoad(context?: object) => void | Triggered when the plug-in is loaded. | -| onDestroy() => void | Triggered when the plug-in is destroyed. | +| Name | Description | +| -------------------------------- | ------------ | +| onLoad(context?: object) => void | Triggered when the plug-in is loaded.| +| onDestroy() => void | Triggered when the plug-in is destroyed.| ## XComponentController @@ -52,9 +53,9 @@ Obtains the ID of the surface held by the **\**. The ID can be used - Return value - | Type | Description | - | ------ | --------------------------- | - | string | ID of the surface held by the **\**. | + | Type | Description | + | ------ | ----------------------- | + | string | ID of the surface held by the **\**.| ### setXComponentSurfaceSize @@ -64,10 +65,10 @@ Sets the width and height of the surface held by the **\**. - Parameters - | Name | Type | Mandatory | Default Value | Description | - | ------------- | -------- | ---- | ------ | ----------------------------- | - | surfaceWidth | number | Yes | - | Width of the surface held by the **\**. | - | surfaceHeight | number | Yes | - | Height of the surface held by the **\**. | + | Name | Type | Mandatory | Default Value | Description | + | ------------- | ------ | ---- | ---- | ----------------------- | + | surfaceWidth | number | Yes | - | Width of the surface held by the **\**.| + | surfaceHeight | number | Yes | - | Height of the surface held by the **\**.| ### getXComponentContext @@ -77,13 +78,15 @@ Obtains the context of an **\** object. - Return value - | Type | Description | - | ------ | ------------------------------------------------------------ | - | Object | Context of an **\** object. The APIs contained in the context are defined by developers. | + | Type | Description | + | ------ | ---------------------------------------- | + | Object | Context of an **\** object. The APIs contained in the context are defined by developers.| ## Example -Provide a surface-type **\** to support capabilities such as camera preview. +Provide a surface-type **\** to support capabilities such as camera preview. + +You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer. ```ts // xxx.ets diff --git a/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md b/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md index d625528c2c4f1cd857ae04585201d5507bb70ff8..2a985e49ea93a56b7425726c6a10ad60c3a4246a 100644 --- a/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md +++ b/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md @@ -1854,7 +1854,7 @@ Obtains the **[PixelMap](../apis/js-apis-image.md#pixelmap7)** object created wi getImageData(sx: number, sy: number, sw: number, sh: number): Object -Creates an **[ImageData](ts-components-canvas-imagebitmap.md)** object with pixels in the specified area on the canvas. +Obtains the **[ImageData](ts-components-canvas-imagebitmap.md)** object created with the pixels within the specified area on the canvas. - Parameters | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | --------- | ------------- | ---------------------------------------- | diff --git a/en/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md b/en/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md index 0f40b0ad1c4329d8e7feb4a9768d4d67c9dfcdfa..e90b0a729c4ae239724536c3ed67753f9ee59e1b 100644 --- a/en/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md +++ b/en/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md @@ -1,7 +1,8 @@ # CanvasGradient -> **NOTE**
+> **NOTE** +> > This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. @@ -17,12 +18,13 @@ Adds a color stop for the **CanvasGradient** object based on the specified offse - Parameters | Name | Type | Mandatory | Default Value | Description | | -------- | -------- | -------- | -------- | -------- | - | offset | number | Yes | 0 | Proportion of the distance between the color stop and the start point to the total length. The value ranges from 0 to 1. | - | color | string | Yes | 'ffffff' | Gradient color to set. | + | offset | number | Yes | 0 | Proportion of the distance between the color stop and the start point to the total length. The value ranges from 0 to 1. | + | color | string | Yes | '#ffffff'| Gradient color to set. | - Example - - ``` + + ```ts + // xxx.ets @Entry @Component struct Page45 { @@ -37,9 +39,9 @@ Adds a color stop for the **CanvasGradient** object based on the specified offse .backgroundColor('#ffff00') .onReady(() =>{ var grad = this.context.createLinearGradient(50,0, 300,100) - this.grad.addColorStop(0.0, 'red') - this.grad.addColorStop(0.5, 'white') - this.grad.addColorStop(1.0, 'green') + grad.addColorStop(0.0, 'red') + grad.addColorStop(0.5, 'white') + grad.addColorStop(1.0, 'green') this.context.fillStyle = grad this.context.fillRect(0, 0, 500, 500) }) diff --git a/en/application-dev/reference/arkui-ts/ts-container-scroll.md b/en/application-dev/reference/arkui-ts/ts-container-scroll.md index 7ea63acd602a3337054e46b96bec8535df58b614..e1b0dbad3176d1cd9b13e77768c7bb41d2c8b537 100644 --- a/en/application-dev/reference/arkui-ts/ts-container-scroll.md +++ b/en/application-dev/reference/arkui-ts/ts-container-scroll.md @@ -1,16 +1,16 @@ # Scroll +> **NOTE** +> - This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. +> - When a **\** is nested in this component, you are advised to specify the width and height of the **\** under scenarios where consistently high performance is required. If the width and height are not specified, this component will load all content of the **\**. -The **\** component scrolls the content when the layout size of a component exceeds the viewport of its parent component. -> **NOTE** -> -> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. +The **\** component scrolls the content when the layout size of a component exceeds the viewport of its parent component. ## Required Permissions -None +None. ## Child Components @@ -25,41 +25,39 @@ Scroll(scroller?: Scroller) ## Attributes -| Name | Type | Default Value | Description | -| -------- | -------- | -------- | -------- | -| scrollable | ScrollDirection | ScrollDirection.Vertical | Scroll method. | -| scrollBar | [BarState](ts-appendix-enums.md#barstate-enums) | ScrollDirection.Auto | Scrollbar status. | -| scrollBarColor | Color | - | Color of the scrollbar. | -| scrollBarWidth | Length | - | Width of the scrollbar. | +| Name | Type | Default Value | Description | +| -------------- | ---------------------------------------- | ------------------------ | --------- | +| scrollable | ScrollDirection | ScrollDirection.Vertical | Scroll method. | +| scrollBar | [BarState](ts-appendix-enums.md#barstate-enums)| ScrollDirection.Auto | Scrollbar status. | +| scrollBarColor | Color | - | Color of the scrollbar.| +| scrollBarWidth | Length | - | Width of the scrollbar.| -- ScrollDirection - | Name | Description | - | -------- | -------- | - | Horizontal | Only horizontal scrolling is supported. | - | Vertical | Only vertical scrolling is supported. | - | None | Scrolling is disabled. | +- ScrollDirection enums + | Name | Description | + | ---------- | ---------- | + | Horizontal | Only horizontal scrolling is supported.| + | Vertical | Only vertical scrolling is supported.| + | None | Scrolling is disabled. | ## Events -| Name | Description | -| -------- | -------- | -| onScrollBegin9+(dx: number, dy: number) => { dxRemain: number, dyRemain: number } | Called when scrolling starts.
Parameters
- **dx**: amount to scroll by in the horizontal direction.
- **dy**: amount to scroll by in the vertical direction.
Return value:
- **dxRemain**: remaining amount to scroll by in the horizontal direction.
- **dyRemain**: remaining amount to scroll by in the vertical direction.| -| onScroll(xOffset: number, yOffset: number) => void | Invoked when scrolling starts. It returns the horizontal and vertical offsets. | -| onScrollEdge(side: Edge) => void | Invoked when scrolling reaches the edge. | -| onScrollEnd() => void | Invoked when scrolling stops. | +| Name | Description | +| ---------------------------------------- | ----------------------------- | +| onScrollBegin9+(dx: number, dy: number) => { dxRemain: number, dyRemain: number } | Invoked when scrolling starts.
Parameters:
- **dx**: amount to scroll by in the horizontal direction.
- **dy**: amount to scroll by in the vertical direction.
Return value:
- **dxRemain**: remaining amount to scroll by in the horizontal direction.
- **dyRemain**: remaining amount to scroll by in the vertical direction.| +| onScroll(xOffset: number, yOffset: number) => void | Invoked to return the horizontal and vertical offsets during scrolling when the specified scroll event occurs.| +| onScrollEdge(side: Edge) => void | Invoked when scrolling reaches the edge. | +| onScrollEnd() => void | Invoked when scrolling stops. | > **NOTE** -> -> If the **onScrollBegin** event and **scrollBy** method are used to implement nested scrolling, you must set **edgeEffect** of the child scrolling node to **None**. For example, if the **\** component is nested with the **\** component, the **edgeEffect** attribute of the **\** component must be set to **EdgeEffect.None**. +> If the **onScrollBegin** event and **scrollBy** API are used to implement nested scrolling, you must set **edgeEffect** of the scrolling child node to **None**. For example, if a **\** is nested in the **\** component, the **edgeEffect** attribute of the **\** must be set to **EdgeEffect.None**. ## Scroller -Controller of the scrollable container component. You can bind this component to the container component and use it to control the scrolling of the container component. Currently, this component can be bound to the **\** and **\** components. +Controller of the scrollable container component. You can bind this component to a container component and use it to control the scrolling of that component. Currently, this component can be bound to the **\** and **\** components. ### Objects to Import - ``` scroller: Scroller = new Scroller() ``` @@ -74,11 +72,11 @@ Scrolls to the specified position. - Parameters - | Name | Type | Mandatory | Default Value | Description | - | -------- | -------- | -------- | -------- | -------- | - | xOffset | Length | Yes | - | Horizontal scrolling offset. | - | yOffset | Length | Yes | - | Vertical scrolling offset. | - | animation | {
duration: number,
curve: Curve \|
CubicBezier \|
SpringCurve
} | No | | Animation configuration, which includes the following:
- **duration**: scrolling duration.
- **curve**: scrolling curve. | + | Name | Type | Mandatory | Default Value | Description | + | --------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | + | xOffset | Length | Yes | - | Horizontal scrolling offset. | + | yOffset | Length | Yes | - | Vertical scrolling offset. | + | animation | {
duration: number,
curve: [Curve](ts-animatorproperty.md) \|
CubicBezier \|
SpringCurve
} | No | | Animation configuration, which includes the following:
- **duration**: scrolling duration.
- **curve**: scrolling curve.| ### scrollEdge @@ -90,10 +88,18 @@ Scrolls to the edge of the container. - Parameters - | Name | Type | Mandatory | Default Value | Description | - | -------- | -------- | -------- | -------- | -------- | - | value | Edge | Yes | - | Edge position to scroll to. | + | Name | Type| Mandatory | Default Value | Description | + | ----- | ---- | ---- | ---- | --------- | + | value | Edge | Yes | - | Edge position to scroll to.| + +- Edge enums + + | Name | Value | Description | + | ------ | ---- | ---------- | + | Top | 0 | Top edge.| + | Bottom | 2 | Bottom edge.| + ### scrollPage @@ -102,43 +108,42 @@ scrollPage(value: { next: boolean, direction?: Axis }): void Scrolls to the next or previous page. - Parameters - | Name | Type | Mandatory | Default Value | Description | - | -------- | -------- | -------- | -------- | -------- | - | next | boolean | Yes | - | Whether to turn to the next page. The value **true** means to scroll to the next page, and the value **false** means to scroll to the previous page. | + | Name | Type | Mandatory | Default Value | Description | + | --------- | ------- | ---- | ---- | ------------------------------ | + | next | boolean | Yes | - | Whether to turn to the next page. The value **true** means to scroll to the next page, and **false** means to scroll to the previous page.| | direction | Axis | No | - | Scrolling direction: horizontal or vertical. | ### currentOffset -scroller.currentOffset(): Object +currentOffset(): Object Obtains the scrolling offset. - Return value - | Type | Description | - | -------- | -------- | - | {
xOffset: number,
yOffset: number
} | **xOffset**: horizontal scrolling offset.
**yOffset**: vertical scrolling offset. | + | Type | Description | + | ------------------------------------------------------- | ------------------------------------------------------------ | + | {
xOffset: number,
yOffset: number
} | **xOffset**: horizontal scrolling offset.
**yOffset**: vertical scrolling offset. | -### scroller.scrollToIndex +### scrollToIndex -scroller.scrollToIndex(value: number): void +scrollToIndex(value: number): void -Scrolls to the specified index. +Scrolls to the item with the specified index. -> **NOTE** -> +> **NOTE** > Only the **\** component is supported. - Parameters - | Name | Type | Mandatory | Default Value | Description | - | -------- | -------- | -------- | -------- | -------- | - | value | number | Yes | - | Index of the item to be scrolled to in the list. | + | Name | Type | Mandatory | Default Value | Description | + | ----- | ------ | ---- | ---- | ----------------- | + | value | number | Yes | - | Index of the item to be scrolled to in the list.| ### scrollBy @@ -150,8 +155,7 @@ Scrolls by the specified amount. > **NOTE** -> -> Only the **\** component is supported. +> Only the **\** component is supported. - Parameters @@ -202,17 +206,17 @@ struct ScrollExample { }) Button('scroll 100') - .onClick(() => {// Click to scroll down 100.0. + .onClick(() => { // Click to scroll down 100.0. this.scroller.scrollTo({ xOffset: 0, yOffset: this.scroller.currentOffset().yOffset + 100 }) }) .margin({ top: 10, left: 20 }) Button('back top') - .onClick(() => {// Click to go back to the top. + .onClick(() => { // Click to go back to the top. this.scroller.scrollEdge(Edge.Top) }) .margin({ top: 60, left: 20 }) Button('next page') - .onClick(() => {// Click to scroll down to the bottom. + .onClick(() => { // Click to scroll down to the bottom. this.scroller.scrollPage({ next: true }) }) .margin({ top: 110, left: 20 }) @@ -222,6 +226,8 @@ struct ScrollExample { ``` ![en-us_image_0000001256978363](figures/en-us_image_0000001256978363.gif) + + ```ts @Entry @Component diff --git a/en/application-dev/reference/arkui-ts/ts-universal-attributes-z-order.md b/en/application-dev/reference/arkui-ts/ts-universal-attributes-z-order.md index c18d5a4e20ca5f48ab6d5ccf368d9936c174fe0d..847fd5b42f9ebe7358f25d0c3a21f859d9451f32 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-attributes-z-order.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-attributes-z-order.md @@ -1,7 +1,8 @@ # Z-order Control +The **zIndex** attribute sets the z-order of a component in the stacking context. -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> **NOTE** > This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. @@ -13,15 +14,16 @@ None ## Attributes - | Name | Type | Default Value | Description | +| Name | Type | Default Value | Description | | -------- | -------- | -------- | -------- | -| zIndex | number | 0 | Hierarchy of sibling components in a container. A larger z-order value indicates a higher display level. | +| zIndex | number | 0 | Hierarchy of sibling components in a container. A larger value indicates a higher display level. | ## Example - -``` + +```ts +// xxx.ets @Entry @Component struct ZIndexExample { @@ -38,7 +40,7 @@ struct ZIndexExample { Text('third child, zIndex(1)') .size({width: '70%', height: '50%'}).backgroundColor(0xc1cbac).align(Alignment.TopStart) .zIndex(1) - } + }.width('100%').height(200) }.width('100%').height(200) } } diff --git a/en/application-dev/security/accesstoken-overview.md b/en/application-dev/security/accesstoken-overview.md index 4537e67fa429ba019ae00074e2dc55c283b690e8..c09791fdd279df931ae82b35816b6afb82e98248 100644 --- a/en/application-dev/security/accesstoken-overview.md +++ b/en/application-dev/security/accesstoken-overview.md @@ -13,31 +13,7 @@ Without the required permissions, an app cannot access or perform operations on Currently, ATM verifies app permissions based on the token identity (Token ID). A token ID identifies an app. The ATM manages app permissions based on the app's token ID. -## Permission Workflow - -Determine the permissions required for an app to access data or perform an operation. Declare the required permissions in the app installation package. - -Determine whether the required permissions need to be authorized by users. If yes, provide a dialog box dynamically to request user authorization. - -After the user grants permissions to the app, the app can access the data or perform the operation. - -The figure below shows the permission workflow. - -![](figures/permission-workflow.png) - -1. Refer to the figure below for the process of applying for app permissions. - -![](figures/permission-application-process.png) - -1. For details about the mapping between the application Ability Privilege Level (APL) and permission level, see [Permission Levels](#permission-levels). - -2. The permission authorization modes include user_grant (permission granted by the user) and system_grant (permission granted by the system). For details, see [Permission Authorization Modes](#permission-authorization-mode). - -3. A low-level app can have a high-level permission by using the Access Control List (ACL). For details, see [ACL](#acl). - -## When to Use - -### Basic Principles +## Basic Principles for Permission Management Observe the following principles for permission management: @@ -49,23 +25,27 @@ Observe the following principles for permission management: - All the permissions granted to apps must come from the [Permission List](permission-list.md). Custom permissions are not allowed for apps currently. -### Scenarios +## Permission Workflow + +Determine the permissions required for an app to access data or perform an operation. Declare the required permissions in the app installation package. + +Determine whether the required permissions need to be authorized by users. If yes, provide a dialog box dynamically to request user authorization. -The following describes two common scenarios. +After the user grants permissions to the app, the app can access the data or perform the operation. -- **Video playback apps** +The figure below shows the permission workflow. - Video playback apps need to use multimedia functions and read and write media files stored on storage devices. Therefore, the apps must have at least the following permissions: +![](figures/permission-workflow.png) - * ohos.permission.READ_MEDIA (allowing the apps to read external media files) +1. You can refer to the figure below to determine whether an app can apply for a permission. - * ohos.permission.WRITE_MEDIA (allowing the apps to read and write external media files) +![](figures/permission-application-process.png) -- **Photography apps** +1. See [Permission Levels](#permission-levels) for details about the mapping between the application Ability Privilege Level (APL) and permission level. - Photography apps need to use the camera function. Before accessing the camera service, the apps must have the following permission: +2. The permission authorization modes include user_grant (permission granted by the user) and system_grant (permission granted by the system). For details, see [Permission Authorization Modes](#permission-authorization-mode). - ohos.permission.CAMERA (allowing the apps to use the camera to take photos and record videos) +3. A low-level app can have a high-level permission by using the Access Control List (ACL). For details, see [ACL](#acl). ## Permission Levels @@ -85,7 +65,28 @@ The table below describes the APLs. By default, apps are of the normal APL. -For the app of the system_basic or system_core APL, declare the app APL level in the **apl** field in the app's profile, and use the profile signing tool to generate a certificate when developing the app installation package. For details about the signing process, see [Hapsigner Guide](hapsigntool-guidelines.md). +For the app of the system_basic or system_core APL, declare the APL in the **apl** field of **bundle-info** in the app's profile when developing the application installation package. + +Then, use the [hapsigner](hapsigntool-overview.md) tool to generate a certificate or use DevEco Studio to [have your app automatically signed](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-auto-configuring-signature-information-0000001271659465#section161281722111). + +> **CAUTION**
The method of declaring the app's APL in its profile applies only to the application or service in debug phase. For a commercial app, apply for a release certificate and profile in the corresponding app market. + +The following is an example. + +This example shows only the modification of the **apl** field. Set other fields based on service requirements. For details about the fields in the profile, see [HarmonyAppProvision Configuration File](../quick-start/app-provision-structure.md). + +```json +{ + "bundle-info" : { + "developer-id": "OpenHarmony", + "development-certificate": "Base64 string", + "distribution-certificate": "Base64 string", + "bundle-name": "com.OpenHarmony.app.test", + "apl": "system_basic", + "app-feature": "hos_normal_app" + }, +} +``` ### Levels of Permissions @@ -101,7 +102,7 @@ The permissions open to apps vary with the permission level. The permission leve The system_basic permission allows access to resources related to basic operating system services. The basic services are basic functions provided or preconfigured by the system, such as system setting and identity authentication. Access to these resources may have considerable risks to user privacy and other apps. - The permissions of this level are available only to the apps of the system_basic APL. + The permissions of this level are available only to apps of the system_basic or system_core APL. - **system_core** @@ -177,8 +178,22 @@ If the permission required by an app has higher level than the app's APL, you ca In addition to the preceding [authorization processes](#authorization-processes), you must declare the ACL. -In other words, in addition to declaring the required permissions in the **config.json** file, you must declare the high-level permissions in the app's [profile](accesstoken-guidelines.md#declaring-the-acl). The subsequent steps of authorization are the same. +In other words, in addition to declaring the required permissions in the app's configuration file, you must [declare the ACL](accesstoken-guidelines.md#declaring-the-acl) in the app's profile. The subsequent steps of authorization are the same. + +**NOTICE** + +When developing an app installation package, you must declare the allowed ACLs in the **acls** field in the app's profile. Then, use the [hapsigner](hapsigntool-overview.md) tool to generate a certificate. + +> **CAUTION**
The method of declaring the app's APL in its profile applies only to the application or service in debug phase. For a commercial app, apply for a release certificate and profile in the corresponding app market. -**NOTE** +```json +{ + "acls": { + "allowed-acls": [ + "ohos.permission.PERMISSION" + ] + }, +} +``` -Declare the target ACL in the **acl** field of the app's profile in the app installation package, and generate a certificate using the profile signing tool. For details about the signing process, see [Hapsigner Guide](hapsigntool-guidelines.md). +For details about the fields in the profile, see [HarmonyAppProvision Configuration File](../quick-start/app-provision-structure.md). diff --git a/en/application-dev/task-management/background-task-dev-guide.md b/en/application-dev/task-management/background-task-dev-guide.md index e8d85cc571320bd7994e9e80a9b72e89acff367b..e820da263fb189ab9a2717c45a31a82d830a8cbc 100644 --- a/en/application-dev/task-management/background-task-dev-guide.md +++ b/en/application-dev/task-management/background-task-dev-guide.md @@ -10,11 +10,11 @@ If a service needs to be continued when the application or service module is run **Table 1** Main APIs for transient tasks -| API| Description| -| -------- | -------- | -| requestSuspendDelay(reason: string, callback: Callback<void>): [DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo) | Requests delayed suspension after the application switches to the background.
The default duration value of delayed suspension is 180000 when the battery level is normal and 60000 when the battery level is low.| -| getRemainingDelayTime(requestId: number): Promise<number> | Obtains the remaining duration before the application is suspended.
This API uses a promise to return the task execution result.| -| cancelSuspendDelay(requestId: number): void | Cancels the suspension delay.| +| API | Description | +| ---------------------------------------- | ---------------------------------------- | +| requestSuspendDelay(reason: string, callback: Callback<void>): [DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo) | Requests delayed suspension after the application switches to the background.
The default duration value of delayed suspension is 180000 when the battery level is normal and 60000 when the battery level is low.| +| getRemainingDelayTime(requestId: number): Promise<number> | Obtains the remaining duration before the application is suspended.
This API uses a promise to return the result. | +| cancelSuspendDelay(requestId: number): void | Cancels the suspension delay. | ### How to Develop @@ -24,12 +24,12 @@ If a service needs to be continued when the application or service module is run ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; - + let myReason = 'test requestSuspendDelay'; let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { console.info("Request suspension delay will time out."); }); - + var id = delayInfo.requestId; console.info("requestId is: " + id); ``` @@ -91,31 +91,33 @@ ohos.permission.KEEP_BACKGROUND_RUNNING **Table 2** Main APIs for continuous tasks -| API| Description| -| -------- | -------- | +| API | Description | +| ---------------------------------------- | ---------------------------- | | startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> | Requests a continuous task from the system so that the application keeps running in the background.| -| stopBackgroundRunning(context: Context): Promise<void> | Cancels the continuous task.| +| stopBackgroundRunning(context: Context): Promise<void> | Cancels the continuous task. | For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantAgent.md). **Table 3** Background modes -| Name| ID| Description| Item| -| -------- | -------- | -------- | -------- | -| DATA_TRANSFER | 1 | Data transfer.| dataTransfer | -| AUDIO_PLAYBACK | 2 | Audio playback.| audioPlayback | -| AUDIO_RECORDING | 3 | Audio recording.| audioRecording | -| LOCATION | 4 | Positioning and navigation.| location | -| BLUETOOTH_INTERACTION | 5 | Bluetooth-related task.| bluetoothInteraction | -| MULTI_DEVICE_CONNECTION | 6 | Multi-device connection.| multiDeviceConnection | -| WIFI_INTERACTION | 7 | WLAN-related task (reserved).| wifiInteraction | -| VOIP | 8 | Voice and video call (reserved).| voip | -| TASK_KEEPING | 9 | Computing task (for specific devices only).| taskKeeping | +| Name | ID | Description | Configuration Item | +| ----------------------- | ---- | -------------- | --------------------- | +| DATA_TRANSFER | 1 | Data transfer. | dataTransfer | +| AUDIO_PLAYBACK | 2 | Audio playback. | audioPlayback | +| AUDIO_RECORDING | 3 | Audio recording. | audioRecording | +| LOCATION | 4 | Positioning and navigation. | location | +| BLUETOOTH_INTERACTION | 5 | Bluetooth-related task. | bluetoothInteraction | +| MULTI_DEVICE_CONNECTION | 6 | Multi-device connection. | multiDeviceConnection | +| WIFI_INTERACTION | 7 | WLAN-related task (reserved). | wifiInteraction | +| VOIP | 8 | Voice and video call (reserved). | voip | +| TASK_KEEPING | 9 | Computing task (for specific devices only).| taskKeeping | ### How to Develop +Development on the FA model: + 1. Create an API version 8 project. Then right-click the project directory and choose **New > Ability > Service Ability** to create a Service ability. Configure the continuous task permission and background mode type in the **config.json** file, with the ability type set to **service**. ``` @@ -137,7 +139,7 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA ] } ``` - + 2. Request a continuous task. ```js @@ -173,16 +175,84 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA ```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); }); - + + ``` + +Development on the stage model: + +1. Create an API version 9 project. Then right-click the project directory and choose **New > Ability** to create an ability. Configure the continuous task permission and background mode type in the **module.json5** file. + + ``` + "module": { + "abilities": [ + { + "backgroundModes": [ + "dataTransfer", + "location" + ], // Background mode + } + ], + "requestPermissions": [ + { + "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // Continuous task permission + } + ] + } ``` +2. Request a continuous task. + + ```ts + import backgroundTaskManager from '@ohos.backgroundTaskManager'; + 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] + }; + + // Obtain the WantAgent object by using the getWantAgent API of the wantAgent module. + wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { + backgroundTaskManager.startBackgroundRunning(this.context, + backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { + console.info("Operation startBackgroundRunning succeeded"); + }).catch((err) => { + console.error("Operation startBackgroundRunning failed Cause: " + err); + }); + }); + ``` + +3. Cancel the continuous task. + + ```ts + import backgroundTaskManager from '@ohos.backgroundTaskManager'; + + backgroundTaskManager.stopBackgroundRunning(this.context).then(() => { + console.info("Operation stopBackgroundRunning succeeded"); + }).catch((err) => { + console.error("Operation stopBackgroundRunning failed Cause: " + err); + }); + + ``` + + ### Development Examples + +Development on the FA model: + For details about how to use the Service ability in the FA model, see [Service Ability Development](../ability/fa-serviceability.md). If an application does not need to interact with a continuous task in the background, you can use **startAbility()** to start the Service ability. In the **onStart** callback of the Service ability, call **startBackgroundRunning()** to declare that the Service ability needs to run in the background for a long time. After the task execution is complete, call **stopBackgroundRunning()** to release resources. @@ -284,3 +354,127 @@ export default { } }; ``` + +Development on the stage model: + +For details about the stage model, see [Stage Model Overview](../ability/stage-brief.md). +If an application needs to run a continuous task in the background, you can use **Call** to create and run an ability in the background. For details, see [Call Development](../ability/stage-call.md). + +```ts +import Ability from '@ohos.application.Ability' +import backgroundTaskManager from '@ohos.backgroundTaskManager'; +import wantAgent from '@ohos.wantAgent'; + +let mContext = null; + +function startContinuousTask() { + let wantAgentInfo = { + // List of operations to be executed after the notification is clicked. + wants: [ + { + bundleName: "com.example.myapplication", + abilityName: "com.example.myapplication.MainAbility" + } + ], + // Type of the operation to perform after the notification is clicked. + operationType: wantAgent.OperationType.START_ABILITY, + // Custom request code. + requestCode: 0, + // Execution attribute of the operation to perform after the notification is clicked. + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] + }; + + // Obtain the WantAgent object by using the getWantAgent API of the wantAgent module. + wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { + backgroundTaskManager.startBackgroundRunning(mContext, + backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { + console.info("Operation startBackgroundRunning succeeded"); + }).catch((err) => { + console.error("Operation startBackgroundRunning failed Cause: " + err); + }); + }); +} + +function stopContinuousTask() { + backgroundTaskManager.stopBackgroundRunning(mContext).then(() => { + console.info("Operation stopBackgroundRunning succeeded"); + }).catch((err) => { + console.error("Operation stopBackgroundRunning failed Cause: " + err); + }); +} + +class MySequenceable { + num: number = 0; + str: String = ""; + + constructor(num, string) { + this.num = num; + this.str = string; + } + + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + return true; + } + + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + return true; + } +} + +function sendMsgCallback(data) { + console.info('BgTaskAbility funcCallBack is called ' + data) + let receivedData = new Mysequenceable(0, "") + data.readSequenceable(receivedData) + console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`) + if (receivedData.str === 'start_bgtask') { + startContinuousTask() + } else if (receivedData.str === 'stop_bgtask') { + stopContinuousTask(); + } + return new Mysequenceable(10, "Callee test"); +} + +export default class BgTaskAbility extends Ability { + onCreate(want, launchParam) { + console.info("[Demo] BgTaskAbility onCreate") + this.callee.on("test", sendMsgCallback); + + try { + this.callee.on(MSG_SEND_METHOD, sendMsgCallback) + } catch (error) { + console.error(`${MSG_SEND_METHOD} register failed with error ${JSON.stringify(error)}`) + } + mContext = this.context; + } + + onDestroy() { + console.info("[Demo] BgTaskAbility onDestroy") + } + + onWindowStageCreate(windowStage) { + console.info("[Demo] BgTaskAbility onWindowStageCreate") + + windowStage.loadContent("pages/second").then((data)=> { + console.info(`load content succeed with data ${JSON.stringify(data)}`) + }).catch((error)=>{ + console.error(`load content failed with error ${JSON.stringify(error)}`) + }) + } + + onWindowStageDestroy() { + console.info("[Demo] BgTaskAbility onWindowStageDestroy") + } + + onForeground() { + console.info("[Demo] BgTaskAbility onForeground") + } + + onBackground() { + console.info("[Demo] BgTaskAbility onBackground") + } +}; +``` diff --git a/en/application-dev/ui/js-framework-syntax-css.md b/en/application-dev/ui/js-framework-syntax-css.md index 9669a0a3e97d78d01af0dfcac4f250f8e0a2f49d..9aa80d0bfac3822c57ac1fc3f1ba6c373292ddde 100644 --- a/en/application-dev/ui/js-framework-syntax-css.md +++ b/en/application-dev/ui/js-framework-syntax-css.md @@ -1,15 +1,15 @@ # CSS -Cascading Style Sheets (CSS) is a language used to describe the HML page structure. All HML components have default styles. You can customize styles for these components using CSS to design various pages. +Cascading Style Sheets (CSS) is a language used to describe the HML page structure. All HML components have default styles. You can customize styles for these components using CSS to design various pages. For details, see [Universal Styles](../reference/arkui-js/js-components-common-styles.md). ## Size Unit -1. Logical px set by <length>: - 1. The default logical screen width is 720 px (for details, see the "window" section in [config.json](js-framework-js-tag.md)). Your page will be scaled to fit the actual width of the screen. For example, on a screen with the actual width of 1440 physical px, 100 px is displayed on 200 physical px, with all sizes doubled from 720 px to 1440 px. - 2. If you set autoDesignWidth to true (for details, see the "window" section in [config.json](js-framework-js-tag.md)), the logical px are scaled based on the screen density. For example, if the screen density is 3x, 100 px will be rendered on 300 physical px. This approach is recommended when your application needs to adapt to multiple devices. +- Logical px set by \: + - The default logical screen width is 720 px (for details, see the "window" section in [config.json](js-framework-js-tag.md)). Your page will be scaled to fit the actual width of the screen. For example, on a screen with the actual width of 1440 physical px, 100 px is displayed on 200 physical px, with all sizes doubled from 720 px to 1440 px. + - If you set autoDesignWidth to true (for details, see the "window" section in [config.json](js-framework-js-tag.md)), the logical px are scaled based on the screen density. For example, if the screen density is 3x, 100 px will be rendered on 300 physical px. This approach is recommended when your application needs to adapt to multiple devices. -2. Percentage set by <percentage>: The component size is represented by its percentage of the parent component size. For example, if the width <percentage> of a component is set to 50%, the width of the component is half of its parent component's width. +- Percentage set by <percentage>: The component size is represented by its percentage of the parent component size. For example, if the width <percentage> of a component is set to 50%, the width of the component is half of its parent component's width. ## Style Import @@ -23,7 +23,7 @@ The .css file with the same name as the .hml file in each page directory describ 1. Internal style: The style and class attributes can be used to specify the component style. Example: - ``` + ```html
Hello World @@ -31,7 +31,7 @@ The .css file with the same name as the .hml file in each page directory describ ``` - ``` + ```css /* index.css */ .container { justify-content: center; @@ -40,7 +40,7 @@ The .css file with the same name as the .hml file in each page directory describ 2. External style files: You need to import the files. For example, create a style.css file in the common directory and import the file at the beginning of index.css. - ``` + ```css /* style.css */ .title { font-size: 50px; @@ -48,7 +48,7 @@ The .css file with the same name as the .hml file in each page directory describ ``` - ``` + ```css /* index.css */ @import '../../common/style.css'; .container { @@ -67,12 +67,12 @@ A CSS selector is used to select elements for which styles need to be added to. | \#id | \#titleId | Selects all components whose id is titleId. | | tag | text | Selects all <text> components. | | , | .title, .content | Selects all components whose class is title or content. | -| \#id .class tag | \#containerId .content text | Selects all grandchild <text> components whose grandparent components are identified as containerId and whose parent components are of the content class. To select child components, use > to replace the space between \#id and .class, for example, \#containerId>.content. | +| \#id .class tag | \#containerId .content text | Selects all grandchild **\** components whose grandparent components are identified as containerId and whose parent components are of the content class. To select child components, use > to replace the space between **\#id** and **.class**, for example, **\#containerId>.content**. | The following is an example: -``` +```html
Title @@ -83,9 +83,9 @@ The following is an example: ``` -``` +```css /* Page style xxx.css */ -/* Set the style for all
components. */ +/\* Set the style for all
components. \*/ div { flex-direction: column; } @@ -101,15 +101,13 @@ div { .title, .content { padding: 5px; } -/* Set the style for all texts of components whose class is container. - */ +/\* Set the style for all texts of components whose class is container.\*/ .container text { - color: #007dff; + color: \#007dff; } -/* Set the style for direct descendant texts of components whose class is container. -*/ -.container > text { - color: #fa2a2d; +/\* Set the style for direct descendant texts of components whose class is container.\*/ +.container > text { + color: \#fa2a2d; } ``` @@ -132,44 +130,44 @@ A CSS pseudo-class is a keyword added to a selector that specifies a special sta In addition to a single pseudo-class, a combination of pseudo-classes is supported. For example, :focus:checked selects the element whose focus and checked attributes are both set to true. The following table lists the supported single pseudo-class in descending order of priority. - | Pseudo-class | Available Components | Description | + +| Pseudo-class | Available Components | Description | | -------- | -------- | -------- | -| :disabled | Components that support the disabled attribute | Selects the element whose disabled attribute is changed to true (unavailable for animation attributes). | -| :focus | Components that support the focusable attribute | Selects the element that takes focus (unavailable for animation attributes). | -| :active | Components that support the click event
| Selects the element activated by a user. For example, a pressed button or a selected tab-bar (unavailable for animation attributes). | -| :waiting | button | Selects the element whose waiting attribute is true (unavailable for animation attributes). | +| :disabled | Components that support the disabled attribute | Selects the element whose disabled attribute is changed to true (unavailable for animation attributes). | +| :focus | Components that support the focusable attribute | Selects the element that takes focus (unavailable for animation attributes). | +| :active | Components that support the click event | Selects the element activated by a user. For example, a pressed button or a selected tab-bar (unavailable for animation attributes). | +| :waiting | button | Selects the element whose waiting attribute is true (unavailable for animation attributes). | | :checked | input[type="checkbox", type="radio"], and switch | Selects the element whose checked attribute is true (unavailable for animation attributes). | -| :hover6+ | Components that support the mouseover event | Selects the element that the cursor is on. | -The following is an example for you to use the :active pseudo-class to control the style when a user presses the button. +The following is an example for you to use the **:active** pseudo-class to control the style when a user presses the button. -``` +```html
``` - -``` +```css /* index.css */ .button:active { background-color: #888888;/* After the button is activated, the background color is changed to #888888. */ } ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
-> Pseudo-classes are not supported for the component and its child components, including , , ,
``` - - + + ```css /* xxx.css */ .container { @@ -356,6 +355,6 @@ weights: 4, 2, 1; } ``` -**4*4卡片** + **4*4卡片** ![gauge](figures/gauge.PNG) diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-clock.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-clock.md index cdf548653480d3cd219c7be37b9b4e14f00a6cf8..0d9a0cec0d088e7da90e5a2e025a6107a93a912e 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-clock.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-clock.md @@ -16,28 +16,28 @@ 除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性： -| 名称 | 类型 | 默认值 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| clockconfig | ClockConfig | - | 是 | Clock的图片资源和样式设置，包括日间时段（6:00-18:00）和夜间时段（18:00-次日6:00）两套资源和样式设置。
其中每套资源和样式包括表盘资源、时针指针资源、分针指针资源、秒针指针资源四张图和相应时间段的表盘数字颜色。
日间资源为必填项。夜间资源可不填，不填时默认会复用日间资源用作夜间时段的显示。
仅支持动态更新整个Object，不支持动态更新Object里的内容。
建议使用PNG资源作为Clock组件的图片资源。
不支持使用SVG资源作为Clock组件的图片资源。 | -| showdigit | boolean | true | 否 | 是否由Clock组件绘制表盘数字。
该属性为true时，请留意clockconfig中digitRadiusRatio和digitSizeRatio参数与表盘的匹配情况。
由Clock组件绘制的表盘数字支持国际化。 | -| hourswest | number | - | 否 | 时钟的时区偏移值，时区为标准时区减去hourswest。
有效范围为[-12, 12]，其中负值范围表示东时区，比如东八区对应的是-8。不设置默认采用系统时间所在的时区。 | +| 名称 | 类型 | 默认值 | 必填 | 描述 | +| ----------- | ----------- | ---- | ---- | ---------------------------------------- | +| clockconfig | ClockConfig | - | 是 | Clock的图片资源和样式设置，包括日间时段（6:00-18:00）和夜间时段（18:00-次日6:00）两套资源和样式设置。
其中每套资源和样式包括表盘资源、时针指针资源、分针指针资源、秒针指针资源四张图和相应时间段的表盘数字颜色。
日间资源为必填项。夜间资源可不填，不填时默认会复用日间资源用作夜间时段的显示。
仅支持动态更新整个Object，不支持动态更新Object里的内容。
建议使用PNG资源作为Clock组件的图片资源。
不支持使用SVG资源作为Clock组件的图片资源。 | +| showdigit | boolean | true | 否 | 是否由Clock组件绘制表盘数字。
该属性为true时，请留意clockconfig中digitRadiusRatio和digitSizeRatio参数与表盘的匹配情况。
由Clock组件绘制的表盘数字支持国际化。 | +| hourswest | number | - | 否 | 时钟的时区偏移值，时区为标准时区减去hourswest。
有效范围为[-12, 12]，其中负值范围表示东时区，比如东八区对应的是-8。不设置默认采用系统时间所在的时区。 | **表1** ClockConfig -| 名称 | 类型 | 默认值 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| face | <string> | - | 是 | 日间时段的表盘资源路径。
表盘资源须为包含时钟刻度的正方形图片，表盘区域（圆形）为该图片的内切圆或内切圆的同心圆。如果表盘区域为表盘资源内切圆的同心圆的话，请相应调整digitRadiusRatio和digitSizeRatio参数。 | -| hourHand | <string> | - | 是 | 日间时段的时针资源路径。
- 时针图片的高度须与表盘资源高度相同。
- 时针图片的宽高比建议在0.062。
- 时针图片上指针的旋转中心须处于时针图片的中心（对角线交点）。
- 夜间时段的时针资源请调整hourHandNight参数。 | -| minuteHand | <string> | - | 是 | 日间时段的分针资源路径。
- 分针图片的高度须与表盘资源高度相同。
- 分针图片的宽高比建议在0.062。
- 分针图片上指针的旋转中心须处于分针图片的中心（对角线交点）。
- 夜间时段的分针资源请调整minuteHandNight参数。 | -| secondHand | <string> | - | 是 | 日间时段的秒针资源路径。
-  秒针图片的高度须与表盘资源高度相同。
- 秒针图片的宽高比建议在0.062。
- 秒针图片上指针的旋转中心须处于秒针图片的中心（对角线交点）。
- 夜间时段的秒针资源请调整secondHandNightSrc参数。 | -| digitColor | <color> | \#FF000000 | 否 | 日间时段（6:00-18:00）的表盘文本颜色。 | -| digitColorNight | <color> | 与digitColor保持一致 | 否 | 夜间时段（18:00-次日6:00）的表盘文本颜色。
- 该属性未设置时，取digitColor的值作为digitColorNight的值（digitColor被设置时，取digitColor被设置的值）。
- 请注意缺省状态下使用digitClor的值作为digitColorNight的值时，夜间时段表盘文本颜色与夜间时段表盘背景（faceNight）的颜色配合问题。 | -| faceNight | <string> | - | 否 | 夜间时段的表盘资源路径。
未设置时使用face的资源路径作为夜间时段的表盘资源路径。 | -| hourHandNight | <string> | - | 否 | 夜间时段的时针资源路径。
未设置时使用hourHand的资源路径作为夜间时段的时针资源路径。 | -| minuteHandNight | <string> | - | 否 | 夜间时段的分针资源路径。
设置时使用minuteHand的资源路径作为夜间时段的分针资源路径。 | -| secondHandNight | <string> | - | 否 | 夜间时段的秒针资源路径。
未设置时使用secondHand的资源路径作为夜间时段的秒针资源路径。 | -| digitRadiusRatio | number | 0.7 | 否 | 表盘数字中心到表盘中心距离 / 表盘资源边长的一半。
- 有效范围为(0, 1]。
- 该参数用于计算表盘数字在表盘上距离圆心的位置。
- 该参数可以保证同一套表盘资源在不同组件尺寸下都有同样的相对位置，而不需要针对每个组件尺寸都重新调整数字位置。
- 该参数设为1时数字会有部分区域超出表盘，建议结合表盘区域合理设置digitRadiusRatio。 | -| digitSizeRatio | number | 0.08 | 否 | 表盘数字尺寸/表盘资源边长。
- 有效范围为(0, 0.142]。
- 该参数用于计算表盘数字相对表盘尺寸的大小。
- 该参数可以保证同一套表盘资源在不同组件尺寸下都有同样的相对大小，而不需要针对每个组件尺寸都重新调整字号。 | +| 名称 | 类型 | 默认值 | 必填 | 描述 | +| ---------------- | -------------- | --------------- | ---- | ---------------------------------------- | +| face | <string> | - | 是 | 日间时段的表盘资源路径。
表盘资源须为包含时钟刻度的正方形图片，表盘区域（圆形）为该图片的内切圆或内切圆的同心圆。如果表盘区域为表盘资源内切圆的同心圆的话，请相应调整digitRadiusRatio和digitSizeRatio参数。 | +| hourHand | <string> | - | 是 | 日间时段的时针资源路径。
- 时针图片的高度须与表盘资源高度相同。
- 时针图片的宽高比建议在0.062。
- 时针图片上指针的旋转中心须处于时针图片的中心（对角线交点）。
- 夜间时段的时针资源请调整hourHandNight参数。 | +| minuteHand | <string> | - | 是 | 日间时段的分针资源路径。
- 分针图片的高度须与表盘资源高度相同。
- 分针图片的宽高比建议在0.062。
- 分针图片上指针的旋转中心须处于分针图片的中心（对角线交点）。
- 夜间时段的分针资源请调整minuteHandNight参数。 | +| secondHand | <string> | - | 是 | 日间时段的秒针资源路径。
-  秒针图片的高度须与表盘资源高度相同。
- 秒针图片的宽高比建议在0.062。
- 秒针图片上指针的旋转中心须处于秒针图片的中心（对角线交点）。
- 夜间时段的秒针资源请调整secondHandNightSrc参数。 | +| digitColor | <color> | \#FF000000 | 否 | 日间时段（6:00-18:00）的表盘文本颜色。 | +| digitColorNight | <color> | 与digitColor保持一致 | 否 | 夜间时段（18:00-次日6:00）的表盘文本颜色。
- 该属性未设置时，取digitColor的值作为digitColorNight的值（digitColor被设置时，取digitColor被设置的值）。
- 请注意缺省状态下使用digitClor的值作为digitColorNight的值时，夜间时段表盘文本颜色与夜间时段表盘背景（faceNight）的颜色配合问题。 | +| faceNight | <string> | - | 否 | 夜间时段的表盘资源路径。
未设置时使用face的资源路径作为夜间时段的表盘资源路径。 | +| hourHandNight | <string> | - | 否 | 夜间时段的时针资源路径。
未设置时使用hourHand的资源路径作为夜间时段的时针资源路径。 | +| minuteHandNight | <string> | - | 否 | 夜间时段的分针资源路径。
设置时使用minuteHand的资源路径作为夜间时段的分针资源路径。 | +| secondHandNight | <string> | - | 否 | 夜间时段的秒针资源路径。
未设置时使用secondHand的资源路径作为夜间时段的秒针资源路径。 | +| digitRadiusRatio | number | 0.7 | 否 | 表盘数字中心到表盘中心距离 / 表盘资源边长的一半。
- 有效范围为(0, 1]。
- 该参数用于计算表盘数字在表盘上距离圆心的位置。
- 该参数可以保证同一套表盘资源在不同组件尺寸下都有同样的相对位置，而不需要针对每个组件尺寸都重新调整数字位置。
- 该参数设为1时数字会有部分区域超出表盘，建议结合表盘区域合理设置digitRadiusRatio。 | +| digitSizeRatio | number | 0.08 | 否 | 表盘数字尺寸/表盘资源边长。
- 有效范围为(0, 0.142]。
- 该参数用于计算表盘数字相对表盘尺寸的大小。
- 该参数可以保证同一套表盘资源在不同组件尺寸下都有同样的相对大小，而不需要针对每个组件尺寸都重新调整字号。 | ![clock](figures/clock.png) @@ -46,19 +46,19 @@ 除支持[通用样式](js-service-widget-common-styles.md)之外，还支持如下样式： -| 名称 | 类型 | 默认值 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| font-family | <string> | sans-serif | 否 | 表盘数字的字体列表，用逗号分隔，每个字体用字体名或者字体族名设置。列表中第一个系统中存在的或者通过2.1.6 自定义字体样式指定的字体，会被选中作为文本的字体。 | +| 名称 | 类型 | 默认值 | 必填 | 描述 | +| ----------- | -------------- | ---------- | ---- | ---------------------------------------- | +| font-family | <string> | sans-serif | 否 | 表盘数字的字体列表，用逗号分隔，每个字体用字体名或者字体族名设置。列表中第一个系统中存在的或者通过2.1.6 自定义字体样式指定的字体，会被选中作为文本的字体。 | > **说明：** > -> clock组件会保持显示区域的宽高比为1，最终正方形显示区域的边长为min(width, height)，在width \* height的组件区域中居中显示。 +> clock组件会保持显示区域的宽高比为1，最终正方形显示区域的边长为min(width, height)，在width \* height的组件区域中居中显示。 ## 事件 -| 名称 | 参数 | 描述 | -| -------- | -------- | -------- | +| 名称 | 参数 | 描述 | +| ---- | ------------------- | --------- | | hour | {hour: number} | 每个整点触发该事件 | @@ -101,7 +101,6 @@ ```json -// xxx.json { "data": { "clockconfig": { diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-input.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-input.md index 7c007fc11083395de42273d3c26fd7f3b9b7be0d..b00211058a23dbeeb9068eac9ce5ad81fd1864aa 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-input.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-basic-input.md @@ -11,12 +11,12 @@ 除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性： -| 名称 | 类型 | 默认值 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| type | string | radio | 是 | input组件类型，当前仅支持radio类型：
- "radio"：定义单选按钮，允许在多个拥有相同name值的选项中选中其中一个； | -| checked | boolean | false | 否 | 当前组件是否选中。 | -| name | string | - | 否 | input组件的名称。 | -| value | string | - | 否 | input组件的value值，类型为radio时必填且相同name值的选项该值唯一。 | +| 名称 | 类型 | 默认值 | 必填 | 描述 | +| ------- | ------- | ----- | ---- | ---------------------------------------- | +| type | string | radio | 是 | input组件类型，当前仅支持radio类型：
- "radio"：定义单选按钮，允许在多个拥有相同name值的选项中选中其中一个； | +| checked | boolean | false | 否 | 当前组件是否选中。 | +| name | string | - | 否 | input组件的名称。 | +| value | string | - | 否 | input组件的value值，类型为radio时必填且相同name值的选项该值唯一。 | ## 样式 @@ -26,10 +26,10 @@ ## 事件 -| 名称 | 参数 | 描述 | -| -------- | -------- | -------- | +| 名称 | 参数 | 描述 | +| ------ | ------------------ | ---------------------------------------- | | change | $event.checkedItem | radio单选框的checked状态发生变化时触发该事件，返回选中的组件value值。 | -| click | - | 点击动作触发该事件。 | +| click | - | 点击动作触发该事件。 | ## 示例 @@ -57,7 +57,6 @@ ```json -// xxx.json { "actions": { "onRadioChange":{ diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-gradient.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-gradient.md index 09c9dd4160f9ac5dedf8849f71e68535f9b5db0c..66c7d73703a3ed5afdb4cffe5ab27bd49e8db131 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-gradient.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-common-gradient.md @@ -4,7 +4,7 @@ > **说明：** > ->从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 开发框架支持线性渐变 (linear-gradient)和重复线性渐变 (repeating-linear-gradient)两种渐变效果。 @@ -22,7 +22,7 @@ - angle：进行角度渐变。 - + ```css background: linear-gradient(direction/angle, color, color, ...); background: repeating-linear-gradient(direction/angle, color, color, ...); @@ -35,16 +35,16 @@ background: repeating-linear-gradient(direction/angle, color, color, ...); - 参数 - | 名称 | 类型 | 默认值 | 必填 | 描述 | - | -------- | -------- | -------- | -------- | -------- | - | direction | to <side-or-corner>  <side-or-corner> = [left \| right] \|\| [top \| bottom] | to bottom (由上到下渐变) | 否 | 指定过渡方向，如：to left (从右向左渐变)  ，或者to bottom right (从左上角到右下角)。 | - | angle | <deg> | 180deg | 否 | 指定过渡方向，以元素几何中心为坐标原点，水平方向为X轴，angle指定了渐变线与Y轴的夹角(顺时针方向)。 | - | color | <color> [<length>\|<percentage>] | - | 是 | 定义使用渐变样式区域内颜色的渐变效果。 | + | 名称 | 类型 | 默认值 | 必填 | 描述 | + | --------- | ---------------------------------------- | ---------------------------- | ---- | ---------------------------------------- | + | direction | to <side-or-corner>  <side-or-corner> = [left \| right] \|\| [top \| bottom] | to bottom (由上到下渐变) | 否 | 指定过渡方向，如：to left (从右向左渐变)  ，或者to bottom right (从左上角到右下角)。 | + | angle | <deg> | 180deg | 否 | 指定过渡方向，以元素几何中心为坐标原点，水平方向为X轴，angle指定了渐变线与Y轴的夹角(顺时针方向)。 | + | color | <color> [<length>\|<percentage>] | - | 是 | 定义使用渐变样式区域内颜色的渐变效果。 | - 示例 1. 默认渐变方向为从上向下渐变。 - + ```css #gradient { height: 300px; @@ -52,27 +52,27 @@ background: repeating-linear-gradient(direction/angle, color, color, ...); /* 从顶部开始向底部由红色向绿色渐变 */ background: linear-gradient(red, #00ff00); } - ``` + ``` ![111](figures/111.PNG) 2. 45度夹角渐变。 - - + + ```css /* 45度夹角，从红色渐变到绿色 */ - background: linear-gradient(45deg, rgb(255,0,0),rgb(0, 255, 0)); + background: linear-gradient(45deg, rgb(255,0,0),rgb(0, 255, 0)); ``` ![222](figures/222.PNG) 3. 设置方向从左向右渐变。 - + ```css /* 从左向右渐变，在距离左边90px和距离左边360px (600*0.6) 之间270px宽度形成渐变 */ background: linear-gradient(to right, rgb(255,0,0) 90px, rgb(0, 255, 0) 60%); ``` - + ![333](figures/333.PNG) diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-config-file.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-config-file.md index cb7360a3d1ae0f9f227f35d869ebbeba1e7cc66e..82867f64408b16b9a82a1d43a786ace97e4f12fa 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-config-file.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-config-file.md @@ -4,11 +4,11 @@ js标签中包含了实例名称、窗口样式和卡片页面信息。 -| 标签 | 类型 | 默认值 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| name | String | default | 是 | 标识JS实例的名字。 | -| pages | Array | - | 是 | 路由信息，详见“[pages](#pages)”。 | -| window | Object | - | 否 | 窗口信息，详见“[window](#window)”。 | +| 标签 | 类型 | 默认值 | 必填 | 描述 | +| ------ | ------ | ------- | ---- | --------------------------- | +| name | String | default | 是 | 标识JS实例的名字。 | +| pages | Array | - | 是 | 路由信息，详见“[pages](#pages)”。 | +| window | Object | - | 否 | 窗口信息，详见“[window](#window)”。 | > **说明：** > name、pages、window等标签配置需在[配置文件]()中的“js”标签中完成设置。 @@ -29,9 +29,9 @@ js标签中包含了实例名称、窗口样式和卡片页面信息。 > **说明：** -> - pages列表中仅包含一个页面。 -> -> - 页面文件名不能使用组件名称，比如：text.hml、button.hml等。 +> - pages列表中仅包含一个页面。 +> +> - 页面文件名不能使用组件名称，比如：text.hml、button.hml等。 ## window @@ -43,16 +43,15 @@ window用于定义与显示窗口相关的配置。对于卡片尺寸适配问 - 设置autoDesignWidth为true，此时designWidth字段将会被忽略，渲染组件和布局时按屏幕密度进行缩放。屏幕逻辑宽度由设备宽度和屏幕密度自动计算得出，在不同设备上可能不同，请使用相对布局来适配多种设备。例如：在466\*466分辨率，320dpi的设备上，屏幕密度为2（以160dpi为基准），1px等于渲染出的2物理像素。 > **说明：** > - 组件样式中<length>类型的默认值，按屏幕密度进行计算和绘制，如：在屏幕密度为2（以160dpi为基准）的设备上，默认<length>为1px时，设备上实际渲染出2物理像素。 - > + > > - autoDesignWidth、designWidth的设置不影响默认值计算方式和绘制结果。 -| 属性 | 类型 | 必填 | 默认值 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| designWidth | number | 否 | 150px | 页面显示设计时的参考值，实际显示效果基于设备宽度与参考值之间的比例进行缩放。 | -| autoDesignWidth | boolean | 否 | false | 页面设计基准宽度是否自动计算，当设为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。 | +| 属性 | 类型 | 必填 | 默认值 | 描述 | +| --------------- | ------- | ---- | ----- | ---------------------------------------- | +| designWidth | number | 否 | 150px | 页面显示设计时的参考值，实际显示效果基于设备宽度与参考值之间的比例进行缩放。 | +| autoDesignWidth | boolean | 否 | false | 页面设计基准宽度是否自动计算，当设为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。 | 示例如下： - ``` { ... "window": { @@ -60,7 +59,6 @@ window用于定义与显示窗口相关的配置。对于卡片尺寸适配问 } ... } - ``` ## 示例 diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-list.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-list.md index 4b369117a3c80f9796cb0b9cb444949ded9515be..02576d205dc77aa2c8754dbdb494cb23d7eb116a 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-list.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-list.md @@ -21,37 +21,37 @@ 除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性： -| 名称 | 类型 | 默认值 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| cachedcount | number | 0 | 否 | 长列表延迟加载时list-item最少缓存数量。 | -| scrollbar | string | off | 否 | 侧边滑动栏的显示模式（当前只支持纵向）：
- off：不显示。
- auto：按需显示(触摸时显示，2s后消失)。
- on：常驻显示。 | -| scrolleffect | string | spring | 否 | 滑动效果，目前支持如下滑动效果：
- spring：弹性物理动效，滑动到边缘后可以根据初始速度或通过触摸事件继续滑动一段距离，松手后回弹。
- fade：渐隐物理动效，滑动到边缘后展示一个波浪形的渐隐，根据速度和滑动距离的变化渐隐也会发送一定的变化。
- no：滑动到边缘后无效果。 | -| divider | boolean | false | 否 | item是否自带分隔线。
其样式参考[样式列表](#样式)的divider-color、divider-height、divider-length、divider-origin。 | -| shapemode | string | default | 否 | 侧边滑动栏的形状类型。
- default：不指定，跟随主题。
- rect：矩形。
- round：圆形。 | -| updateeffect | boolean | false | 否 | 用于设置当list内部的item发生删除或新增时是否支持动效。
- false：新增删除item时无过渡动效。
- true：新增删除item时播放过程动效。 | -| initialindex | number | 0 | 否 | 用于设置当前List初次加载时视口起始位置显示的item，默认为0，即显示第一个item，如设置的序号超过了最后一个item的序号，则设置不生效，当同时设置了initialoffset属性时，当前属性不生效。 | -| initialoffset | <length> | 0 | 否 | 用于设置当前List初次加载时视口的起始偏移量，偏移量无法超过当前List可滑动的范围，如果超过会被截断为可滑动范围的极限值。 | -| selected | string | - | 否 | 指定当前列表中被选中激活的项，可选值为list-item的section属性值。 | +| 名称 | 类型 | 默认值 | 必填 | 描述 | +| ------------- | -------------- | ------- | ---- | ---------------------------------------- | +| cachedcount | number | 0 | 否 | 长列表延迟加载时list-item最少缓存数量。 | +| scrollbar | string | off | 否 | 侧边滑动栏的显示模式（当前只支持纵向）：
- off：不显示。
- auto：按需显示(触摸时显示，2s后消失)。
- on：常驻显示。 | +| scrolleffect | string | spring | 否 | 滑动效果，目前支持如下滑动效果：
- spring：弹性物理动效，滑动到边缘后可以根据初始速度或通过触摸事件继续滑动一段距离，松手后回弹。
- fade：渐隐物理动效，滑动到边缘后展示一个波浪形的渐隐，根据速度和滑动距离的变化渐隐也会发送一定的变化。
- no：滑动到边缘后无效果。 | +| divider | boolean | false | 否 | item是否自带分隔线。
其样式参考[样式列表](#样式)的divider-color、divider-height、divider-length、divider-origin。 | +| shapemode | string | default | 否 | 侧边滑动栏的形状类型。
- default：不指定，跟随主题。
- rect：矩形。
- round：圆形。 | +| updateeffect | boolean | false | 否 | 用于设置当list内部的item发生删除或新增时是否支持动效。
- false：新增删除item时无过渡动效。
- true：新增删除item时播放过程动效。 | +| initialindex | number | 0 | 否 | 用于设置当前List初次加载时视口起始位置显示的item，默认为0，即显示第一个item，如设置的序号超过了最后一个item的序号，则设置不生效，当同时设置了initialoffset属性时，当前属性不生效。 | +| initialoffset | <length> | 0 | 否 | 用于设置当前List初次加载时视口的起始偏移量，偏移量无法超过当前List可滑动的范围，如果超过会被截断为可滑动范围的极限值。 | +| selected | string | - | 否 | 指定当前列表中被选中激活的项，可选值为list-item的section属性值。 | ## 样式 除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式： -| 名称 | 类型 | 默认值 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| divider-color | <color> | transparent | 否 | item分隔线颜色，仅当list的divider属性为true时生效。 | -| divider-height | <length> | 1 | 否 | item分隔线高度，仅当list的divider属性为true时生效。 | -| divider-length | <length> | 主轴宽度 | 否 | item分隔线长度，不设置时最大长度为主轴宽度，具体长度取决于divider-origin，仅当list的divider属性为true时生效。 | -| divider-origin | <length> | 0 | 否 | item分隔线相对于item主轴起点位置的偏移量，仅当list的divider属性为true时生效。 | -| flex-direction | string | column | 否 | 设置flex容器主轴的方向，指定flex项如何放置在flex容器中，可选值为：
- column：主轴为纵向。
- row：主轴为横向。
其他组件默认值为row，在list组件中默认值为column。 | -| columns | number | 1 | 否 | list交叉轴方向的显示列数，默认为1列。
设置多列时，在list交叉轴上进行均分，每一列大小相同。 | -| align-items | string | stretch | 否 | list每一列交叉轴上的对齐格式，可选值为：
- stretch：弹性元素被在交叉轴方向被拉伸到与容器相同的高度或宽度。
- flex-start：元素向交叉轴起点对齐。
- flex-end：元素向交叉轴终点对齐。
- center：元素在交叉轴居中。
 align-items样式作用在每一列的子元素上，列与列之间采用均分方式布局。 | -| item-extent | <length> \| <percentage> | - | 否 | 设置内部item为固定大小，设置为百分比格式时，指相对于list的视口主轴方向长度的百分比。 | -| fade-color | <color> | grey | 否 | 设置渐隐物理动效的颜色。当滑动效果设置为渐隐物理动效时生效。 | -| scrollbar-color | <color> | - | 否 | 设置滚动条的颜色。 | -| scrollbar-width | <length> | - | 否 | 设置滚动条的宽度。 | -| scrollbar-offset | <length> | 0 | 否 | 设置滚动条距离List默认位置的偏移量，只支持正数，默认位置在List右边缘，可以通过这个偏移量调整滚动条的水平位置，如果滚动条绘制在list外部，而list父组件有裁剪，会导致滚动条被裁剪。 | +| 名称 | 类型 | 默认值 | 必填 | 描述 | +| ---------------- | ---------------------------------------- | ----------- | ---- | ---------------------------------------- | +| divider-color | <color> | transparent | 否 | item分隔线颜色，仅当list的divider属性为true时生效。 | +| divider-height | <length> | 1 | 否 | item分隔线高度，仅当list的divider属性为true时生效。 | +| divider-length | <length> | 主轴宽度 | 否 | item分隔线长度，不设置时最大长度为主轴宽度，具体长度取决于divider-origin，仅当list的divider属性为true时生效。 | +| divider-origin | <length> | 0 | 否 | item分隔线相对于item主轴起点位置的偏移量，仅当list的divider属性为true时生效。 | +| flex-direction | string | column | 否 | 设置flex容器主轴的方向，指定flex项如何放置在flex容器中，可选值为：
- column：主轴为纵向。
- row：主轴为横向。
其他组件默认值为row，在list组件中默认值为column。 | +| columns | number | 1 | 否 | list交叉轴方向的显示列数，默认为1列。
设置多列时，在list交叉轴上进行均分，每一列大小相同。 | +| align-items | string | stretch | 否 | list每一列交叉轴上的对齐格式，可选值为：
- stretch：弹性元素被在交叉轴方向被拉伸到与容器相同的高度或宽度。
- flex-start：元素向交叉轴起点对齐。
- flex-end：元素向交叉轴终点对齐。
- center：元素在交叉轴居中。
 align-items样式作用在每一列的子元素上，列与列之间采用均分方式布局。 | +| item-extent | <length> \| <percentage> | - | 否 | 设置内部item为固定大小，设置为百分比格式时，指相对于list的视口主轴方向长度的百分比。 | +| fade-color | <color> | grey | 否 | 设置渐隐物理动效的颜色。当滑动效果设置为渐隐物理动效时生效。 | +| scrollbar-color | <color> | - | 否 | 设置滚动条的颜色。 | +| scrollbar-width | <length> | - | 否 | 设置滚动条的宽度。 | +| scrollbar-offset | <length> | 0 | 否 | 设置滚动条距离List默认位置的偏移量，只支持正数，默认位置在List右边缘，可以通过这个偏移量调整滚动条的水平位置，如果滚动条绘制在list外部，而list父组件有裁剪，会导致滚动条被裁剪。 | ## 事件 @@ -76,7 +76,6 @@ ```json -// xxx.json { "data": { "todolist": [{ diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-swiper.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-swiper.md index 0dc9b2f39d9da11c5c33517c863d87c1a4e376dd..236748668d0c771c15ccf1cdfd961b8fd5d0db23 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-swiper.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-container-swiper.md @@ -6,7 +6,7 @@ > **说明：** > ->从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +> 从API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 @@ -14,26 +14,26 @@ 除支持[通用属性](js-service-widget-common-attributes.md)外，还支持如下属性： -| 名称 | 类型 | 默认值 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| index | number | 0 | 否 | 当前在容器中显示的子组件的索引值。 | -| indicator | boolean | true | 否 | 是否启用导航点指示器，默认true。 | -| digital | boolean | false | 否 | 是否启用数字导航点，默认为false。
必须设置indicator时才能生效数字导航点。 | -| loop | boolean | true | 否 | 是否开启循环滑动。 | -| duration | number | - | 否 | 子组件切换的动画时长。 | -| vertical | boolean | false | 否 | 是否为纵向滑动，纵向滑动时采用纵向的指示器。 | +| 名称 | 类型 | 默认值 | 必填 | 描述 | +| --------- | ------- | ----- | ---- | ---------------------------------------- | +| index | number | 0 | 否 | 当前在容器中显示的子组件的索引值。 | +| indicator | boolean | true | 否 | 是否启用导航点指示器，默认true。 | +| digital | boolean | false | 否 | 是否启用数字导航点，默认为false。
必须设置indicator时才能生效数字导航点。 | +| loop | boolean | true | 否 | 是否开启循环滑动。 | +| duration | number | - | 否 | 子组件切换的动画时长。 | +| vertical | boolean | false | 否 | 是否为纵向滑动，纵向滑动时采用纵向的指示器。 | ## 样式 除支持[通用样式](js-service-widget-common-styles.md)外，还支持如下样式： -| 名称 | 类型 | 默认值 | 必填 | 描述 | -| -------- | -------- | -------- | -------- | -------- | -| indicator-color | <color> | - | 否 | 导航点指示器的填充颜色。 | -| indicator-selected-color | <color> | - | 否 | 导航点指示器选中的颜色。 | -| indicator-size | <length> | 4px | 否 | 导航点指示器的直径大小。 | -| indicator-top\|left\|right\|bottom | <length> \| <percentage> | - | 否 | 导航点指示器在swiper中的相对位置。 | +| 名称 | 类型 | 默认值 | 必填 | 描述 | +| ---------------------------------- | ---------------------------------------- | ---- | ---- | -------------------- | +| indicator-color | <color> | - | 否 | 导航点指示器的填充颜色。 | +| indicator-selected-color | <color> | - | 否 | 导航点指示器选中的颜色。 | +| indicator-size | <length> | 4px | 否 | 导航点指示器的直径大小。 | +| indicator-top\|left\|right\|bottom | <length> \| <percentage> | - | 否 | 导航点指示器在swiper中的相对位置。 | ## 事件 @@ -87,7 +87,6 @@ ```json -// xxx.json { "data": { "index": 1 diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-events.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-events.md index c1b03b177da3a3ff2c88f4e84a90f982cab2f9f2..05287a5e1f56337015048392cdcc11e1cfa617d7 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-events.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-events.md @@ -6,7 +6,7 @@ > **说明：** > -> 事件名不支持大写字母。 +> 事件名不支持大写字母。 ## 子组件comp示例： @@ -43,7 +43,6 @@ ```json -// comp.json { "data": { }, @@ -83,8 +82,7 @@ -```json -// xxx.json +```j'so { "data": { }, diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-props.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-props.md index 347e6479bfc7604779cc803544faa58e5ac9dc65..9d3a1fbf02c4de67afe52a6172f7cf265c30e3f0 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-props.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-custom-props.md @@ -35,7 +35,6 @@ ```json -// comp.json { "data": { "progress": { diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-multiple-languages.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-multiple-languages.md index 78c0a0fde361747bd20b0819fc6946958fbb4135..456b3d40ff345a7365a5970b135518b75b311979 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-multiple-languages.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-multiple-languages.md @@ -15,7 +15,7 @@ 由于不同语言针对单复数有不同的匹配规则，在资源文件中的使用“zero”“one”“two”“few”“many”“other”定义不同单复数场景下的词条内容。例如中文不区分单复数仅存在“other”场景；英文存在“one”、“other”场景；阿拉伯语存在上述6种场景。 - 以en-US.json和ar-AE.json为例，资源文件内容格式如下： + 以en-US.json和ar-AE.json为例，资源文件内容格式如下： ```json { @@ -59,19 +59,19 @@ 在应用中使用$t方法引用资源，$t既可以在hml中使用，也可以在js中使用。系统将根据当前语言环境和指定的资源路径（通过$t的path参数设置），显示对应语言的资源文件中的内容。 **表1** 简单格式化 - - | 属性 | 类型 | 参数 | 必填 | 描述 | - | -------- | -------- | -------- | -------- | -------- | - | $t | Function | 请见$t参数说明 | 是 | 根据系统语言完成简单的替换：this.$t('strings.hello') | + + | 属性 | 类型 | 参数 | 必填 | 描述 | + | ---- | -------- | -------- | ---- | -------------------------------------- | + | $t | Function | 请见$t参数说明 | 是 | 根据系统语言完成简单的替换：this.$t('strings.hello') | **表2** $t参数说明 - - | 参数 | 类型 | 必填 | 描述 | - | -------- | -------- | -------- | -------- | - | path | string | 是 | 资源路径 | + + | 参数 | 类型 | 必填 | 描述 | + | ---- | ------ | ---- | ---- | + | path | string | 是 | 资源路径 | - 简单格式化示例代码 - + ```html
@@ -81,21 +81,22 @@ ``` - 单复数格式化方法 - **表3** 单复数格式化 - - | 属性 | 类型 | 参数 | 必填 | 描述 | - | -------- | -------- | -------- | -------- | -------- | - | $tc | Function | 请见$tc参数说明 | 是 | 根据系统语言完成单复数替换：this.$tc('strings.plurals')
定义资源的内容通过json格式的key为“zero”、“one”、“two”、“few”、“many”和“other”区分。 | - - **表4** $tc参数说明 - - | 参数 | 类型 | 必填 | 描述 | - | -------- | -------- | -------- | -------- | - | path | string | 是 | 资源路径 | - | count | number | 是 | 要表达的值 | + + **表3** 单复数格式化 + + | 属性 | 类型 | 参数 | 必填 | 描述 | + | ---- | -------- | --------- | ---- | ---------------------------------------- | + | $tc | Function | 请见$tc参数说明 | 是 | 根据系统语言完成单复数替换：this.$tc('strings.plurals')
定义资源的内容通过json格式的key为“zero”、“one”、“two”、“few”、“many”和“other”区分。 | + + **表4** $tc参数说明 + + | 参数 | 类型 | 必填 | 描述 | + | ----- | ------ | ---- | ----- | + | path | string | 是 | 资源路径 | + | count | number | 是 | 要表达的值 | - 单复数格式化示例代码 - + ```html
diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-hml.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-hml.md index 3270a6fd6a9ed892a310406e55067adc81639505..6cd29b1341e3259773fd6212ac188137eec9ea18 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-hml.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-hml.md @@ -35,7 +35,6 @@ HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组 ```json -// xxx.json { "data": { "content": "Hello World!", @@ -49,9 +48,9 @@ HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组 > **说明：** -> - key值支持对象操作符和数组操作符，如{{key.value}}、{{key[0]}}。 -> -> - 从 API Version 6 开始支持字符串拼接、逻辑运算和三元表达式。 +> - key值支持对象操作符和数组操作符，如{{key.value}}、{{key[0]}}。 +> +> - 从 API Version 6 开始支持字符串拼接、逻辑运算和三元表达式。 > - 字符串拼接： > - 支持变量跟变量：{{key1}}{{key2}}等 > - 支持常量跟变量： "my name is {{name}}， i am from {{city}}." "key1 {{key1}}" @@ -70,18 +69,17 @@ HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组 卡片仅支持click通用事件，事件的定义只能是直接命令式，事件定义必须包含action字段，用以说明事件类型。卡片支持两种事件类型：跳转事件(router)和消息事件(message)。跳转事件可以跳转到卡片提供方的OpenHarmony应用，消息事件可以将开发者自定义信息传递给卡片提供方。事件参数支持变量，变量以"{{}}"修饰。跳转事件中若定义了params字段，则在被拉起应用的onStart的intent中，可用"params"作为key将跳转事件定义的params字段的值取到。 - 跳转事件格式 - + 通过定义ability名称和携带的参数字段params直接跳转，可用"params"作为key提取到跳转事件定义的params字段值。 - - | 选择器 | 样例 | 默认值 | 样例描述 | - | -------- | -------- | -------- | -------- | - | action | string | "router" | 事件类型。
- "router"：用于应用跳转。
- "message"：自定义点击事件。 | - | abilityName | string | - | 跳转ability名。 | - | params | Object | - | 跳转应用携带的额外参数。 | - - + + | 选择器 | 样例 | 默认值 | 样例描述 | + | ----------- | ------ | -------- | ---------------------------------------- | + | action | string | "router" | 事件类型。
- "router"：用于应用跳转。
- "message"：自定义点击事件。 | + | abilityName | string | - | 跳转ability名。 | + | params | Object | - | 跳转应用携带的额外参数。 | + + ```json - // xxx.json { "data": { "mainAbility": "xxx.xxx.xxx" @@ -95,31 +93,30 @@ HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组 } } ``` - + 也可以使用want格式绑定参数跳转到目标应用，want定义了ability名称、包名、携带的参数字段等。 - - | 选择器 | 类型 | 默认值 | 样例描述 | - | ------ | ------ | -------- | ------------------------------------------------------------ | + + | 选择器 | 类型 | 默认值 | 样例描述 | + | ------ | ------ | -------- | ---------------------------------------- | | action | string | "router" | 事件类型。
- "router"：用于应用跳转。
- "message"：自定义点击事件。 | - | want | Object | - | 跳转目标应用的信息，参考want格式表。 | - + | want | Object | - | 跳转目标应用的信息，参考want格式表。 | + **表1** want格式 - - | 选择器 | 类型 | 默认值 | 样例描述 | - | ----------- | -------------------- | ------------ | ------------------------------------------------------------ | + + | 选择器 | 类型 | 默认值 | 样例描述 | + | ----------- | -------------------- | ------------ | ---------------------------------------- | | bundleName | string | - | 表示包描述。如果在Want中同时指定了BundleName和AbilityName，则Want可以直接匹配到指定的Ability。 | - | abilityName | string | - | 表示待启动的Ability名称。 | - | action | string | - | 表示action选项描述。 | + | abilityName | string | - | 表示待启动的Ability名称。 | + | action | string | - | 表示action选项描述。 | | uri | string | - | 表示Uri描述。如果在Want中指定了Uri，则Want将匹配指定的Uri信息，包括scheme, schemeSpecificPart, authority和path信息。 | - | type | string | "text/plain" | 表示MIME type类型描述，比如："text/plain" 、 "image/*"等。 | + | type | string | "text/plain" | 表示MIME type类型描述，比如："text/plain" 、 "image/*"等。 | | flags | number | - | 表示处理Want的方式。默认传数字，具体参考[flags说明](../apis/js-apis-featureAbility.md#flags说明)。 | - | entities | Array\ | - | 类别，用于指定Intent的操作类别。 | - | parameters | {[key: string]: any} | - | 表示WantParams描述。 | - - + | entities | Array\ | - | 类别，用于指定Intent的操作类别。 | + | parameters | {[key: string]: any} | - | 表示WantParams描述。 | + + ```json - // xxx.json - { + { "data": { "mainAbility": "xxx.xxx.xxx" }, @@ -141,19 +138,18 @@ HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组 } } ``` - - 在API Version 8，want参数需要在app.js或app.ets文件的onCreate方法中调用[featureAbility.getWant](../apis/js-apis-featureAbility.md#featureabilitygetwant-1)接口接收相关参数。 - + + 在API Version 8，want参数需要在app.js或app.ets文件的onCreate方法中调用[featureAbility.getWant](../apis/js-apis-featureAbility.md)接口接收相关参数。 + - 消息事件格式 - | 选择器 | 样例 | 默认值 | 样例描述 | - | -------- | -------- | -------- | -------- | - | action | string | message | 表示事件类型。 | - | params | Object | - | 跳转应用携带的额外参数。 | + | 选择器 | 样例 | 默认值 | 样例描述 | + | ------ | ------ | ------- | ------------ | + | action | string | message | 表示事件类型。 | + | params | Object | - | 跳转应用携带的额外参数。 | + - ```json - // xxx.json { "actions": { "activeEvent": { @@ -165,7 +161,7 @@ HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组 ``` - 绑定路由事件和消息事件 - + ```html
@@ -201,7 +197,6 @@ HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组 ```json -// xxx.json { "data": { "array": [ @@ -221,15 +216,15 @@ tid属性主要用来加速for循环的重渲染，旨在列表中的数据有 - for="(i, v) in array"：其中元素索引为i，元素变量为v，遍历数组对象array。 > **说明：** -> - 数组中的每个元素必须存在tid指定的数据属性，否则运行时可能会导致异常。 -> -> - 数组中被tid指定的属性要保证唯一性，如果不是则会造成性能损耗。比如，示例中只有id和name可以作为tid字段，因为它们属于唯一字段。 -> -> - tid不支持表达式。 -> -> - 不支持for嵌套使用。 -> -> - for对应的变量数组，当前要求数组中的object是相同类型，不支持多种object类型混合写在一个数组中。 +> - 数组中的每个元素必须存在tid指定的数据属性，否则运行时可能会导致异常。 +> +> - 数组中被tid指定的属性要保证唯一性，如果不是则会造成性能损耗。比如，示例中只有id和name可以作为tid字段，因为它们属于唯一字段。 +> +> - tid不支持表达式。 +> +> - 不支持for嵌套使用。 +> +> - for对应的变量数组，当前要求数组中的object是相同类型，不支持多种object类型混合写在一个数组中。 ## 条件渲染 @@ -250,7 +245,6 @@ tid属性主要用来加速for循环的重渲染，旨在列表中的数据有 ```json -// xxx.json { "data": { "show": false, @@ -269,7 +263,6 @@ tid属性主要用来加速for循环的重渲染，旨在列表中的数据有 ```json -// xxx.json { "data": { "visible": false @@ -295,7 +288,6 @@ tid属性主要用来加速for循环的重渲染，旨在列表中的数据有 ```json -// xxx.json { "data": { "show": true diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-version-compatibility.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-version-compatibility.md index 6ffed216a0c9d4923ab3a3ed584a8a1ef67d3c8a..07b5eca24b2027f8b1045f9c3c74a4ea71bbe200 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-version-compatibility.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-version-compatibility.md @@ -5,7 +5,8 @@ > **说明：** -> 低版本兼容能力从 API Version 6 开始支持。 +> +> 低版本兼容能力从 API Version 6 开始支持。 开发者可以通过JSON配置文件配置前向兼容能力。该文件提供了apiVersion属性用于兼容版本，该字段和卡片配置文件的数据字段data、事件字段actions同级。在apiVersion标签下定义的内容会基于当前运行版本信息，覆盖原始的data标签内容。 diff --git a/zh-cn/application-dev/reference/syscap-list.md b/zh-cn/application-dev/reference/syscap-list.md new file mode 100644 index 0000000000000000000000000000000000000000..9910b45a248562a9d06891d80825b61e13eca34e --- /dev/null +++ b/zh-cn/application-dev/reference/syscap-list.md @@ -0,0 +1,180 @@ +# SysCap列表 + +SysCap，全称SystemCapability，即系统能力，指操作系统中每一个相对独立的特性。开发者使用某个接口进行开发前，建议先阅读[SysCap使用指南](../quick-start/syscap.md)，了解Syscap的定义和使用指导。再结合下表判断具体能力集是否支持某个设备，提高开发效率。 + +| SysCap名称 | SysCap描述 | Default | 运动表 | 智能表 | 平板 | 车机 | 智慧屏 | Smart-Vision | Router | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------- | ------ | ------ | ---- | ---- | ------ | ------------ | ------ | +| SystemCapability.ArkUI.
ArkUI.Full | ArKUI标准系统 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.ArkUI.
ArkUI.Lite | ArkUI小型系统 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 否 | +| SystemCapability.ArkUI.
ArkUI.Napi | napi功能 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.ArkUI.
ArkUI.Libuv | libuv功能 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.ArkUI.
UiAppearance | 外观配置功能 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.BundleManager.
BundleFramework | 包管理服务 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.BundleManager.
DistributedBundleFramework | 分布式包管理服务 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.BundleManager.
BundleTool | 包管理命令行工具 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.BundleManager.
Zlib | Zlib压缩、解压缩工具 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.BundleManager.
PackingTool | 包管理打包、拆包工具 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 否 | +| SystemCapability.Graphic.
Graphic2D.WebGL | WebGL1.0 标准api | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Graphic.
Graphic2D.WebGL2 | WebGL2.0 标准api | 是 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | +| SystemCapability.WindowManager.
WindowManager.Core | 窗口管理 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.WindowManager.
WindowManager.MutiScreen | 多屏能力 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Notification.
CommonEvent | 公共事件 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Notification.
Notification | 通知 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Notification.
ReminderAgent | 后台代理提醒 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Notification.
Emitter | 事件处理服务 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
IPC.Core | 进程间通信 | 是 | 否 | 是 | 是 | 是 | 是 | 是 | 否 | +| SystemCapability.Communication.
SoftBus.Core | 软总线 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | +| SystemCapability.Communication.
NetManager.Core | 网络管理基础服务 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
NetManager.Extension | 网络管理扩展服务 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
NetStack | 基础网络协议栈能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
WiFi.Core | WIFI基础能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
WiFi.STA | WIFI STA能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
WiFi.AP.Core | WIFI AP能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
WiFi.AP.Extension | WIFI AP扩展能力 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 是 | +| SystemCapability.Communication.
WiFi.P2P | WIFI P2P能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
Bluetooth.Core | 蓝牙服务以及协议栈 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
Bluetooth.Lite | 蓝牙轻量级服务 | 是 | 是 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Communication.
NFC.Core | NFC服务 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | +| SystemCapability.Communication.
ConnectedTag | 有源NFC标签服务 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | +| SystemCapability.Location.
Location.Core | 位置服务基础能力 | 是 | 否 | 是 | 是 | 是 | 否 | 否 | 否 | +| SystemCapability.Location.
Location.Geocoder | 地理编码能力 | 是 | 否 | 是 | 是 | 是 | 否 | 否 | 否 | +| SystemCapability.Location.
Location.Geofence | 地理围栏能力 | 是 | 否 | 是 | 是 | 是 | 否 | 否 | 否 | +| SystemCapability.Location.
Location.Gnss | GNSS硬件相关能力 | 是 | 否 | 是 | 是 | 是 | 否 | 否 | 否 | +| SystemCapability.Location.
Location.Lite | 位置服务轻设备能力 | 是 | 是 | 是 | 是 | 是 | 否 | 否 | 否 | +| SystemCapability.MultimodalInput.
Input.Core | 基本输入能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.MultimodalInput.
Input.InputDevice | 输入设备管理 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.MultimodalInput.
Input.RemoteInputDevice | 分布式输入设备管理 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.MultimodalInput.
Input.InputMonitor | 输入事件监听者 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.MultimodalInput.
Input.InputConsumer | 输入事件消费者 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.MultimodalInput.
Input.InputSimulator | 输入事件模拟者 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.MultimodalInput.
Input.InputFilter | 输入事件过滤器 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.PowerManager.
BatteryManager.Extension | 电池服务扩展能力 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.PowerManager.
BatteryStatistics | 耗电统计 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.PowerManager.
DisplayPowerManager | 显示能效管理 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.PowerManager.
ThermalManager | 温控服务 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.PowerManager.
PowerManager.Core | 系统电源管理服务核心能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.PowerManager.
PowerManager.Lite | 轻设备系统电源管理服务能力 | 否 | 是 | 否 | 否 | 否 | 否 | 是 | 是 | +| SystemCapability.PowerManager.
BatteryManager.Core | 电池服务核心能力 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.PowerManager.
BatteryManager.Lite | 轻设备电池服务能力 | 否 | 是 | 否 | 否 | 否 | 否 | 是 | 是 | +| SystemCapability.PowerManager.
PowerManager.Extension | 系统电源管理服务扩展能力 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.Core | 媒体基础能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.AudioPlayer | 媒体音频播放引擎能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.AudioRecorder | 媒体音频播录制引擎能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.VideoPlayer | 媒体视频播放引擎能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.VideoRecorder | 媒体视频录制引擎能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.CodecBase | 媒体编解码基础能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.AudioDecoder | 媒体音频解码能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.AudioEncoder | 媒体音频编码能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.VideoDecoder | 媒体视频解码能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.VideoEncoder | 媒体视频编码能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.Spliter | 媒体解封装能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Media.Muxer | 媒体封装能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
AVSession.Core | 媒体会话基础能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
AVSession.Manager | 媒体会话管理能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Audio.Core | 音频基础能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Audio.Renderer | 音频输出能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Audio.Capturer | 音频输入能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Audio.Device | 音频设备管理能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Audio.Volume | 音频音量管理能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Audio.Communication | 音频通信能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Camera.Core | 相机基础能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Camera.DistributedCore | 相机分布式能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Image.Core | 图片基础能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Image.ImageSource | 图片源解码解析能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Image.ImagePacker | 图片打包能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
Image.ImageReceiver | 图片接收能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
MediaLibrary.Core | 媒体库基础能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
MediaLibrary.SmartAlbum | 媒体库智慧相册能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Multimedia.
MediaLibrary.DistributedCore | 媒体库分布式能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Telephony.
CoreService | 蜂窝核心服务 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.Telephony.
CallManager | 通话管理服务 | 是 | 否 | 是 | 是 | 是 | 否 | 否 | 否 | +| SystemCapability.Telephony.
CellularCall | 蜂窝通话服务 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.Telephony.
CellularData | 蜂窝数据服务 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.Telephony.
SmsMms | 短彩信服务 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.Telephony.
StateRegistry | 蜂窝网络状态注册服务 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.Global.I18n | 国际化 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Global.
ResourceManager | 资源管理 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Customization.
ConfigPolicy | 定制框架 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | +| SystemCapability.Customization.
EnterpriseDeviceManager | 企业设备管理 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.BarrierFree.
Accessibility.Core | 提供开发辅助应用的能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.BarrierFree.
Accessibility.Vision | 无障碍视觉辅助能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.BarrierFree.
Accessibility.Hearing | 无障碍听觉辅助能力 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.BarrierFree.
Accessibility.Interaction | 无障碍行为辅助能力 | 是 | 否 | 否 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.ResourceSchedule.
WorkScheduler | 延迟任务调度 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.ResourceSchedule.
BackgroundTaskManager.
ContinuousTask | 长时任务管理 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.ResourceSchedule.
BackgroundTaskManager.
TransientTask | 短时任务管理 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.ResourceSchedule.
UsageStatistics.App | 应用使用信息统计 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.ResourceSchedule.
UsageStatistics.AppGroup | 应用使用活跃分组 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Utils.Lang | TS/JS语言基础库 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.HiviewDFX.
HiLog | 流水日志 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.HiviewDFX.
HiLogLite | 轻量级流水日志 | 否 | 是 | 否 | 否 | 否 | 否 | 是 | 是 | +| SystemCapability.HiviewDFX.
HiTrace | 分布式追踪 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.HiviewDFX.
Hiview.FaultLogger | 事件打点 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.HiviewDFX.
HiviewLite | 轻量级hiview服务 | 否 | 是 | 否 | 否 | 否 | 否 | 是 | 是 | +| SystemCapability.HiviewDFX.
HiChecker | 检测模式 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.HiviewDFX.
HiCollie | 卡死检测 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.HiviewDFX.
HiDumper | 系统信息导出 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.HiviewDFX.
HiAppEvent | 应用事件打点 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.HiviewDFX.
HiSysEvent | 系统事件打点 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.HiviewDFX.
HiEventLite | 轻量级事件打点 | 否 | 是 | 否 | 否 | 否 | 否 | 否 | 是 | +| SystemCapability.HiviewDFX.
HiProfiler.HiDebug | 调试调优 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Update.
UpdateService | 升级服务 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | +| SystemCapability.
DistributedHardware.
DeviceManager | 分布式设备管理 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.Security.
DeviceAuth | 设备互信认证 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.Security.
DataTransitManager | 数据传输管控策略库 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.Security.
DeviceSecurityLevel | 设备安全等级管理 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.Security.
Huks | 设备密钥管理 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.Security.
AccessToken | 访问控制 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Security.
Cipher | 加解密 | 否 | 否 | 否 | 否 | 否 | 否 | 是 | 否 | +| SystemCapability.Account.
OsAccount | 帐号 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Account.
AppAccount | 应用账号 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.UserIAM.
UserAuth.Core | 统一用户认证 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.UserIAM.
UserAuth.PinAuth | 口令认证 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.UserIAM.
UserAuth.FaceAuth | 人脸认证 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.MiscServices.
InputMethodFramework | 输入法框架 | 是 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.MiscServices.
Pasteboard | 剪贴板服务 | 是 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.MiscServices.
Time | 时间时区定时 | 是 | 否 | 是 | 是 | 否 | 是 | 否 | 否 | +| SystemCapability.MiscServices.
Wallpaper | 壁纸框架 | 是 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.MiscServices.
ScreenLock | 锁屏服务 | 是 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.MiscServices.
Upload | 上传服务 | 是 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.MiscServices.
Download | 下载服务 | 是 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.FileManagement.
StorageService.Backup | 备份恢复 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.FileManagement.
StorageService.SpatialStatistics | 空间统计 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.FileManagement.
StorageService.Volume | 卷管理 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.FileManagement.
StorageService.Encryption | 文件加密能力 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.FileManagement.
File.FileIO | 基础文件IO接口 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | +| SystemCapability.FileManagement.
File.Environment | 环境相关接口 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | +| SystemCapability.FileManagement.
File.DistributedFile | 分布式文件扩展接口 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.FileManagement.
AppFileService | 应用文件分享 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.FileManagement.
UserFileService | 用户文件访问服务 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.USB.USBManager | usb服务 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Sensors.Sensor | 传感器服务订阅 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.Sensors.MiscDevice | 小器件-振感 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | +| SystemCapability.Startup.SystemInfo | 系统基本信息 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | +| SystemCapability.
DistributedDataManager.
RelationalStore.Core | 关系型数据库核心能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
RelationalStore.Synchronize | 关系型数据库分布式能力 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
RelationalStore.Lite | 轻量级关系型数据库 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
KVStore.Core | Key-Value型数据库核心能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
KVStore.Lite | 轻量级Key-Value型数据库核心能力 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
KVStore.DistributedKVStore | 分布式Key-Value型数据库 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
DataObject.DistributedObject | 分布式对象 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
Preferences.Core | 偏好型数据存储核心能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
DataShare.Core | 跨进程数据共享，基础能力 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
DataShare.Consumer | 跨进程数据共享，数据消费者 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.
DistributedDataManager.
DataShare.Provider | 跨进程数据共享，数据生产者 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Ability.AbilityBase | 组件运行基础数据定义，主要包括组件通信数据的载体want、系统配置定义等 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Ability
.AbilityRuntime.Core | 组件运行核心基础功能模块，包括应用初始化、无界面组件运行等； | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Ability.
AbilityRuntime.FAModel | FA模型 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Ability.
AbilityRuntime.AbilityCore | 通用组件(有界面) | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Ability.
AbilityRuntime.Mission | 任务管理 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Ability.
AbilityTools.AbilityAssistant | 命令行工具 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Ability.Form | 卡片管理 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Ability.
DistributedAbilityManager | 分布式流转管理（continuationManager)接口定义，支持打开互联面板、更新流转状态 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Applications.
ContactsData | 联系人数据库 | 是 | 否 | 是 | 是 | 是 | 否 | 否 | 否 | +| SystemCapability.Applications.
Contacts | 联系人 | 是 | 否 | 是 | 是 | 是 | 否 | 否 | 否 | +| SystemCapability.Applictaions.
settings.Core | 设置API | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Test.UiTest | UI测试框架能力支持 | 是 | 否 | 否 | 是 | 是 | 否 | 否 | 否 | +| SystemCapability.Web.
Webview.Core | webview组件 | 是 | 否 | 是 | 是 | 是 | 是 | 否 | 否 | +| SystemCapability.Cloud.AAID | AAID管理服务 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | +| SystemCapability.Cloud.OAID | OAID管理服务 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | +| SystemCapability.Cloud.VAID | VAID管理服务 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | \ No newline at end of file diff --git a/zh-cn/application-dev/security/Readme-CN.md b/zh-cn/application-dev/security/Readme-CN.md index dba654ecce2006d27dd7af5977f0274c35b6ef97..a8aca58e95bd95b7d6e2eb4bb86ecf97467cb23f 100644 --- a/zh-cn/application-dev/security/Readme-CN.md +++ b/zh-cn/application-dev/security/Readme-CN.md @@ -1,9 +1,9 @@ # 安全 - 访问控制 - - [访问控制开发概述](accesstoken-overview.md) - - [访问控制开发指导](accesstoken-guidelines.md) - - [权限定义列表](permission-list.md) + - [访问控制（权限）开发概述](accesstoken-overview.md) + - [访问控制（权限）开发指导](accesstoken-guidelines.md) + - [应用权限列表](permission-list.md) - 用户认证 - [用户认证开发概述](userauth-overview.md) - [用户认证开发指导](userauth-guidelines.md) diff --git a/zh-cn/application-dev/security/accesstoken-guidelines.md b/zh-cn/application-dev/security/accesstoken-guidelines.md index 2ab9bcc05dbf63a2756fc61c0aed48df44111525..33cc66fb4cddd51c885a898f580a9fdf31ed1af3 100644 --- a/zh-cn/application-dev/security/accesstoken-guidelines.md +++ b/zh-cn/application-dev/security/accesstoken-guidelines.md @@ -1,4 +1,4 @@ -# 访问控制开发指导 +# 访问控制（权限）开发指导 ## 场景介绍 @@ -35,7 +35,8 @@ | name | 权限名称。 | | reason | 当申请的权限为user_grant权限时，此字段必填，描述申请权限的原因。 | | usedScene | 当申请的权限为user_grant权限时，此字段必填，描述权限使用的场景和时机。 | -| abilities | 标识需要使用到该权限的元能力，标签为数组形式。 | +| ability | 标识需要使用到该权限的元能力，标签为数组形式。
**适用模型：** FA模型 | +| abilities | 标识需要使用到该权限的元能力，标签为数组形式。
**适用模型：** Stage模型 | | when | 标识权限使用的时机，值为"inuse/always"，表示为仅允许前台使用和前后台都可使用。 | ### FA模型 @@ -52,7 +53,7 @@ "name" : "ohos.permission.PERMISSION1", "reason": "$string:reason", "usedScene": { - "abilities": [ + "ability": [ "FormAbility" ], "when":"inuse" @@ -62,13 +63,13 @@ "name" : "ohos.permission.PERMISSION2", "reason": "$string:reason", "usedScene": { - "abilities": [ + "ability": [ "FormAbility" ], "when":"always" } } - ], + ] } } ``` @@ -103,7 +104,7 @@ "when":"always" } } - ], + ] } } ``` @@ -122,7 +123,7 @@ "allowed-acls": [ "ohos.permission.PERMISSION2" ] - }, + } } ``` @@ -170,5 +171,5 @@ 针对访问控制，有以下相关实例可供参考： -- [`AbilityAccessCtrl`：访问权限控制（eTS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/Safety/AbilityAccessCtrl) +- [`AbilityAccessCtrl`：访问权限控制（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Safety/AbilityAccessCtrl) - [为应用添加运行时权限（eTS）（API 9）](https://gitee.com/openharmony/codelabs/tree/master/Ability/AccessPermission) \ No newline at end of file diff --git a/zh-cn/application-dev/security/accesstoken-overview.md b/zh-cn/application-dev/security/accesstoken-overview.md index cc9ce654d3b1bd614aeb65e6619cb0d3ebdf2ee8..9885ce6029ff076b1d590a7d5b3b4dee288839d8 100644 --- a/zh-cn/application-dev/security/accesstoken-overview.md +++ b/zh-cn/application-dev/security/accesstoken-overview.md @@ -1,4 +1,4 @@ -# 访问控制开发概述 +# 访问控制（权限）开发概述 ATM（AccessTokenManager）是OpenHarmony上基于AccessToken构建的统一的应用权限管理能力。 diff --git a/zh-cn/application-dev/security/huks-guidelines.md b/zh-cn/application-dev/security/huks-guidelines.md index c5a8655ee077a94caa959da94d513fade25ab0f5..f05171ff3e788e0bedd1985704460891c1ee3462 100644 --- a/zh-cn/application-dev/security/huks-guidelines.md +++ b/zh-cn/application-dev/security/huks-guidelines.md @@ -4,21 +4,7 @@ HUKS（OpenHarmony Universal KeyStore，OpenHarmony通用密钥库系统）向应用提供密钥库能力，包括密钥管理及密钥的密码学操作等功能。HUKS所管理的密钥可以由应用导入或者由应用调用HUKS接口生成。 - -## 接口说明 - -| 接口名 | 描述 | -| ------------------------------------------------------------ | ---------------- | -| generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void| 生成密钥 | -| generateKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>| 生成密钥 | -| exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void| 导出公钥 | -| exportKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>| 导出公钥 | -| isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback<boolean>) : void | 查询密钥是否存在 | -| isKeyExist(keyAlias: string, options: HuksOptions) : Promise<boolean> | 查询密钥是否存在 | -| deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void| 删除密钥 | -| deleteKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>| 删除密钥 | - -## 开发步骤 +## 基于JS的开发指导 1. 引入HUKS模块 @@ -89,7 +75,7 @@ } }) ``` - + 4. 使用Update接口进行update操作。 handle为更新密钥的session id，options为更新密钥用的参数集合，需根据具体需要到的算法设定options中的参数。 @@ -115,7 +101,7 @@ }; var result = huks.update(handle, options) ``` - + 5. 使用Finish接口进行finish操作。 handle为 结束密钥的session id，options为结束密钥用的参数集合，需根据具体需要到的算法设定options中的参数。 @@ -142,5 +128,1454 @@ var result = huks.finish(handle, options) ``` +## 基于TS的开发指导 + +### 密钥导入导出 + +可以将密钥导出储存到本地和导入使用已在本地存放的密钥。 + +开发步骤如下： + +1. 生成密钥。 +2. 导出密钥。 +3. 导入密钥。 + +在使用示例前，需要先了解几个预先定义的变量： + +| 参数名 | 类型 | 必填 | 说明 | +| ----------------- | ----------- | ---- | ------------------------ | +| srcKeyAlias | string | 是 | 生成密钥别名。 | +| srcKeyAliasSecond | string | 是 | 导入密钥别名。 | +| huksOptions | HuksOptions | 是 | 用于存放生成key所需TAG。 | +| encryptOptions | HuksOptions | 是 | 用于存放导入key所需TAG。 | + +关于接口的具体信息，可在[API参考文档](..\reference\apis\js-apis-huks.md)中查看。 + +**示例：** + +```ts +/* 以生成RSA512密钥为例 */ +var srcKeyAlias = 'hukRsaKeyAlias'; +var srcKeyAliasSecond = 'huksRsaKeyAliasSecond'; + +async function testImportExport() { + /* 集成生成密钥参数集 */ + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA, + } + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, + } + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512, + } + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB, + } + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5, + } + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256, + } + var huksOptions = { + properties: properties, + inData: new Uint8Array(new Array()) + } + + /* 生成密钥 */ + await huks.generateKey(srcKeyAlias, huksOptions).then((data) => { + console.info(`test generateKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test generateKey err information: ' + JSON.stringify(err)); + }); + + /* 导出密钥 */ + await huks.exportKey(srcKeyAlias, huksOptions).then((data) => { + console.info(`test ExportKey data: ${JSON.stringify(data)}`); + exportKey = data.outData; + }).catch((err) => { + console.info('test ImportKey err information: ' + JSON.stringify(err)); + }); + + /* 集成导入密钥参数集 */ + var propertiesEncrypt = new Array(); + propertiesEncrypt[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA, + } + propertiesEncrypt[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512, + } + propertiesEncrypt[2] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5, + } + propertiesEncrypt[3] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB, + } + propertiesEncrypt[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256, + } + propertiesEncrypt[5] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT, + } + var encryptOptions = { + properties: propertiesEncrypt, + inData: new Uint8Array(new Array()) + } + + /* 导入密钥 */ + encryptOptions.inData = exportKey; + await huks.importKey(srcKeyAliasSecond, encryptOptions).then((data) => { + console.info(`test ImportKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test ImportKey err information: ' + JSON.stringify(err)); + }); +} +``` + +### 安全导入 + +导入加密密钥。 + +开发步骤如下： + +1. huks中生成用于加密导入协商的密钥。 +2. 导出该密钥的公钥，协商出共享密钥。 +3. 生成中间密钥材料并加密密钥。 +4. 导入密钥。 + +在使用示例前，需要先了解几个预先定义的变量： + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ----------- | ---- | -------------------------------- | +| importAlias | string | 是 | 密钥别名。 | +| wrapAlias | string | 是 | 密钥别名。 | +| genWrapOptions | HuksOptions | 是 | 用于存放生成加密协商key所需TAG。 | +| importOptions | HuksOptions | 是 | 用于存放导入加密key所需TAG。 | + +关于接口的具体信息，可在[API参考文档](..\reference\apis\js-apis-huks.md)中查看。 + +**示例：** + +```ts +var inputEccPair = new Uint8Array([ + 0x02, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x20, 0x00, 0x00, + 0x00, 0x20, 0x00, 0x00, 0x00, 0x20, 0x00, 0x00, 0x00, 0xa5, 0xb8, + 0xa3, 0x78, 0x1d, 0x6d, 0x76, 0xe0, 0xb3, 0xf5, 0x6f, 0x43, 0x9d, + 0xcf, 0x60, 0xf6, 0x0b, 0x3f, 0x64, 0x45, 0xa8, 0x3f, 0x1a, 0x96, + 0xf1, 0xa1, 0xa4, 0x5d, 0x3e, 0x2c, 0x3f, 0x13, 0xd7, 0x81, 0xf7, + 0x2a, 0xb5, 0x8d, 0x19, 0x3d, 0x9b, 0x96, 0xc7, 0x6a, 0x10, 0xf0, + 0xaa, 0xbc, 0x91, 0x6f, 0x4d, 0xa7, 0x09, 0xb3, 0x57, 0x88, 0x19, + 0x6f, 0x00, 0x4b, 0xad, 0xee, 0x34, 0x35, 0xfb, 0x8b, 0x9f, 0x12, + 0xa0, 0x83, 0x19, 0xbe, 0x6a, 0x6f, 0x63, 0x2a, 0x7c, 0x86, 0xba, + 0xca, 0x64, 0x0b, 0x88, 0x96, 0xe2, 0xfa, 0x77, 0xbc, 0x71, 0xe3, + 0x0f, 0x0f, 0x9e, 0x3c, 0xe5, 0xf9]); + +var exportWrappingKey; +var importAlias = "importAlias"; +var wrapAlias = "wrappingKeyAlias"; + +async function TestGenFunc(alias, options) { + await genKey(alias, options).then((data) => { + console.log(`test genKey data: ${JSON.stringify(data)}`); + }) + .catch((err) => { + console.log('test genKey err information: ' + JSON.stringify(err)); + }); +} + +function genKey(alias, options) { + return new Promise((resolve, reject) => { + huks.importKey(alias, options, function (err, data) { + console.log(`test genKey data: ${JSON.stringify(data)}`); + if (err.code !== 0) { + console.log('test genKey err information: ' + JSON.stringify(err)); + reject(err); + } else { + resolve(data); + } + }); + }); +} + +async function TestExportFunc(alias, options) { + await exportKey(alias, options).then((data) => { + console.log(`test exportKey data: ${JSON.stringify(data)}`); + }) + .catch((err) => { + console.log('test exportKey err information: ' + JSON.stringify(err)); + }); +} + +function exportKey(alias, options) { + return new Promise((resolve, reject) => { + huks.exportKey(alias, options, function (err, data) { + console.log(`test exportKey data: ${JSON.stringify(data)}`); + if (err.code !== 0) { + console.log('test exportKey err information: ' + JSON.stringify(err)); + reject(err); + } else { + exportWrappingKey = data.outData; + resolve(data); + } + }); + }); +} + +async function TestImportWrappedFunc(alias, wrappingAlias, options) { + var result = await huks.importWrappedKey(alias, wrappingAlias, options); + if (result.errorCode === 0) { + console.error('test importWrappedKey success'); + } else { + console.error('test importWrappedKey fail'); + } +} + +async function TestImportWrappedKeyFunc( + importAlias, + wrappingAlias, + genOptions, + importOptions +) { + await TestGenFunc(wrappingAlias, genOptions); + await TestExportFunc(wrappingAlias, genOptions); + + /* 以下操作不需要调用HUKS接口，此处不给出具体实现。 + * 假设待导入的密钥为keyA + * 1.生成ECC公私钥keyB，公钥为keyB_pub, 私钥为keyB_pri + * 2.使用keyB_pri和wrappingAlias密钥中获取的公钥进行密钥协商，协商出共享密钥share_key + * 3.随机生成密钥kek，用于加密keyA，采用AES-GCM加密，加密过程中需要记录：nonce1/aad1/加密后的密文keyA_enc/加密后的tag1。 + * 4.使用share_key加密kek，采用AES-GCM加密，加密过程中需要记录：nonce2/aad2/加密后的密文kek_enc/加密后的tag2。 + * 5.拼接importOptions.inData字段，满足以下格式: + * keyB_pub的长度（4字节） + keyB_pub的数据 + aad2的长度（4字节） + aad2的数据 + + * nonce2的长度（4字节） + nonce2的数据 + tag2的长度（4字节） + tag2的数据 + + * kek_enc的长度（4字节） + kek_enc的数据 + aad1的长度（4字节） + aad1的数据 + + * nonce1的长度（4字节） + nonce1的数据 + tag1的长度（4字节） + tag1的数据 + + * keyA长度占用的内存长度（4字节） + keyA的长度 + keyA_enc的长度（4字节） + keyA_enc的数据 + */ + var inputKey = new Uint8Array([ + 0x5b, 0x00, 0x00, 0x00, 0x30, 0x59, 0x30, 0x13, 0x06, 0x07, 0x2a, + 0x86, 0x48, 0xce, 0x3d, 0x02, 0x01, 0x06, 0x08, 0x2a, 0x86, 0x48, + 0xce, 0x3d, 0x03, 0x01, 0x07, 0x03, 0x42, 0x00, 0x04, 0xc0, 0xfe, + 0x1c, 0x67, 0xde, 0x86, 0x0e, 0xfb, 0xaf, 0xb5, 0x85, 0x52, 0xb4, + 0x0e, 0x1f, 0x6c, 0x6c, 0xaa, 0xc5, 0xd9, 0xd2, 0x4d, 0xb0, 0x8a, + 0x72, 0x24, 0xa1, 0x99, 0xaf, 0xfc, 0x3e, 0x55, 0x5a, 0xac, 0x99, + 0x3d, 0xe8, 0x34, 0x72, 0xb9, 0x47, 0x9c, 0xa6, 0xd8, 0xfb, 0x00, + 0xa0, 0x1f, 0x9f, 0x7a, 0x41, 0xe5, 0x44, 0x3e, 0xb2, 0x76, 0x08, + 0xa2, 0xbd, 0xe9, 0x41, 0xd5, 0x2b, 0x9e, 0x10, 0x00, 0x00, 0x00, + 0xbf, 0xf9, 0x69, 0x41, 0xf5, 0x49, 0x85, 0x31, 0x35, 0x14, 0x69, + 0x12, 0x57, 0x9c, 0xc8, 0xb7, 0x10, 0x00, 0x00, 0x00, 0x2d, 0xb7, + 0xf1, 0x5a, 0x0f, 0xb8, 0x20, 0xc5, 0x90, 0xe5, 0xca, 0x45, 0x84, + 0x5c, 0x08, 0x08, 0x10, 0x00, 0x00, 0x00, 0x43, 0x25, 0x1b, 0x2f, + 0x5b, 0x86, 0xd8, 0x87, 0x04, 0x4d, 0x38, 0xc2, 0x65, 0xcc, 0x9e, + 0xb7, 0x20, 0x00, 0x00, 0x00, 0xf4, 0xe8, 0x93, 0x28, 0x0c, 0xfa, + 0x4e, 0x11, 0x6b, 0xe8, 0xbd, 0xa8, 0xe9, 0x3f, 0xa7, 0x8f, 0x2f, + 0xe3, 0xb3, 0xbf, 0xaf, 0xce, 0xe5, 0x06, 0x2d, 0xe6, 0x45, 0x5d, + 0x19, 0x26, 0x09, 0xe7, 0x10, 0x00, 0x00, 0x00, 0xf4, 0x1e, 0x7b, + 0x01, 0x7a, 0x84, 0x36, 0xa4, 0xa8, 0x1c, 0x0d, 0x3d, 0xde, 0x57, + 0x66, 0x73, 0x10, 0x00, 0x00, 0x00, 0xe3, 0xff, 0x29, 0x97, 0xad, + 0xb3, 0x4a, 0x2c, 0x50, 0x08, 0xb5, 0x68, 0xe1, 0x90, 0x5a, 0xdc, + 0x10, 0x00, 0x00, 0x00, 0x26, 0xae, 0xdc, 0x4e, 0xa5, 0x6e, 0xb1, + 0x38, 0x14, 0x24, 0x47, 0x1c, 0x41, 0x89, 0x63, 0x11, 0x04, 0x00, + 0x00, 0x00, 0x20, 0x00, 0x00, 0x00, 0x20, 0x00, 0x00, 0x00, 0x0b, + 0xcb, 0xa9, 0xa8, 0x5f, 0x5a, 0x9d, 0xbf, 0xa1, 0xfc, 0x72, 0x74, + 0x87, 0x79, 0xf2, 0xf4, 0x22, 0x0c, 0x8a, 0x4d, 0xd8, 0x7e, 0x10, + 0xc8, 0x44, 0x17, 0x95, 0xab, 0x3b, 0xd2, 0x8f, 0x0a]); + + importOptions.inData = inputKey; + await TestImportWrappedFunc(importAlias, wrappingAlias, importOptions); +} + +function makePubKeyOptions() { + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_ECC + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_UNWRAP + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_IMPORT_KEY_TYPE, + value: huks.HuksImportKeyType.HUKS_KEY_TYPE_KEY_PAIR, + }; + var options = { + properties: properties, + inData: inputEccPair + }; + return options; +} + +function makeImportOptions() { + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_CBC + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_UNWRAP_ALGORITHM_SUITE, + value: huks.HuksUnwrapSuite.HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING + }; + var options = { + properties: properties + }; + return options; +} + +function huksImportWrappedKey() { + var genOptions = makePubKeyOptions(); + var importOptions = makeImportOptions(); + TestImportWrappedKeyFunc( + importAlias, + wrapAlias, + genOptions, + importOptions + ); +} +``` + +### 密钥加解密 + +发送和接收数据的双方使用对称或非对称密钥对密钥数据进行加密或解密运算的方法。 + +开发步骤如下： + +1. 生成密钥。 +2. 密钥加密。 +3. 密钥解密。 + +在使用示例前，需要先了解几个预先定义的变量： + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ----------- | ---- | ------------------------ | +| srcKeyAlias | string | 是 | 密钥别名。 | +| huksOptions | HuksOptions | 是 | 用于存放生成key所需TAG。 | +| encryptOptions | HuksOptions | 是 | 用于存放加密key所需TAG。 | +| decryptOptions | HuksOptions | 是 | 用于存放解密key所需TAG。 | + +关于接口的具体信息，可在[API参考文档](..\reference\apis\js-apis-huks.md)中查看。 + +**示例：** + +```ts +/* Cipher操作支持RSA、AES、SM4类型的密钥。 + * + * 以下以SM4 128密钥的Promise操作使用为例 + */ +function sm4CipherStringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} +function sm4CipherUint8ArrayToString(fileData) { + var dataString = ''; + for (var i = 0; i < fileData.length; i++) { + dataString += String.fromCharCode(fileData[i]); + } + return dataString; +} + +var handle; +var IV = '0000000000000000'; +var cipherInData = 'Hks_SM4_Cipher_Test_101010101010101010110_string'; +var srcKeyAlias = 'huksCipherSm4SrcKeyAlias'; +var encryptUpdateResult = new Array(); +var decryptUpdateResult = new Array(); + +async function testCipher() { + /* 集成生成密钥参数集 & 加密参数集 */ + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_SM4, + } + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, + } + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_SM4_KEY_SIZE_128, + } + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_CBC, + } + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE, + } + var huksOptions = { + properties: properties, + inData: new Uint8Array(new Array()) + } + + var propertiesEncrypt = new Array(); + propertiesEncrypt[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_SM4, + } + propertiesEncrypt[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT, + } + propertiesEncrypt[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_SM4_KEY_SIZE_128, + } + propertiesEncrypt[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE, + } + propertiesEncrypt[4] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_CBC, + } + propertiesEncrypt[5] = { + tag: huks.HuksTag.HUKS_TAG_IV, + value: sm4CipherStringToUint8Array(IV), + } + var encryptOptions = { + properties: propertiesEncrypt, + inData: new Uint8Array(new Array()) + } + + /* 生成密钥 */ + await huks.generateKey(srcKeyAlias, huksOptions).then((data) => { + console.info(`test generateKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test generateKey err information: ' + JSON.stringify(err)); + }); + + /* 进行密钥加密操作 */ + await huks.init(srcKeyAlias, encryptOptions).then((data) => { + console.info(`test init data: ${JSON.stringify(data)}`); + handle = data.handle; + }).catch((err) => { + console.info('test init err information: ' + JSON.stringify(err)); + }); + console.info(`leave init`); + encryptOptions.inData = sm4CipherStringToUint8Array(cipherInData); + await huks.update(handle, encryptOptions).then(async (data) => { + console.info(`test update data ${JSON.stringify(data)}`); + encryptUpdateResult = Array.from(data.outData); + }).catch((err) => { + console.info('test update err information: ' + err); + }); + encryptOptions.inData = new Uint8Array(new Array()); + await huks.finish(handle, encryptOptions).then((data) => { + console.info(`test finish data: ${JSON.stringify(data)}`); + var finishData = sm4CipherUint8ArrayToString(new Uint8Array(encryptUpdateResult)); + if (finishData === cipherInData) { + console.info('test finish encrypt err '); + } else { + console.info('test finish encrypt success'); + } + }).catch((err) => { + console.info('test finish err information: ' + JSON.stringify(err)); + }); + + /* 修改加密参数集为解密参数集 */ + propertiesEncrypt.splice(1, 1, { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, + }); + var decryptOptions = { + properties: propertiesEncrypt, + inData: new Uint8Array(new Array()) + } + + /* 进行解密操作 */ + await huks.init(srcKeyAlias, decryptOptions).then((data) => { + console.info(`test init data: ${JSON.stringify(data)}`); + handle = data.handle; + }).catch((err) => { + console.info('test init err information: ' + JSON.stringify(err)); + }); + decryptOptions.inData = new Uint8Array(encryptUpdateResult); + await huks.update(handle, decryptOptions).then(async (data) => { + console.info(`test update data ${JSON.stringify(data)}`); + decryptUpdateResult = Array.from(data.outData); + }).catch((err) => { + console.info('test update err information: ' + err); + }); + decryptOptions.inData = new Uint8Array(new Array()); + await huks.finish(handle, decryptOptions).then((data) => { + console.info(`test finish data: ${JSON.stringify(data)}`); + var finishData = sm4CipherUint8ArrayToString(new Uint8Array(decryptUpdateResult)); + if (finishData === cipherInData) { + console.info('test finish decrypt success '); + } else { + console.info('test finish decrypt err'); + } + }).catch((err) => { + console.info('test finish err information: ' + JSON.stringify(err)); + }); + + await huks.deleteKey(srcKeyAlias, huksOptions).then((data) => { + console.info(`test deleteKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test deleteKey err information: ' + JSON.stringify(err)); + }); +} +``` + +### 密钥签名验签 + +签名：给我们将要发送的数据，做上一个唯一签名；验签： 对发送者发送过来的签名进行验证 。 + +开发步骤如下： + +1. 生成密钥。 +2. 密钥签名。 +3. 导出签名密钥。 +4. 导入签名密钥。 +5. 密钥验签。 + +在使用示例前，需要先了解几个预先定义的变量： + +| 参数名 | 类型 | 必填 | 说明 | +| -------------------- | ----------- | ---- | ------------------------ | +| srcRsaKeyAliasSign | string | 是 | 生成密钥别名。 | +| srcRsaKeyAliasVerify | string | 是 | 导入密钥别名。 | +| rsaSignOptions | HuksOptions | 是 | 用于存放生成key所需TAG。 | +| rsaSignOptionsSecond | HuksOptions | 是 | 用于存放签名key所需TAG。 | +| rsaVerifyOptions | HuksOptions | 是 | 用于存放验签key所需TAG。 | + +关于接口的具体信息，可在[API参考文档](..\reference\apis\js-apis-huks.md)中查看。 + +**示例：** + +```ts +/* Sign/Verify操作支持RSA、ECC、SM2、ED25519、DSA类型的密钥。 + * + * 以下以RSA512密钥的Promise操作使用为例 + */ +function rsaSignVerifyStringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +var rsaSignHandle; +var rsaSignVerifyInData = 'signVerifyInData'; +var srcRsaKeyAliasSign = 'huksSignVerifySrcKeyAliasSign'; +var srcRsaKeyAliasVerify = 'huksSignVerifySrcKeyAliasVerify'; +var finishRsaSignData; +var rsaExportSignKey; + +async function testSignVerify() { + /* 集成生成密钥参数集 & 签名参数集 & 验签参数集 */ + var rsaSignProperties = new Array(); + rsaSignProperties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA, + } + rsaSignProperties[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN, + } + rsaSignProperties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512, + } + rsaSignProperties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_MD5, + } + rsaSignProperties[4] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5, + } + var rsaSignOptions = { + properties: rsaSignProperties, + inData: new Uint8Array(new Array()) + } + + var rsaPropertiesSign = new Array(); + rsaPropertiesSign[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA, + } + rsaPropertiesSign[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN + } + rsaPropertiesSign[2] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_MD5, + } + rsaPropertiesSign[3] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512, + } + rsaPropertiesSign[4] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5, + } + var rsaSignOptionsSecond = { + properties: rsaPropertiesSign, + inData: new Uint8Array(new Array()) + } + + var rsaPropertiesVerify = new Array(); + rsaPropertiesVerify[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA, + } + rsaPropertiesVerify[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY + } + rsaPropertiesVerify[2] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_MD5, + } + rsaPropertiesVerify[3] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512, + } + rsaPropertiesVerify[4] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5, + } + var rsaVerifyOptions = { + properties: rsaPropertiesVerify, + inData: new Uint8Array(new Array()) + } + + /* 生成密钥 */ + await huks.generateKey(srcRsaKeyAliasSign, rsaSignOptions).then((data) => { + console.info(`test generateKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test generateKey err information: ' + JSON.stringify(err)); + }); + + /* 对密钥进行签名操作 */ + await huks.init(srcRsaKeyAliasSign, rsaSignOptionsSecond).then((data) => { + console.info(`test init data: ${JSON.stringify(data)}`); + rsaSignHandle = data.handle; + }).catch((err) => { + console.info('test init err information: ' + JSON.stringify(err)); + }); + rsaSignOptionsSecond.inData = rsaSignVerifyStringToUint8Array(rsaSignVerifyInData) + await huks.update(rsaSignHandle, rsaSignOptionsSecond).then(async (data) => { + console.info(`test update data ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test update err information: ' + err); + }); + rsaVerifyOptions.inData = finishRsaSignData; + await huks.finish(rsaSignHandle, rsaSignOptionsSecond).then((data) => { + console.info(`test finish data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test finish err information: ' + JSON.stringify(err)); + }); + + /* 通过导出导入模拟获取一段密钥数据 */ + await huks.exportKey(srcRsaKeyAliasSign, rsaSignOptions).then((data) => { + console.info(`test exportKey data: ${JSON.stringify(data)}`); + rsaExportSignKey = data.outData; + }).catch((err) => { + console.info('test exportKey err information: ' + JSON.stringify(err)); + }); + rsaVerifyOptions.inData = rsaExportSignKey; + await huks.importKey(srcRsaKeyAliasVerify, rsaVerifyOptions).then((data) => { + console.info(`test ImportKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test exportKey err information: ' + JSON.stringify(err)); + }); + + /* 对密钥进行验签 */ + await huks.init(srcRsaKeyAliasVerify, rsaVerifyOptions).then((data) => { + console.info(`test init data: ${JSON.stringify(data)}`); + rsaSignHandle = data.handle; + }).catch((err) => { + console.info('test init err information: ' + JSON.stringify(err)); + }); + rsaVerifyOptions.inData = rsaSignVerifyStringToUint8Array(rsaSignVerifyInData); + await huks.update(rsaSignHandle, rsaVerifyOptions).then(async (data) => { + console.info(`test update data ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test update err information: ' + err); + }); + rsaVerifyOptions.inData = finishRsaSignData; + await huks.finish(rsaSignHandle, rsaVerifyOptions).then((data) => { + console.info(`test finish data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test finish err information: ' + JSON.stringify(err)); + }); + + await huks.deleteKey(srcRsaKeyAliasVerify, rsaVerifyOptions).then((data) => { + console.info(`test deleteKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test deleteKey err information: ' + JSON.stringify(err)); + }); + + await huks.deleteKey(srcRsaKeyAliasSign, rsaSignOptions).then((data) => { + console.info(`test deleteKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test deleteKey err information: ' + JSON.stringify(err)); + }); +} +``` + +### 密钥协商 + +两个或多个对象生成会话密钥，通过会话密钥进行交流 。 + +开发步骤如下： + +1. 生成两个密钥。 +2. 分别导出密钥。 +3. 交叉进行密钥协商。 + +在使用示例前，需要先了解几个预先定义的变量： + +| 参数名 | 类型 | 必填 | 说明 | +| ------------------- | ----------- | ---- | -------------------------------------- | +| srcKeyAliasFirst | string | 是 | 生成密钥别名。 | +| srcKeyAliasSecond | string | 是 | 生成密钥别名，用于结果对比。 | +| huksOptions | HuksOptions | 是 | 用于存放生成key所需TAG。 | +| finishOptionsFrist | HuksOptions | 是 | 用于存放协商key所需TAG。 | +| finishOptionsSecond | HuksOptions | 是 | 用于存放协商key所需TAG，用于结果对比。 | + +关于接口的具体信息，可在[API参考文档](..\reference\apis\js-apis-huks.md)中查看。 + +**示例：** + +```ts +/* agree操作支持ECDH、DH、X25519类型的密钥。 + * + * 以下以X25519 256密钥的Promise操作使用为例 + */ +function AgreeStringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +var srcKeyAliasFirst = "AgreeX25519KeyFirstAlias"; +var srcKeyAliasSecond = "AgreeX25519KeySecondAlias"; +var agreeX25519InData = 'AgreeX25519TestIndata'; +var exportKeyFrist; +var exportKeySecond; + +async function testAgree() { + /* 集成生成密钥参数集 */ + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_X25519, + } + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_AGREE, + } + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_CURVE25519_KEY_SIZE_256, + } + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_NONE, + } + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE, + } + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_CBC, + } + var huksOptions = { + properties: properties, + inData: new Uint8Array(new Array()) + } + + /* 1.生成两个密钥并导出 */ + await huks.generateKey(srcKeyAliasFirst, huksOptions).then((data) => { + console.info('test generateKey data = ' + JSON.stringify(data)); + }).catch((err) => { + console.info(`test generateKey err: " + ${JSON.stringify(err)}`); + }); + await huks.generateKey(srcKeyAliasSecond, huksOptions).then((data) => { + console.info('test generateKey data = ' + JSON.stringify(data)); + }).catch((err) => { + console.info(`test generateKey err: " + ${JSON.stringify(err)}`); + }); + await huks.exportKey(srcKeyAliasFirst, huksOptions).then((data) => { + console.info('test exportKey data = ' + JSON.stringify(data)); + exportKeyFrist = data.outData; + }).catch((err) => { + console.info(`test exportKey err: " + ${JSON.stringify(err)}`); + }); + await huks.exportKey(srcKeyAliasSecond, huksOptions).then((data) => { + console.info('test exportKey data = ' + JSON.stringify(data)); + exportKeySecond = data.outData; + }).catch((err) => { + console.info(`test exportKey err: " + ${JSON.stringify(err)}`); + }); + + /* 集成第一个协商参数集 */ + var finishProperties = new Array(); + finishProperties[0] = { + tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, + value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT, + } + finishProperties[1] = { + tag: huks.HuksTag.HUKS_TAG_IS_KEY_ALIAS, + value: true + } + finishProperties[2] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES, + } + finishProperties[3] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256, + } + finishProperties[4] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, + } + finishProperties[5] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_NONE, + } + finishProperties[6] = { + tag: huks.HuksTag.HUKS_TAG_KEY_ALIAS, + value: AgreeStringToUint8Array(srcKeyAliasFirst+ 'final'), + } + finishProperties[7] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE, + } + finishProperties[8] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB, + } + var finishOptionsFrist = { + properties: finishProperties, + inData: AgreeStringToUint8Array(agreeX25519InData) + } + + /* 对第一个密钥进行协商 */ + await huks.init(srcKeyAliasFirst, huksOptions).then((data) => { + console.info(`test init data: ${JSON.stringify(data)}`); + handle = data.handle; + }).catch((err) => { + console.info(`test init err: " + ${JSON.stringify(err)}`); + }); + huksOptions.inData = exportKeySecond; + await huks.update(handle, huksOptions).then((data) => { + console.info(`test update data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info(`test update err: " + ${JSON.stringify(err)}`); + }); + await huks.finish(handle, finishOptionsFrist).then((data) => { + console.info(`test finish data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test finish err information: ' + JSON.stringify(err)); + }); + + /* 集成第二个协商参数集 */ + var finishOptionsSecond = { + properties: finishProperties, + inData: AgreeStringToUint8Array(agreeX25519InData) + } + finishOptionsSecond.properties.splice(6, 1, { + tag: huks.HuksTag.HUKS_TAG_KEY_ALIAS, + value: AgreeStringToUint8Array(srcKeyAliasSecond + 'final'), + }) + await huks.init(srcKeyAliasSecond, huksOptions).then((data) => { + console.info(`test init data: ${JSON.stringify(data)}`); + handle = data.handle; + }).catch((err) => { + console.info(`test init err: " + ${JSON.stringify(err)}`); + }); + + /* 对第二个密钥进行协商 */ + huksOptions.inData = exportKeyFrist; + await huks.update(handle, huksOptions).then((data) => { + console.info(`test update data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info(`test update err: " + ${JSON.stringify(err)}`); + }); + await huks.finish(handle, finishOptionsSecond).then((data) => { + console.info(`test finish data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test finish err information: ' + JSON.stringify(err)); + }); + + await huks.deleteKey(srcKeyAliasFirst, huksOptions).then((data) => { + console.info(`test deleteKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test deleteKey err information: ' + JSON.stringify(err)); + }); + await huks.deleteKey(srcKeyAliasSecond, huksOptions).then((data) => { + console.info(`test deleteKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test deleteKey err information: ' + JSON.stringify(err)); + }); +} +``` + +### 密钥派生 + +从一个密钥产生出一个或者多个密钥。 + +**测试流程**：1.生成密钥；2.密钥派生 + +开发步骤如下： + +1. 生成两个密钥。 +2. 分别导出密钥。 +3. 交叉进行密钥协商。 + +在使用示例前，需要先了解几个预先定义的变量： + +| 参数名 | 类型 | 必填 | 说明 | +| ------------- | ----------- | ---- | ---------------- | +| srcKeyAlias | string | 是 | 生成密钥别名。 | +| huksOptions | HuksOptions | 是 | 生成密钥参数集。 | +| finishOptions | HuksOptions | 是 | 派生密钥参数集。 | + +关于接口的具体信息，可在[API参考文档](..\reference\apis\js-apis-huks.md)中查看。 + +**示例：** + +```ts +/* derive操作支持HKDF、pbdkf类型的密钥。 + * + * 以下以HKDF256密钥的Promise操作使用为例 + */ +function hkdfStringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +var deriveHkdfInData = "deriveHkdfTestIndata"; +var srcKeyAlias = "deriveHkdfKeyAlias"; + +async function testDerive() { + /* 集成生成密钥参数集 */ + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES, + } + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DERIVE, + } + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256, + } + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128, + } + var huksOptions = { + properties: properties, + inData: new Uint8Array(new Array()) + } + + /* 生成密钥 */ + await huks.generateKey(srcKeyAlias, huksOptions).then((data) => { + console.info('test generateKey data = ' + JSON.stringify(data)); + }).catch((err) => { + console.info(`test init err: " + ${JSON.stringify(data)}`); + }); + + /* 调整init时的参数集 */ + huksOptions.properties.splice(0, 1, { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_HKDF, + }); + huksOptions.properties.splice(3, 1, { + tag: huks.HuksTag.HUKS_TAG_DERIVE_KEY_SIZE, + value: HuksKeyDERIVEKEYSIZE, + }); + + var finishProperties = new Array(); + finishProperties[0] = { + tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, + value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT, + } + finishProperties[1] = { + tag: huks.HuksTag.HUKS_TAG_IS_KEY_ALIAS, + value: true, + } + finishProperties[2] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES, + } + finishProperties[3] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256, + } + finishProperties[4] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | + huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, + } + finishProperties[5] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_NONE, + } + finishProperties[6] = { + tag: huks.HuksTag.HUKS_TAG_KEY_ALIAS, + value: stringToUint8Array(srcKeyAlias), + } + finishProperties[7] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE, + } + finishProperties[8] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB, + } + var finishOptions = { + properties: finishProperties, + inData: new Uint8Array(new Array()) + } + + /* 进行派生操作 */ + await huks.init(srcKeyAlias, huksOptions).then((data) => { + console.log(`test init data: ${JSON.stringify(data)}`); + handle = data.handle; + }).catch((err) => { + console.log(`test init err: " + ${JSON.stringify(err)}`); + }); + huksOptions.inData = hkdfStringToUint8Array(deriveHkdfInData); + await huks.update(handle, huksOptions).then((data) => { + console.log(`test update data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.log(`test update err: " + ${JSON.stringify(err)}`); + }); + await huks.finish(handle, finishOptions).then((data) => { + console.log(`test finish data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.log('test finish err information: ' + JSON.stringify(err)); + }); + + huksOptions.properties.splice(0, 1, { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_AES, + }); + huksOptions.properties.splice(3, 1, { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128, + }); + + await huks.deleteKey(srcKeyAlias, huksOptions).then((data) => { + console.log(`test deleteKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.log('test deleteKey err information: ' + JSON.stringify(err)); + }); +} +``` + +### 密钥mac + +基于密钥数据进行mac摘要所获得的一个哈希值。 + +开发步骤如下： + +1. 生成密钥。 +2. 密钥mac。 + +在使用示例前，需要先了解几个预先定义的变量： + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ----------- | ---- | -------------- | +| srcKeyAlias | string | 是 | 生成密钥别名。 | +| huksOptions | HuksOptions | 是 | 密钥参数集。 | + +关于接口的具体信息，可在[API参考文档](..\reference\apis\js-apis-huks.md)中查看。 + +**示例：** + +```ts +/* mac操作支持HMAC、SM3类型的密钥。 + * + * 以下以SM3 256密钥的Promise操作使用为例 + */ +function macStringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +var srcKeyAlias = "sm3KeyAlias"; +var hmacInData = 'sm3TestIndata'; +var handle; + +async function testMac() { + /* 集成生成密钥参数集 */ + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_SM3, + } + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_MAC, + } + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SM3, + } + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256, + } + var huksOptions = { + properties:properties, + inData:new Uint8Array(new Array()) + } + + /* 生成密钥 */ + await huks.generateKey(srcKeyAlias, huksOptions).then((data) => { + console.info('test generateKey data = ' + JSON.stringify(data)); + }).catch((err) => { + console.info(`test init err: " + ${JSON.stringify(err)}`); + }); + + /* 修改init时的参数集并进行mac操作 */ + huksOptions.properties.splice(3, 3); + await huks.init(srcKeyAlias, huksOptions).then((data) => { + console.info(`test init data: ${JSON.stringify(data)}`); + handle = data.handle; + }).catch((err) => { + console.info(`test init err: " + ${JSON.stringify(err)}`); + }); + huksOptions.inData = macStringToUint8Array(hmacInData); + await huks.update(handle, huksOptions).then((data) => { + console.info(`test init data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info(`test init err: " + ${JSON.stringify(err)}`); + }); + huksOptions.inData = new Uint8Array(new Array()); + await huks.finish(handle, huksOptions).then((data) => { + console.info(`test update data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test update err information: ' + JSON.stringify(err)); + }); + + huksOptions.properties.splice(1, 0, { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256, + }); + + await huks.deleteKey(srcKeyAlias, huksOptions).then((data) => { + console.info(`test deleteKey data: ${JSON.stringify(data)}`); + }).catch((err) => { + console.info('test deleteKey err information: ' + JSON.stringify(err)); + }); +} +``` + +### AttestID + +测试获取udid等证书信息，并打印相关信息。 + +开发步骤如下： + +1. 生成证书。 +2. 获取证书信息。 + +在使用示例前，需要先了解几个预先定义的变量： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------ | +| keyAlias | string | 是 | 密钥别名，存放待获取证书密钥的别名。 | +| options | HuksOptions | 是 | 用于获取证书时指定所需参数与数据。 | + +关于接口的具体信息，可在[API参考文档](..\reference\apis\js-apis-huks.md)中查看。 + +**示例：** + +```ts +/* 证书AttestID操作示例如下*/ +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +function printLog(...data) { + console.error(data.toString()); +} + +let securityLevel = stringToUint8Array('sec_level'); +let challenge = stringToUint8Array('challenge_data'); +let versionInfo = stringToUint8Array('version_info'); +let udid = stringToUint8Array('udid'); +let serial = stringToUint8Array('serial'); +let deviceId = stringToUint8Array('device_id'); +let idAliasString = "id attest"; + +/* 集成生成密钥参数集 & 生成密钥 */ +function generateKey(alias) { + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, + value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048 + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PSS + }; + properties[6] = { + tag: huks.HuksTag.HUKS_TAG_KEY_GENERATE_TYPE, + value: huks.HuksKeyGenerateType.HUKS_KEY_GENERATE_TYPE_DEFAULT + }; + properties[7] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB + }; + let options = { + properties: properties + }; + huks.generateKey(alias, options); +} + +async function attestId() { + let aliasString = idAliasString; + let aliasUint8 = stringToUint8Array(aliasString); + + /* 集成证书参数集 */ + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO, + value: securityLevel + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE, + value: challenge + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO, + value: versionInfo + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS, + value: aliasUint8 + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_UDID, + value: udid + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SERIAL, + value: serial + }; + properties[6] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_DEVICE, + value: deviceId + }; + let options = { + properties: properties + }; + + generateKey(aliasString); + setTimeout(()=>huks.attestKey(aliasString, options, function (err, data) { + printLog(`key attest result : ${JSON.stringify(data)}`); + }), 1000); +} +``` + +### AttestKey + +测试获取密钥证书，并打印相关信息。 + +开发步骤如下： + +1. 生成证书。 +2. 获取证书信息。 + +在使用示例前，需要先了解几个预先定义的变量： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------ | +| keyAlias | string | 是 | 密钥别名，存放待获取证书密钥的别名。 | +| options | HuksOptions | 是 | 用于获取证书时指定所需参数与数据。 | + +关于接口的具体信息，可在[API参考文档](..\reference\apis\js-apis-huks.md)中查看。 + +**示例：** + +```ts +/* 证书AttestKey操作示例如下*/ +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +function printLog(...data) { + console.error(data.toString()); +} + +let securityLevel = stringToUint8Array('sec_level'); +let challenge = stringToUint8Array('challenge_data'); +let versionInfo = stringToUint8Array('version_info'); +let keyAliasString = "key attest"; + +/* 集成生成密钥参数集 & 生成密钥 */ +function generateKey(alias) { + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_RSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, + value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048 + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 + }; + properties[5] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_PSS + }; + properties[6] = { + tag: huks.HuksTag.HUKS_TAG_KEY_GENERATE_TYPE, + value: huks.HuksKeyGenerateType.HUKS_KEY_GENERATE_TYPE_DEFAULT + }; + properties[7] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB + }; + let options = { + properties: properties + }; + huks.generateKey(alias, options); +} + +async function attestKey() { + let aliasString = keyAliasString; + let aliasUint8 = stringToUint8Array(aliasString); + + /* 集成证书参数集 */ + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO, + value: securityLevel + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE, + value: challenge + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO, + value: versionInfo + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS, + value: aliasUint8 + }; + let options = { + properties: properties + }; + generateKey(aliasString); + setTimeout(()=>huks.attestKey(aliasString, options, function (err, data) { + printLog(`key attest result : ${JSON.stringify(data)}`); + }), 1000); +} +``` diff --git a/zh-cn/application-dev/security/permission-list.md b/zh-cn/application-dev/security/permission-list.md index bf7fc55ab8dc6e5747fc8e9c53dd852c989b6cb3..99f59636494e75526e326f32a81a1bb4a443b2b0 100644 --- a/zh-cn/application-dev/security/permission-list.md +++ b/zh-cn/application-dev/security/permission-list.md @@ -1,4 +1,4 @@ -# 权限定义列表 +# 应用权限列表 在申请目标权限前，建议开发者先阅读[访问控制开发概述-权限的工作流程](accesstoken-overview.md#权限的工作流程)。对权限的工作流程有基本的了解后，再结合下表判断应用能否申请目标权限，提高开发效率。 @@ -117,6 +117,7 @@ | ohos.permission.MANAGE_VOICEMAIL | system_basic | user_grant | TRUE | 允许应用在语音信箱中留言 | | ohos.permission.LOCATION_IN_BACKGROUND | normal | user_grant | FALSE | 允许应用在后台运行时获取设备位置信息。 | | ohos.permission.LOCATION | normal | user_grant | TRUE | 允许应用获取设备位置信息。 | +| ohos.permission.APPROXIMATELY_LOCATION | normal | user_grant | FALSE | 允许应用获取设备模糊位置信息。 | | ohos.permission.MEDIA_LOCATION | normal | user_grant | TRUE | 允许应用访问用户媒体文件中的地理位置信息。 | | ohos.permission.CAMERA | normal | user_grant | TRUE | 允许应用使用相机拍摄照片和录制视频。 | | ohos.permission.READ_MEDIA | normal | user_grant | TRUE | 允许应用读取用户外部存储中的媒体文件信息。 | @@ -131,4 +132,10 @@ | ohos.permission.DISTRIBUTED_SOFTBUS_CENTER | system_basic | system_grant | FALSE | 允许不同设备之间进行组网处理。 | | ohos.permission.ACCESS_DLP_FILE | system_core | system_grant | TRUE | 允许对DLP文件进行权限配置和管理。 | | ohos.permission.PROVISIONING_MESSAGE | system_core | system_grant | TRUE | 允许激活超级设备管理器应用。 | -| ohos.permission.ACCESS_SYSTEM_SETTINGS | system_basic | system_grant | TRUE | 允许应用接入或拉起系统设置界面。 | \ No newline at end of file +| ohos.permission.ACCESS_SYSTEM_SETTINGS | system_basic | system_grant | TRUE | 允许应用接入或拉起系统设置界面。 | +| ohos.permission.READ_IMAGEVIDEO | system_basic | user_grant | TRUE | 允许读取用户公共目录的图片或视频文件。 | +| ohos.permission.READ_AUDIO | system_basic | user_grant | TRUE | 允许读取用户公共目录的音频文件。 | +| ohos.permission.READ_DOCUMENT | system_basic | user_grant | TRUE | 允许读取用户公共目录的文档。 | +| ohos.permission.WRITE_IMAGEVIDEO | system_basic | user_grant | TRUE | 允许修改用户公共目录的图片或视频文件。 | +| ohos.permission.WRITE_AUDIO | system_basic | user_grant | TRUE | 允许修改用户公共目录的音频文件。 | +| ohos.permission.WRITE_DOCUMENT | system_basic | user_grant | TRUE | 允许修改用户公共目录的文档。 | diff --git a/zh-cn/application-dev/telephony/cellular-network-signal-info.md b/zh-cn/application-dev/telephony/cellular-network-signal-info.md index 90d9087aae3b0995ccb86a35149449217f2a7854..8c308e38578da07e19b7fe129fa0af7f47db0ca4 100644 --- a/zh-cn/application-dev/telephony/cellular-network-signal-info.md +++ b/zh-cn/application-dev/telephony/cellular-network-signal-info.md @@ -53,4 +53,4 @@ radio模块提供了获取当前网络信号信息的方法。observer模块为 ## 相关实例 针对蜂窝网络数据开发，有以下相关实例可供参考： -- [`MobileNetwork`：蜂窝数据（eTS）（API9）](https://gitee.com/openharmony/app_samples/tree/master/Telephony/MobileNetwork) \ No newline at end of file +- [`MobileNetwork`：蜂窝数据（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Telephony/MobileNetwork) \ No newline at end of file diff --git a/zh-cn/application-dev/ui/Readme-CN.md b/zh-cn/application-dev/ui/Readme-CN.md index ab862d2dd3c3d4a50f066ce49fc261ecebdbc650..1fa9e2bd8a616441ff07722933a287499204b263 100755 --- a/zh-cn/application-dev/ui/Readme-CN.md +++ b/zh-cn/application-dev/ui/Readme-CN.md @@ -72,6 +72,7 @@ - [构建食物列表List布局](ui-ts-building-category-list-layout.md) - [构建食物分类Grid布局](ui-ts-building-category-grid-layout.md) - [页面跳转与数据传递](ui-ts-page-redirection-data-transmission.md) + - [性能提升的推荐方法](ts-performance-improvement-recommendation.md) - 基于JS扩展的类Web开发范式 - [概述](ui-js-overview.md) diff --git a/zh-cn/application-dev/ui/js-framework-syntax-css.md b/zh-cn/application-dev/ui/js-framework-syntax-css.md index 9def147357018c331a88ede5c43bf35f652636cb..1c62aadebe72cd7e9854cf6be14c659a7de43077 100644 --- a/zh-cn/application-dev/ui/js-framework-syntax-css.md +++ b/zh-cn/application-dev/ui/js-framework-syntax-css.md @@ -79,7 +79,7 @@ css选择器用于选择需要添加样式的元素，支持的选择器如下 ```css /* 页面样式xxx.css */ -/\* 对所有div组件设置样式 \*/ +/* 对所有div组件设置样式 */ div { flex-direction: column; } @@ -95,13 +95,13 @@ div { .title, .content { padding: 5px; } -/\* 对class="container"的组件下的所有text设置样式 \*/ +/* 对class="container"的组件下的所有text设置样式 */ .container text { - color: \#007dff; + color: #007dff; } -/\* 对class="container"的组件下的直接后代text设置样式 \*/ +/* 对class="container"的组件下的直接后代text设置样式 */ .container > text { - color: \#fa2a2d; + color: #fa2a2d; } ``` diff --git a/zh-cn/application-dev/ui/ts-component-states-state.md b/zh-cn/application-dev/ui/ts-component-states-state.md index 2dd964f10e9d8ac6c85741c57a8ce9051a5ad0cf..0a187beec5f6abe75a983020ed142ad422bac672 100644 --- a/zh-cn/application-dev/ui/ts-component-states-state.md +++ b/zh-cn/application-dev/ui/ts-component-states-state.md @@ -1,6 +1,6 @@ # @State -@State装饰的变量是组件内部的状态数据，当这些状态数据被修改时，将会调用所在组件的build方法进行UI刷新。 +@State装饰的变量是组件内部的状态数据，当这些状态数据被修改时，将会调用所在组件的build方法进行UI刷新，只能监听第一层数据的改变，内层数据的改变@State监听不到，无法触发build生命周期。 @State状态数据具有以下特征： diff --git a/zh-cn/application-dev/ui/ts-performance-improvement-recommendation.md b/zh-cn/application-dev/ui/ts-performance-improvement-recommendation.md new file mode 100644 index 0000000000000000000000000000000000000000..b20f704d1150f8df495603794142d77bac6786b3 --- /dev/null +++ b/zh-cn/application-dev/ui/ts-performance-improvement-recommendation.md @@ -0,0 +1,260 @@ +# 性能提升的推荐方法 + +开发者若使用低性能的代码实现功能场景可能不会影响应用的正常运行，但却会对应用的性能造成负面影响。本章节列举出了一些可提升性能的场景供开发者参考，以避免应用实现上带来的性能劣化。 + +## 推荐使用数据懒加载 + +开发者在使用长列表时，如果直接采用循环渲染方式，如下所示，会一次性加载所有的列表元素，一方面会导致页面启动时间过长，影响用户体验，另一方面也会增加服务器的压力和流量，加重系统负担。 + +```ts +@Entry +@Component +struct MyComponent { + @State arr: number[] = Array.from(Array(100), (v,k) =>k); //构造0-99的数组 + build() { + List() { + ForEach(this.arr, (item: number) => { + ListItem() { + Text(`item value: ${item}`) + } + }, (item: number) => item.toString()) + } + } +} +``` + +上述代码会在页面加载时将100个列表元素全部加载，这并非我们需要的，我们希望从数据源中按需迭代加载数据并创建相应组件，因此需要使用数据懒加载，如下所示： + +```ts +class BasicDataSource implements IDataSource { + private listeners: DataChangeListener[] = [] + + public totalCount(): number { + return 0 + } + + public getData(index: number): any { + return undefined + } + + registerDataChangeListener(listener: DataChangeListener): void { + if (this.listeners.indexOf(listener) < 0) { + console.info('add listener') + this.listeners.push(listener) + } + } + + unregisterDataChangeListener(listener: DataChangeListener): void { + const pos = this.listeners.indexOf(listener); + if (pos >= 0) { + console.info('remove listener') + this.listeners.splice(pos, 1) + } + } + + notifyDataReload(): void { + this.listeners.forEach(listener => { + listener.onDataReloaded() + }) + } + + notifyDataAdd(index: number): void { + this.listeners.forEach(listener => { + listener.onDataAdd(index) + }) + } + + notifyDataChange(index: number): void { + this.listeners.forEach(listener => { + listener.onDataChange(index) + }) + } + + notifyDataDelete(index: number): void { + this.listeners.forEach(listener => { + listener.onDataDelete(index) + }) + } + + notifyDataMove(from: number, to: number): void { + this.listeners.forEach(listener => { + listener.onDataMove(from, to) + }) + } +} + +class MyDataSource extends BasicDataSource { + private dataArray: string[] = ['item value: 0', 'item value: 1', 'item value: 2'] + + public totalCount(): number { + return this.dataArray.length + } + + public getData(index: number): any { + return this.dataArray[index] + } + + public addData(index: number, data: string): void { + this.dataArray.splice(index, 0, data) + this.notifyDataAdd(index) + } + + public pushData(data: string): void { + this.dataArray.push(data) + this.notifyDataAdd(this.dataArray.length - 1) + } +} + +@Entry +@Component +struct MyComponent { + private data: MyDataSource = new MyDataSource() + + build() { + List() { + LazyForEach(this.data, (item: string) => { + ListItem() { + Row() { + Text(item).fontSize(20).margin({ left: 10 }) + } + } + .onClick(() => { + this.data.pushData('item value: ' + this.data.totalCount()) + }) + }, item => item) + } + } +} +``` + +上述代码在页面加载时仅初始化加载三个列表元素，之后每点击一次列表元素，将增加一个列表元素。 + +## 使用条件渲染替代显隐控制 + +如下所示，开发者在使用visibility通用属性控制组件的显隐状态时，仍存在组件的重新创建过程，造成性能上的损耗。 + +```ts +@Entry +@Component +struct MyComponent { + @State isVisible: Visibility = Visibility.Visible; + + build() { + Column() { + Button("显隐切换") + .onClick(() => { + if (this.isVisible == Visibility.Visible) { + this.isVisible = Visibility.None + } else { + this.isVisible = Visibility.Visible + } + }) + Row().visibility(this.isVisible) + .width(300).height(300).backgroundColor(Color.Pink) + }.width('100%') + } +} +``` + +要避免这一问题，可使用if条件渲染代替visibility属性变换，如下所示： + +```ts +@Entry +@Component +struct MyComponent { + @State isVisible: boolean = true; + + build() { + Column() { + Button("显隐切换") + .onClick(() => { + this.isVisible = !this.isVisible + }) + if (this.isVisible) { + Row() + .width(300).height(300).backgroundColor(Color.Pink) + } + }.width('100%') + } +} +``` + +## 使用Column/Row替代Flex + +由于Flex容器组件默认情况下存在shrink导致二次布局，这会在一定程度上造成页面渲染上的性能劣化。 + +```ts +@Entry +@Component +struct MyComponent { + build() { + Flex({ direction: FlexDirection.Column }) { + Flex().width(300).height(200).backgroundColor(Color.Pink) + Flex().width(300).height(200).backgroundColor(Color.Yellow) + Flex().width(300).height(200).backgroundColor(Color.Grey) + } + } +} +``` + +上述代码可将Flex替换为Column、Row，在保证实现的页面布局效果相同的前提下避免Flex二次布局带来的负面影响。 + +```ts +@Entry +@Component +struct MyComponent { + build() { + Column() { + Row().width(300).height(200).backgroundColor(Color.Pink) + Row().width(300).height(200).backgroundColor(Color.Yellow) + Row().width(300).height(200).backgroundColor(Color.Grey) + } + } +} +``` + +## 设置List组件的宽高 + +开发者在使用Scroll容器组件嵌套List子组件时，若不指定List的宽高尺寸，则默认全部加载，如下所示： + +```ts +@Entry +@Component +struct MyComponent { + private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; + + build() { + Scroll() { + List() { + ForEach(this.arr, (item) => { + ListItem() { + Text(`item value: ${item}`).fontSize(30).margin({ left: 10 }) + }.height(100) + }, (item) => item.toString()) + } + }.backgroundColor(Color.Pink) + } +} +``` + +因此，在这种场景下建议开发者设置List子组件的宽高，如下所示： + +```ts +@Entry +@Component +struct MyComponent { + private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; + + build() { + Scroll() { + List() { + ForEach(this.arr, (item) => { + ListItem() { + Text(`item value: ${item}`).fontSize(30).margin({ left: 10 }) + }.height(100) + }, (item) => item.toString()) + }.width('100%').height(500) + }.backgroundColor(Color.Pink) + } +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/ui/ts-resource-access.md b/zh-cn/application-dev/ui/ts-resource-access.md index 7858ba7a8adee799dbf99aede2092ce54b21513a..faa397e8dd850efa2974c4ae44a785c8865bdd5c 100644 --- a/zh-cn/application-dev/ui/ts-resource-access.md +++ b/zh-cn/application-dev/ui/ts-resource-access.md @@ -8,7 +8,10 @@ 引用rawfile下资源时使用```"$rawfile('filename')"```的形式，filename需要表示为rawfile目录下的文件相对路径，文件名需要包含后缀，路径开头不可以以"/"开头。 > **说明：** +> > 资源描述符不能拼接使用，仅支持普通字符串如`'app.type.name'`。 +> +> `$r`返回值为Resource对象，可通过[getString](../../reference/apis/js-apis-resource-manager.md#getstring) 方法获取对应的字符串。 在xxx.ets文件中，可以使用在resources目录中定义的资源。 diff --git a/zh-cn/application-dev/ui/ts-types.md b/zh-cn/application-dev/ui/ts-types.md index 7fe41c4e11547cc1fa02f4678f4c907518ba93ca..ebbb98117fd142f5f8a4acbfbcbee944baa96f2f 100644 --- a/zh-cn/application-dev/ui/ts-types.md +++ b/zh-cn/application-dev/ui/ts-types.md @@ -98,6 +98,14 @@ | ---- | ---------------------------------------- | ---------------------------------------- | | Font | {
size?: Length;
weight?: FontWeight  \| number  \| string;
family?: string  \| Resource;
style?: FontStyle;
} | 设置文本样式：
size: 设置文本尺寸，Length为number类型时，使用fp单位。
weight: 设置文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。
family: 设置文本的字体列表。使用多个字体，使用','进行分割，优先级按顺序生效。例如：'Arial, sans-serif'。
style: 设置文本的字体样式。 | + +## ColorFilter类型9+ + +| 名称 | 类型定义 | 描述 | +| ----------- | -------- | ----------------------------------------------------------- | +| ColorFilter | number[] | 用于描述颜色矩阵信息。
行优先矩阵，长度为20的浮点数组。 | + + ## CustomBuilder类型8+ 组件属性方法参数可使用CustomBuilder类型来自定义UI描述。 diff --git a/zh-cn/application-dev/ui/ui-js-building-ui-component.md b/zh-cn/application-dev/ui/ui-js-building-ui-component.md index e190e0b5bed9f96258d5dfedc969f3c0abfb4732..cf63923328412ea24648f56227297cc43d7d552d 100755 --- a/zh-cn/application-dev/ui/ui-js-building-ui-component.md +++ b/zh-cn/application-dev/ui/ui-js-building-ui-component.md @@ -35,8 +35,6 @@ - [`JsUserRegistration`：用户注册（JS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/UI/JsUserRegistration) -- [`ECG`：心率检测（JS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/common/ECG) - - [`Badge`：事件标记控件（JS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/UI/Badge) - [`JsVideo`：视频播放（JS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/media/JsVideo) diff --git a/zh-cn/application-dev/ui/ui-js-components-switch.md b/zh-cn/application-dev/ui/ui-js-components-switch.md index 9430f6e94215b5d88a0a10374076598663cbba3c..e236251483a79026fdcc87663ead6d309a221329 100644 --- a/zh-cn/application-dev/ui/ui-js-components-switch.md +++ b/zh-cn/application-dev/ui/ui-js-components-switch.md @@ -52,10 +52,8 @@ switch为开关选择器，切换开启或关闭状态。具体用法请参考[s align-items: center; background-color: #F1F3F5; } -switch{ - // 选中时的字体颜色 +switch { texton-color: #002aff; - // 未选中时的字体颜色 textoff-color: silver; text-padding: 20px; font-size: 50px; diff --git a/zh-cn/application-dev/ui/ui-js-overview.md b/zh-cn/application-dev/ui/ui-js-overview.md index 178416ba17362d3246441578cab30fc0bfaa8b4e..22adf599ad38ff406b93ffc1c8678760c607c059 100755 --- a/zh-cn/application-dev/ui/ui-js-overview.md +++ b/zh-cn/application-dev/ui/ui-js-overview.md @@ -48,8 +48,6 @@ - [`JsGallery`：图库示例应用（JS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/UI/JsGallery) -- [`AirQuality`：空气质量（JS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/common/AirQuality) - - [`Badge`：事件标记控件（JS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/UI/Badge) - [购物应用（JS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/JSUI/ShoppingOpenHarmony) diff --git a/zh-cn/application-dev/ui/ui-ts-basic-components-button.md b/zh-cn/application-dev/ui/ui-ts-basic-components-button.md index 9983e643f1015dd8e4ecf4fe1449c6876b191565..06ff221c14b45531dc919dca123e6d1ac28f5b43 100644 --- a/zh-cn/application-dev/ui/ui-ts-basic-components-button.md +++ b/zh-cn/application-dev/ui/ui-ts-basic-components-button.md @@ -134,7 +134,7 @@ Button('Ok', { type: ButtonType.Normal, stateEffect: true }) 可以将按钮用于启动操作的任何用户界面元素。按钮会根据用户的操作触发相应的事件。如，在List容器里边通过点击按钮进行页面跳转： ```ts - // xxx.js + // xxx.ets import router from '@ohos.router' @Entry @@ -167,26 +167,27 @@ Button('Ok', { type: ButtonType.Normal, stateEffect: true }) ``` - ![zh-cn_image_0000001235626467](figures/zh-cn_image_0000001235626467.png) +​ ![zh-cn_image_0000001235626467](figures/zh-cn_image_0000001235626467.png) - 用于表单的提交 - 在用户登录/注册页面，用户的登录或注册的提交操作会用按钮。 + 在用户登录/注册页面，用户的登录或注册的提交操作会用按钮。 ```ts -// xxx.js -@Entry - @Component - struct ButtonCase2 { - build() { - Column() { - TextInput({ placeholder: 'input your username' }).margin({ top: 20 }) - TextInput({ placeholder: 'input your password' }).type(InputType.Password).margin({ top: 20 }) - Button('Register').width(300).margin({ top: 20 }) - }.padding(20) + // xxx.ets + @Entry + @Component + struct ButtonCase2 { + build() { + Column() { + TextInput({ placeholder: 'input your username' }).margin({ top: 20 }) + TextInput({ placeholder: 'input your password' }).type(InputType.Password).margin({ top: 20 }) + Button('Register').width(300).margin({ top: 20 }) + }.padding(20) + } } - } ``` + ![zh-cn_image_0000001190466492](figures/zh-cn_image_0000001190466492.png) diff --git a/zh-cn/application-dev/ui/ui-ts-basic-resource-file-categories.md b/zh-cn/application-dev/ui/ui-ts-basic-resource-file-categories.md index 8f704f9f69a725690f39e855e38a51477c6cfe1e..a162017315d13a063d7d5e7cb5fa0f7369af8d5f 100644 --- a/zh-cn/application-dev/ui/ui-ts-basic-resource-file-categories.md +++ b/zh-cn/application-dev/ui/ui-ts-basic-resource-file-categories.md @@ -75,7 +75,7 @@ base目录与限定词目录下面可以创建资源组目录（包括element、 | ------- | ---------------------------------------- | ---------------------------------------- | | element | 表示元素资源，以下每一类数据都采用相应的JSON文件来表征。
- boolean，布尔型
- color，颜色
- float，浮点型
- intarray，整型数组
- integer，整型
- pattern，样式
- plural，复数形式
- strarray，字符串数组
- string，字符串 | element目录中的文件名称建议与下面的文件名保持一致。每个文件中只能包含同一类型的数据。
- boolean.json
- color.json
- float.json
- intarray.json
- integer.json
- pattern.json
- plural.json
- strarray.json
- string.json | | media | 表示媒体资源，包括图片、音频、视频等非文本格式的文件。 | 文件名可自定义，例如：icon.png。 | -| profile | 表示其他类型文件，以原始文件形式保存。 | 文件名可自定义。 | +| rawfile | 表示其他类型文件，在应用构建为hap包后，以原始文件形式保存，不会被集成到resources.index文件中。 | 文件名可自定义。 | ### 媒体资源类型说明 diff --git a/zh-cn/application-dev/ui/ui-ts-layout-mediaquery.md b/zh-cn/application-dev/ui/ui-ts-layout-mediaquery.md index 85b9d19fd65520302a9889724eb4e69f86f915ab..a57eebc7332161fec6af29482d70de9c769c4b70 100644 --- a/zh-cn/application-dev/ui/ui-ts-layout-mediaquery.md +++ b/zh-cn/application-dev/ui/ui-ts-layout-mediaquery.md @@ -43,9 +43,9 @@ listener.on('change', onPortrait) `(max-height: 800)` ：当高度小于800时条件成立 -`(height <= 800) ` ：当高度小于800时条件成立 +`(height <= 800) ` ：当高度小于等于800时条件成立 -`screen and (device-type: tv) or (resolution < 2)` ：包含多个媒体特征的多条件复杂语句查询 +`screen and (device-type: tv) or (resolution < 2)` ：包含多个媒体特征的多条件复杂语句查询 ### 媒体类型(media-type) diff --git a/zh-cn/application-dev/ui/ui-ts-local-storage.md b/zh-cn/application-dev/ui/ui-ts-local-storage.md index 9fb55fdaa18b4a90cc7f563dec0da43ddfac0533..02e927cb539e1ff478bb1942b9aa0a520db7dd9a 100644 --- a/zh-cn/application-dev/ui/ui-ts-local-storage.md +++ b/zh-cn/application-dev/ui/ui-ts-local-storage.md @@ -278,8 +278,8 @@ clear(): boolean ### 示例1（在一个Ability创建的LocalStorage) -```javascript -import Ability from '@ohos.appLication.Ability' +```ts +import Ability from '@ohos.application.Ability' export default class MainAbility extends Ability { storage : LocalStorage onCreate(want) { @@ -335,23 +335,23 @@ let storage = new LocalStorage({"PropA":47}); @Entry(storage) @Component struct ComA { - @LocalStorageLink("PropA") storLink : number = 1; + @LocalStorageLink("PropA") storLink: number = 1; build() { Column() { - Text(`Parent from LocalStorage $(this.storLink)`) + Text(`Parent from LocalStorage ${ this.storLink }`) .onClick(()=>this.storLink+=1) - Child() - } + Child() + } } } @Component struct Child{ - @LocalStorageLink("PropA") storLink : number = 1; + @LocalStorageLink("PropA") storLink: number = 1; build() { - Text(`Parent from LocalStorage $(this.storLink)`) - .onClick(()=>this.storLink1+=1) + Text(`Parent from LocalStorage ${ this.storLink }`) + .onClick(()=>this.storLink+=1) } } ``` \ No newline at end of file diff --git a/zh-cn/application-dev/webgl/webgl-guidelines.md b/zh-cn/application-dev/webgl/webgl-guidelines.md index 972237b3ea2fd222b9cd1b9e1ed8c43ca48488cd..69ae4645ce51af1eb43bc6c90caad7c7ff264ee7 100644 --- a/zh-cn/application-dev/webgl/webgl-guidelines.md +++ b/zh-cn/application-dev/webgl/webgl-guidelines.md @@ -64,7 +64,7 @@ WebGL主要帮助开发者在前端开发中完成图形图像的相关处理， 3. 编辑JavaScript代码文件，增加2D绘制逻辑代码。index.js示例如下： ``` - //index.js + // index.js export default {//NAPI交互代码 data: { title: "DEMO BY TEAMOL", @@ -80,7 +80,7 @@ WebGL主要帮助开发者在前端开发中完成图形图像的相关处理， // 获取2D上下文 const ctx = canvas.getContext('2d'); - //执行CPU绘制函数 + // 执行CPU绘制函数 // Set line width ctx.lineWidth = 10; // Wall @@ -135,9 +135,9 @@ WebGL主要帮助开发者在前端开发中完成图形图像的相关处理， 3. 编辑JavaScript代码文件，增加彩色三角形绘制逻辑代码。index.js示例如下： ``` - //index.js + // index.js - //WebGL相关预定义 + // WebGL相关预定义 var gl = { DEPTH_BUFFER_BIT: 0x00000100, STENCIL_BUFFER_BIT: 0x00000400, @@ -515,7 +515,7 @@ WebGL主要帮助开发者在前端开发中完成图形图像的相关处理， // 向缓冲区对象写入数据 gl.bufferData(gl.ARRAY_BUFFER, verticesColors.buffer, gl.STATIC_DRAW); - //获取着色器中attribute变量a_Position的地址 + // 获取着色器中attribute变量a_Position的地址 var a_Position = gl.getAttribLocation(gl.program, 'a_Position'); if (a_Position < 0) { console.log('Failed to get the storage location of a_Position'); @@ -527,7 +527,7 @@ WebGL主要帮助开发者在前端开发中完成图形图像的相关处理， // 连接a_Position变量与分配给它的缓冲区对象 gl.enableVertexAttribArray(a_Position); - //获取着色器中attribute变量a_Color的地址 + // 获取着色器中attribute变量a_Color的地址 var a_Color = gl.getAttribLocation(gl.program, 'a_Color'); if (a_Color < 0) { console.log('Failed to get the storage location of a_Color'); @@ -704,4 +704,4 @@ WebGL主要帮助开发者在前端开发中完成图形图像的相关处理， 针对WebGL开发，有以下相关实例可供参考： -- [`JsWbgGL`：WebGL（JS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/Graphics/JsWebGL) +- [`JsWbgGL`：WebGL（JS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/master/Graphics/JsWebGL) \ No newline at end of file diff --git a/zh-cn/application-dev/website.md b/zh-cn/application-dev/website.md index cba24b77fb85f3b9d79d6b02e1d4f5ea5acb3bb5..923a7e45bb65064b60a5792dd73b1f9f523d9860 100644 --- a/zh-cn/application-dev/website.md +++ b/zh-cn/application-dev/website.md @@ -108,6 +108,7 @@ - [构建食物列表List布局](ui/ui-ts-building-category-list-layout.md) - [构建食物分类Grid布局](ui/ui-ts-building-category-grid-layout.md) - [页面跳转与数据传递](ui/ui-ts-page-redirection-data-transmission.md) + - [性能提升的推荐方法](ui/ts-performance-improvement-recommendation.md) - 基于JS扩展的类Web开发范式 - [概述](ui/ui-js-overview.md) - 框架说明 @@ -635,6 +636,48 @@ - [slot插槽](reference/arkui-js/js-components-custom-slot.md) - [生命周期定义](reference/arkui-js/js-components-custom-lifecycle.md) - [数据类型说明](reference/arkui-js/js-appendix-types.md) + - JS服务卡片UI组件参考 + - JS服务卡片UI框架说明 + - [文件组织](reference/js-service-widget-ui/js-service-widget-file.md) + - [配置文件](reference/js-service-widget-ui/js-service-widget-config-file.md) + - 语法 + - [HML语法参考](reference/js-service-widget-ui/js-service-widget-syntax-hml.md) + - [CSS语法参考](reference/js-service-widget-ui/js-service-widget-syntax-css.md) + - [配置数据和事件](reference/js-service-widget-ui/js-service-widget-configuration.md) + - [多语言支持](reference/js-service-widget-ui/js-service-widget-multiple-languages.md) + - [低版本兼容](reference/js-service-widget-ui/js-service-widget-version-compatibility.md) + - 组件 + - 通用 + - [通用属性](reference/js-service-widget-ui/js-service-widget-common-attributes.md) + - [通用样式](reference/js-service-widget-ui/js-service-widget-common-styles.md) + - [通用事件](reference/js-service-widget-ui/js-service-widget-common-events.md) + - [渐变样式](reference/js-service-widget-ui/js-service-widget-common-gradient.md) + - [媒体查询](reference/js-service-widget-ui/js-service-widget-common-mediaquery.md) + - [自定义字体样式](reference/js-service-widget-ui/js-service-widget-common-customizing-font.md) + - [无障碍](reference/js-service-widget-ui/js-service-widget-common-accessibility.md) + - [原子布局](reference/js-service-widget-ui/js-service-widget-common-atomic-layout.md) + - 容器组件 + - [div](reference/js-service-widget-ui/js-service-widget-container-div.md) + - [list](reference/js-service-widget-ui/js-service-widget-container-list.md) + - [list-item](reference/js-service-widget-ui/js-service-widget-container-list-item.md) + - [stack](reference/js-service-widget-ui/js-service-widget-container-stack.md) + - [swiper](reference/js-service-widget-ui/js-service-widget-container-swiper.md) + - 基础组件 + - [button](reference/js-service-widget-ui/js-service-widget-basic-button.md) + - [calendar](reference/js-service-widget-ui/js-service-widget-basic-calendar.md) + - [chart](reference/js-service-widget-ui/js-service-widget-basic-chart.md) + - [clock](reference/js-service-widget-ui/js-service-widget-basic-clock.md) + - [divider](reference/js-service-widget-ui/js-service-widget-basic-divider.md) + - [image](reference/js-service-widget-ui/js-service-widget-basic-image.md) + - [input](reference/js-service-widget-ui/js-service-widget-basic-input.md) + - [progress](reference/js-service-widget-ui/js-service-widget-basic-progress.md) + - [span](reference/js-service-widget-ui/js-service-widget-basic-span.md) + - [text](reference/js-service-widget-ui/js-service-widget-basic-text.md) + - 自定义组件 + - [自定义组件基本用法](reference/js-service-widget-ui/js-service-widget-custom-basic-usage.md) + - [自定义事件](reference/js-service-widget-ui/js-service-widget-custom-events.md) + - [Props](reference/js-service-widget-ui/js-service-widget-custom-props.md) + - [数据类型说明](reference/js-service-widget-ui/js-service-widget-appendix-types.md) - 接口参考（JS及TS API） - [开发说明](reference/apis/development-intro.md) - Ability框架 @@ -821,7 +864,7 @@ - [@ohos.screenLock (锁屏管理)](reference/apis/js-apis-screen-lock.md) - [@ohos.systemTime (设置系统时间)](reference/apis/js-apis-system-time.md) - [@ohos.wallpaper (壁纸)](reference/apis/js-apis-wallpaper.md) - - [@ohos.systemTimer(设置系统时间)](js-apis-system-timer.md) + - [@ohos.systemTimer(设置系统时间)](reference/apis/js-apis-system-timer.md) - [Timer (定时器)](reference/apis/js-apis-timer.md) - 设备管理 - [@ohos.batteryInfo (电量信息)](reference/apis/js-apis-battery-info.md) diff --git a/zh-cn/application-dev/windowmanager/application-window-fa.md b/zh-cn/application-dev/windowmanager/application-window-fa.md index be0148a32c242e3d38c3baefbd6265aaa3ce0889..36618463d23c3c19c93cc097c7a7b6f1c027bbee 100644 --- a/zh-cn/application-dev/windowmanager/application-window-fa.md +++ b/zh-cn/application-dev/windowmanager/application-window-fa.md @@ -22,7 +22,7 @@ | 实例名 | 接口名 | 描述 | | -------- | -------- | -------- | -| window静态方法 | create(id:string,type:WindowType,callback:AsyncCallback]<Window>):void | 创建子窗口。
此接口仅可在`FA`模型下使用。 | +| window静态方法 | create(id:string,type:WindowType,callback:AsyncCallback<Window>):void | 创建子窗口。
此接口仅可在`FA`模型下使用。 | | window静态方法 | getTopWindow(callback:AsyncCallback<Window>):void | 获取当前应用内最后显示的窗口。
此接口仅可在`FA`模型下使用。 | | window静态方法 | find(id:string,callback:AsyncCallback<Window>):void | 查找`id`所对应的窗口。 | | Window | loadContent(path:string,callback:AsyncCallback<void>):void | 为当前窗口加载具体页面内容。 | @@ -197,7 +197,7 @@ console.info('Succeeded in enabling the full-screen mode. Data: ' + JSON.stringify(data)); }); // 2.实现沉浸式效果。方式二：设置导航栏、状态栏不显示。 - var names = null; + var names = []; mainWindowClass.setSystemBarEnable(names, (err, data) => { if (err.code) { console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); diff --git a/zh-cn/application-dev/windowmanager/application-window-stage.md b/zh-cn/application-dev/windowmanager/application-window-stage.md index 33fe1385b290ea4b51630d9152f6c3a8341db84d..3fb2397711d5b0fe3e26c6e02241b31af37b6923 100644 --- a/zh-cn/application-dev/windowmanager/application-window-stage.md +++ b/zh-cn/application-dev/windowmanager/application-window-stage.md @@ -241,7 +241,7 @@ class MainAbility extends Ability { console.info('Succeeded in enabling the full-screen mode. Data: ' + JSON.stringify(data)); }); // 2.实现沉浸式效果。方式二：设置导航栏、状态栏不显示。 - var names = null; + var names = []; windowClass.setSystemBarEnable(names, (err, data) => { if (err.code) { console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); @@ -404,3 +404,7 @@ class MainAbility extends Ability { } }; ``` +## 相关实例 + +针对window开发（Stage模型），有以下相关实例可供参考： +- [`Window`：窗口（eTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Graphics/Window) \ No newline at end of file diff --git a/zh-cn/application-dev/windowmanager/display-guidelines.md b/zh-cn/application-dev/windowmanager/display-guidelines.md index ef1ef4abb5c15e2711eb69cab51658809efd037a..98ff63601358f7894896925295df2a90600c6663 100644 --- a/zh-cn/application-dev/windowmanager/display-guidelines.md +++ b/zh-cn/application-dev/windowmanager/display-guidelines.md @@ -15,7 +15,6 @@ ```js import display from '@ohos.display' // 导入模块 -let disp; // disp用来保存默认Display display.getDefaultDisplay().then((disp) => { console.log('display.getDefaultDisplay success, display :' + JSON.stringify(disp)); }, (err) => { @@ -24,5 +23,5 @@ display.getDefaultDisplay().then((disp) => { ``` ## 相关实例 针对屏幕属性开发，有以下相关实例可供参考： -- [`Screen`：屏幕属性（eTS）（API8）](https://gitee.com/openharmony/app_samples/tree/master/device/Screen) +- [`Screen`：屏幕属性（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/Screen) diff --git a/zh-cn/application-dev/windowmanager/screenshot-guidelines.md b/zh-cn/application-dev/windowmanager/screenshot-guidelines.md index 443921c936adaefc3d9b4252d6e73c1b5600c559..cc27b62c6536f274e3657d65e140cfdc6aa224d7 100644 --- a/zh-cn/application-dev/windowmanager/screenshot-guidelines.md +++ b/zh-cn/application-dev/windowmanager/screenshot-guidelines.md @@ -37,5 +37,5 @@ screenshot.save(ScreenshotOptions).then((image) => { ``` ## 相关实例 针对屏幕截图开发，有以下相关实例可供参考： -- [`Screenshot`：屏幕截图（eTS）（API9）](https://gitee.com/openharmony/app_samples/tree/master/Basic/Screenshot) +- [`Screenshot`：屏幕截图（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/Basic/Screenshot) diff --git a/zh-cn/application-dev/windowmanager/window-overview.md b/zh-cn/application-dev/windowmanager/window-overview.md index 982f9e6132e5e0029eea8a08cbb2285b69d51285..66592376084eccb141fa6399d9e116386bd24a5d 100644 --- a/zh-cn/application-dev/windowmanager/window-overview.md +++ b/zh-cn/application-dev/windowmanager/window-overview.md @@ -46,7 +46,7 @@ OpenHarmony的窗口模块将窗口界面分为系统窗口、应用窗口两种 - 应用子窗口 - ​ 应用子窗口用于显示应用的弹窗、悬浮窗等辅助窗口，不会在"任务管理界面"显示 + ​ 应用子窗口用于显示应用的弹窗、悬浮窗等辅助窗口，不会在"任务管理界面"显示。 diff --git a/zh-cn/contribute/style-guide/style-guide-content-elements.md b/zh-cn/contribute/style-guide/style-guide-content-elements.md index b984629d236de6c4015dd4b7769077b4a6842011..6e4df91da149ba948da02bdc58abdcb0630ffc6a 100755 --- a/zh-cn/contribute/style-guide/style-guide-content-elements.md +++ b/zh-cn/contribute/style-guide/style-guide-content-elements.md @@ -32,6 +32,10 @@ 【规则】表格至少为两行两列。 +【规则】表格行数（Rows）应≤9行，列数（Columns）应≤4列，推荐2～3列。大于4列的表格需要拆分或将列内容合并，以减少列数；也可采用项目列表等形式改写。每个单元格中，内容所占行数不宜超过5行。 + +【规则】Markdown中，如果表格预览效果不佳，请采用减少列数、减少单元格内容中单个英文字符串长度、或将表格改写为项目列表等方式调整，以免影响可读性。 + 【规则】相同类型的表标题、表头，风格保持一致，采用名词或名词词组的形式。 同样对参数进行说明的表，不应出现“参数说明”、“参数解释”、“参数含义”、“参数意义”等不同的表头内容，需要全文保持统一。 @@ -48,6 +52,8 @@ 【规则】表格内容默认使用左对齐。 +【建议】如果表格的列数太多而行数较少，建议把表格的列转换成行。 + ## 图片 @@ -167,6 +173,13 @@ 【规则】中文文档中，缩略语全称中对应的字母大写。 +【规则】“[OpenHarmony术语表](https://gitee.com/openharmony/docs/blob/master/zh-cn/glossary.md)”中，术语名以“英文全称 (缩略语)；中文全称”的形式写作；术语解释直接陈述术语内涵，不需要重复术语名。 + +| **正例** | **反例** | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| - Hardware Driver Foundation (HDF)；硬件驱动框架
用于提供统一外设访问能力和驱动开发、管理框架。 | - HDF
Hardware Driver Foundation，硬件驱动框架，用于提供统一外设访问能力和驱动开发、管理框架。 | +| - ArkUI；方舟开发框架
一套极简、高性能、跨设备应用设计研发的UI开发框架，支撑开发者高效地构建跨设备应用UI界面。 | - ArkUI
是一套极简、高性能、跨设备应用设计研发的UI开发框架，支撑开发者高效地构建跨设备应用UI界面。 | + 【建议】一篇文档中某缩略语首次出现的位置（标题和表头除外），提供英文全称，可选提供中文全称。 【建议】开发板名称、设备名称等不作为术语或缩略语，不在术语表中体现。建议在文档中单独以表格或其他形式介绍。 diff --git a/zh-cn/device-dev/Readme-CN.md b/zh-cn/device-dev/Readme-CN.md index cb97523cb570e086bc512dbad6970149f6af897f..08e217caed84a2b48063c1b26ba5db582ec62447 100644 --- a/zh-cn/device-dev/Readme-CN.md +++ b/zh-cn/device-dev/Readme-CN.md @@ -12,7 +12,7 @@ - [隐私与安全规范](security/Readme-CN.md) - 移植 - [轻量和小型系统三方库移植指导](porting/porting-thirdparty.md) - - [轻量系统芯片移植指导](porting/porting-minichip.md) + - [轻量系统芯片移植指导](porting/porting-minichip-overview.md) - [轻量系统芯片移植案例](porting/porting-minichip-cases.md) - [小型系统芯片移植指导](porting/porting-smallchip.md) - [标准系统芯片移植指导](porting/standard-system-porting-guide.md) @@ -56,5 +56,6 @@ - [Codelabs](https://gitee.com/openharmony/codelabs/blob/master/README.md) - 参考 - [常见问题-设备开发](faqs/Readme-CN.md) + - [HDI接口参考](reference/hdi-apis/Readme-CN.md) - 贡献 - [参与贡献](../contribute/贡献文档.md) \ No newline at end of file diff --git a/zh-cn/device-dev/device-dev-guide.md b/zh-cn/device-dev/device-dev-guide.md index 3203ed3ce6a79e5c6d0a580805c21b03bb2bfa39..df08526c33b40ca2f400b88a53c17e582c7ad349 100644 --- a/zh-cn/device-dev/device-dev-guide.md +++ b/zh-cn/device-dev/device-dev-guide.md @@ -37,11 +37,11 @@ OpenHarmony也提供了一系列可选的系统组件，方便设备开发者按 | 了解OpenHarmony | 整体认知OpenHarmony | - [OpenHarmony概述](https://gitee.com/openharmony)
- [术语](../glossary.md) | | 获取开发资源 | 准备开发前相关资源 | - [获取源码](get-code/sourcecode-acquire.md)
- [获取工具](get-code/gettools-acquire.md) | | 快速入门 | 快速熟悉OpenHarmony环境搭建、编译、烧录、调测、运行 | - [轻量和小型系统快速入门](quick-start/quickstart-ide-lite-overview.md) | -| 基础能力使用 | 使用OpenHarmony提供的基础能力 | - [轻量系统内核开发指南](kernel/kernel-mini-overview.md)
- [小型系统内核开发指南](kernel/kernel-small-overview.md)
- [驱动开发指南](driver/driver-hdf-overview.md)
- [子系统开发指南](subsystems/subsys-build-mini-lite.md)
- [安全指南](security/security-guidelines-overall.md)
- [隐私保护](security/security-privacy-protection.md) | +| 基础能力使用 | 使用OpenHarmony提供的基础能力 | - [轻量系统内核开发指南](kernel/kernel-mini-overview.md)
- [小型系统内核开发指南](kernel/kernel-small-overview.md)
- [驱动开发指南](driver/driver-hdf-overview.md)
- [子系统开发指南](subsystems/subsys-build-all.md)
- [安全指南](security/security-guidelines-overall.md)
- [隐私保护](security/security-privacy-protection.md) | | 进阶开发 | 结合系统能力开发智能设备 | - [WLAN连接类产品](guide/device-wlan-led-control.md)
- [无屏摄像头类产品](guide/device-iotcamera-control-overview.md)
- [带屏摄像头类产品](guide/device-camera-control-overview.md) | -| 移植适配 | - 针对特定芯片做移植适配
- 对三方库进行移植适配
- 三方厂商移植案例
| - [轻量系统芯片移植指导](porting/porting-minichip.md)
- [小型系统芯片移植指导](porting/porting-smallchip-prepare-needs.md)
- [轻量和小型系统三方库移植指导](porting/porting-thirdparty-overview.md)
- [带屏解决方案之恒玄芯片移植案例](porting/porting-bes2600w-on-minisystem-display-demo.md)
- [Combo解决方案之ASR芯片移植案例](porting/porting-asr582x-combo-demo.md)
- [物联网解决方案之芯海cst85芯片移植案例](porting/porting-cst85f01-combo-demo.md)
- [轻量系统STM32F407芯片移植案例](porting/porting-stm32f407-on-minisystem-eth.md)
- [Combo解决方案之W800芯片移植案例](porting/porting-w800-combo-demo.md)
- [小型设备STM32MP1芯片移植案例](porting/porting-stm32mp15xx-on-smallsystem.md)| +| 移植适配 | - 针对特定芯片做移植适配
- 对三方库进行移植适配
- 三方厂商移植案例
| - [轻量系统芯片移植指导](porting/porting-minichip-overview.md)
- [小型系统芯片移植指导](porting/porting-smallchip-prepare-needs.md)
- [轻量和小型系统三方库移植指导](porting/porting-thirdparty-overview.md)
- [带屏解决方案之恒玄芯片移植案例](porting/porting-bes2600w-on-minisystem-display-demo.md)
- [Combo解决方案之ASR芯片移植案例](porting/porting-asr582x-combo-demo.md)
- [物联网解决方案之芯海cst85芯片移植案例](porting/porting-cst85f01-combo-demo.md)
- [轻量系统STM32F407芯片移植案例](porting/porting-stm32f407-on-minisystem-eth.md)
- [Combo解决方案之W800芯片移植案例](porting/porting-w800-combo-demo.md)
- [小型设备STM32MP1芯片移植案例](porting/porting-stm32mp15xx-on-smallsystem.md)| | 贡献组件 | 为OpenHarmony贡献功能组件 | - [HPM Part 介绍](hpm-part/hpm-part-about.md)
- [HPM Part 开发指导](hpm-part/hpm-part-development.md)
- [HPM Part 参考](hpm-part/hpm-part-reference.md) | -| 参考 | 开发参考 | [常见问题](faqs/faqs-overview.md) +| 参考 | 为开发者提供常见的问题解答和HDI接口参考 | - [常见问题](faqs/faqs-overview.md)
- [HDI接口参考](reference/hdi-apis/Readme-CN.md) **表 2** 标准系统开发指导（参考内存≥128MiB） @@ -50,8 +50,8 @@ OpenHarmony也提供了一系列可选的系统组件，方便设备开发者按 | 了解OpenHarmony | 整体认知OpenHarmony | - [OpenHarmony概述](https://gitee.com/openharmony)
- [术语](../glossary.md) | | 获取开发资源 | 准备开发前相关资源 | - [获取源码](get-code/sourcecode-acquire.md)
- [获取工具](get-code/gettools-acquire.md) | | 快速入门 | 快速熟悉OpenHarmony环境搭建、编译、烧录、调测、运行 | - [标准系统快速入门](quick-start/quickstart-ide-standard-overview.md) | -| 基础能力使用 | 使用OpenHarmony提供的基础能力 | - [内核开发指南](kernel/kernel-standard.md)
- [驱动开发指南](driver/driver-hdf-overview.md)
- [子系统开发指南](subsystems/subsys-build-standard-large.md)
- [安全指南](security/security-guidelines-overall.md)
- [隐私保护](security/security-privacy-protection.md) | +| 基础能力使用 | 使用OpenHarmony提供的基础能力 | - [内核开发指南](kernel/kernel-standard.md)
- [驱动开发指南](driver/driver-hdf-overview.md)
- [子系统开发指南](subsystems/subsys-build-all.md)
- [安全指南](security/security-guidelines-overall.md)
- [隐私保护](security/security-privacy-protection.md) | | 进阶开发 | 结合系统能力开发智能设备 | - [时钟应用开发指导](guide/device-clock-guide.md)
- [平台驱动开发示例](guide/device-driver-demo.md)
- [外设驱动开发示例](guide/device-outerdriver-demo.md) | -| 移植适配 | - 针对特定芯片做移植适配
- 快速移植OpenHarmony Linux内核的方法| - [标准系统芯片移植指导](porting/standard-system-porting-guide.md)
- [一种快速移植OpenHarmony Linux内核的方法](porting/porting-linux-kernel.md) | +| 移植适配 | - 针对特定芯片做移植适配
- 快速移植OpenHarmony Linux内核的方法| - [标准系统芯片移植指导](porting/standard-system-porting-guide.md)
- [一种快速移植OpenHarmony Linux内核的方法](porting/porting-linux-kernel.md)
- [标准系统方案之瑞芯微RK3568移植案例](porting/porting-dayu200-on_standard-demo.md)| | 贡献组件 | 为OpenHarmony贡献功能组件 | - [HPM Part 介绍](hpm-part/hpm-part-about.md)
- [HPM Part 开发指导](hpm-part/hpm-part-development.md)
- [HPM Part 参考](hpm-part/hpm-part-reference.md) | -| 参考 | 开发参考 | [常见问题](faqs/faqs-overview.md) | +| 参考 | 为开发者提供常见的问题解答和HDI接口参考 | - [常见问题](faqs/faqs-overview.md)
- [HDI接口参考](reference/hdi-apis/Readme-CN.md) | diff --git a/zh-cn/device-dev/driver/driver-peripherals-pinauth-des.md b/zh-cn/device-dev/driver/driver-peripherals-pinauth-des.md index e175948b6bbade1514cb842e2c0311bb4634ad7c..e1c07b0543beb5afeda8a0a43e63decab1cb463a 100644 --- a/zh-cn/device-dev/driver/driver-peripherals-pinauth-des.md +++ b/zh-cn/device-dev/driver/driver-peripherals-pinauth-des.md @@ -95,22 +95,28 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提 以RK3568平台为例，我们提供了Pin_auth驱动DEMO实例，以下是目录结构及各部分功能简介。 -``` +```text // drivers/peripheral/pin_auth ├── BUILD.gn # 编译脚本 ├── bundle.json # 组件描述文件 +├── test # 测试用例 └── hdi_service # Pin_auth驱动实现 ├── BUILD.gn # 编译脚本 - ├── inc # 头文件 - └── src - ├── executor_impl.cpp # 认证、录入等功能接口实现 - ├── pin_auth_interface_driver.cpp # Pin_auth驱动入口 - └── pin_auth_interface_service.cpp # 获取执行器列表接口实现 + ├── adaptor # 相关算法实现 + ├── common # 公共接口实现 + ├── database # 数据库实现 + ├── main # 口令相关功能实现入口 + └── service # Pin_auth驱动实现入口 + ├── inc # 头文件 + └── src + ├── executor_impl.cpp # 认证、录入等功能接口实现 + ├── pin_auth_interface_driver.cpp # Pin_auth驱动入口 + └── pin_auth_interface_service.cpp # 获取执行器列表接口实现 ``` 下面结合DEMO实例介绍驱动开发的具体步骤。 -1. 基于HDF驱动框架，按照驱动Driver Entry程序，完成pin_auth驱动开发，主要由Bind、Init、Release、Dispatch函数接口实现，详细代码参见[pin_auth_interface_driver.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/src/pin_auth_interface_driver.cpp)文件。 +1. 基于HDF驱动框架，按照驱动Driver Entry程序，完成pin_auth驱动开发，主要由Bind、Init、Release、Dispatch函数接口实现，详细代码参见[pin_auth_interface_driver.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/service/src/pin_auth_interface_driver.cpp)文件。 ```c++ // 通过自定义的HdfPinAuthInterfaceHost对象包含IoService对象和真正的HDI Service实现PinAuthInterfaceService对象 @@ -212,7 +218,7 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提 -1. 完成获取执行器列表接口实现，详细代码参见[pin_auth_interface_service.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/src/pin_auth_interface_service.cpp)文件。 +1. 完成获取执行器列表接口实现，详细代码参见[pin_auth_interface_service.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/service/src/pin_auth_interface_service.cpp)文件。 ```c++ // 执行器实现类 @@ -285,7 +291,7 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提 -1. 完成执行器每个功能接口实现，详细代码参见[executor_impl.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/src/executor_impl.cpp)文件。 +1. 完成执行器每个功能接口实现，详细代码参见[executor_impl.cpp](https://gitee.com/openharmony/drivers_peripheral/blob/master/pin_auth/hdi_service/service/src/executor_impl.cpp)文件。 ```c++ // 实现获取执行器信息接口（仅作示例） diff --git a/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-event.md b/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-event.md index a5ef1e1b97839ab25451bd3080c0c91342bd026e..3f22c8ca8805c838933f2a66cead333a6ae34e04 100644 --- a/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-event.md +++ b/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-event.md @@ -52,6 +52,7 @@ typedef struct tagEvent { **事件销毁**：销毁指定的事件控制块。 **图1** 轻量系统事件运作原理图 + ![zh-cn_image_0000001200771972](figures/zh-cn_image_0000001200771972.png) diff --git a/zh-cn/device-dev/kernel/kernel-mini-extend-dynamic-loading.md b/zh-cn/device-dev/kernel/kernel-mini-extend-dynamic-loading.md index 22a9c5443e3a6bff91be15c204c33d583e757aba..b54322512502bdae48997ccbcc8f656db40eb0cb 100644 --- a/zh-cn/device-dev/kernel/kernel-mini-extend-dynamic-loading.md +++ b/zh-cn/device-dev/kernel/kernel-mini-extend-dynamic-loading.md @@ -63,6 +63,7 @@ Program Headers: ``` **图3** ELF文件的加载过程 + ![zh-cn_image_0000001245251887](figures/zh-cn_image_0000001245251887.png) diff --git a/zh-cn/device-dev/kernel/kernel-mini-memory-exception.md b/zh-cn/device-dev/kernel/kernel-mini-memory-exception.md index d3efbaeff1c9c45b5d0390bf448070ca47790cd2..daa581a14689a449059bfe53265b7eb3b194f1d0 100644 --- a/zh-cn/device-dev/kernel/kernel-mini-memory-exception.md +++ b/zh-cn/device-dev/kernel/kernel-mini-memory-exception.md @@ -15,6 +15,7 @@ OpenHarmony LiteOS-M提供异常接管调测手段，帮助开发者定位分析 堆栈分析原理如下图所示，实际堆栈信息根据不同CPU架构有所差异，此处仅做示意。 **图1** 堆栈分析原理示意图 + ![zh-cn_image_0000001132936268](figures/zh-cn_image_0000001132936268.png) 图中不同颜色的寄存器表示不同的函数。可以看到函数调用过程中，寄存器的保存。通过FP寄存器，栈回溯到异常函数的父函数，继续按照规律对栈进行解析，推出函数调用关系，方便用户定位问题。 diff --git a/zh-cn/device-dev/kernel/kernel-mini-overview.md b/zh-cn/device-dev/kernel/kernel-mini-overview.md index 7c27f39c9230a8443d7ff1d0d4c2000f76e047af..29fcfdf88c8ee2cfe78d2a30ed7fe17837fb6bf0 100644 --- a/zh-cn/device-dev/kernel/kernel-mini-overview.md +++ b/zh-cn/device-dev/kernel/kernel-mini-overview.md @@ -32,4 +32,5 @@ LiteOS-M已经支持ARM Cortex-M3、ARM Cortex-M4、ARM Cortex-M7、ARM Cortex-M 在开发板配置文件target_config.h配置系统时钟、每秒Tick数，可以对任务、内存、IPC、异常处理模块进行裁剪配置。系统启动时，根据配置进行指定模块的初始化。内核启动流程包含外设初始化、系统时钟配置、内核初始化、操作系统启动等，详见下图。 **图2** 内核启动流程 + ![zh-cn_image_0000001160338832](figures/zh-cn_image_0000001160338832.png) diff --git a/zh-cn/device-dev/kernel/kernel-small-basic-memory-physical.md b/zh-cn/device-dev/kernel/kernel-small-basic-memory-physical.md index 55792a35546745f8b8fd06e2d145c4684e49ae71..54ce84098a2f9e5ebb6d21b750f241a87a7b4984 100644 --- a/zh-cn/device-dev/kernel/kernel-small-basic-memory-physical.md +++ b/zh-cn/device-dev/kernel/kernel-small-basic-memory-physical.md @@ -20,6 +20,7 @@ 系统申请12KiB内存，即3个页帧时，9个内存块组中索引为3的链表挂着一块大小为8个页帧的内存块满足要求，分配出12KiB内存后还剩余20KiB内存，即5个页帧，将5个页帧分成2的幂次方之和，即4跟1，尝试查找伙伴进行合并。4个页帧的内存块没有伙伴则直接插到索引为2的链表上，继续查找1个页帧的内存块是否有伙伴，索引为0的链表上此时有1个，如果两个内存块地址连续则进行合并，并将内存块挂到索引为1的链表上，否则不做处理。 **图2** 内存申请示意图 + ![zh-cn_image_0000001189778871](figures/zh-cn_image_0000001189778871.png) - 释放内存 diff --git a/zh-cn/device-dev/kernel/kernel-small-basic-trans-event.md b/zh-cn/device-dev/kernel/kernel-small-basic-trans-event.md index a1d647c2a1fc841cd3242a0b760ea43629c17725..56737c618168cddd11a50b91dae498ecde549733 100644 --- a/zh-cn/device-dev/kernel/kernel-small-basic-trans-event.md +++ b/zh-cn/device-dev/kernel/kernel-small-basic-trans-event.md @@ -64,6 +64,7 @@ typedef struct tagEvent { **事件销毁**：销毁指定的事件控制块。 **图1** 小型系统事件运作原理图 + ![zh-cn_image_0000001180952545](figures/zh-cn_image_0000001180952545.png) diff --git a/zh-cn/device-dev/kernel/kernel-small-debug-trace-other-faqs.md b/zh-cn/device-dev/kernel/kernel-small-debug-trace-other-faqs.md index 525b873132507c485fdaa3245ee2cd3031692e61..4bfca492524d332ef0b0795ae04871a6f7f56ed1 100644 --- a/zh-cn/device-dev/kernel/kernel-small-debug-trace-other-faqs.md +++ b/zh-cn/device-dev/kernel/kernel-small-debug-trace-other-faqs.md @@ -6,6 +6,7 @@ 系统异常被挂起后，会在串口看到一些关键寄存器的信息，如图1所示。可通过这些信息定位到异常所在函数和其调用栈关系，为原因分析提供第一手资料。 **图1** 异常信息 + ![zh-cn_image_0000001153823524](figures/zh-cn_image_0000001153823524.png) 上图中的异常信息主要解释4个标签： diff --git a/zh-cn/device-dev/porting/Readme-CN.md b/zh-cn/device-dev/porting/Readme-CN.md index 8d2c217aee92178f6eb562066e5bcac3465bb7f5..e838579f9185afdb7da4a1f1028dedd48793689f 100644 --- a/zh-cn/device-dev/porting/Readme-CN.md +++ b/zh-cn/device-dev/porting/Readme-CN.md @@ -22,21 +22,18 @@ repo init -u https://gitee.com/openharmony-sig/manifest.git -b master -m devboar ## 芯片移植指导 - 轻量系统芯片移植指导 - - 移植准备 - - [移植须知](porting-chip-prepare-knows.md) - - [编译构建适配流程](porting-chip-prepare-process.md) - - 内核移植 - - [移植概述](porting-chip-kernel-overview.md) - - [内核基础适配](porting-chip-kernel-adjustment.md) - - [内核移植验证](porting-chip-kernel-verify.md) - - 板级系统移植 - - [移植概述](porting-chip-board-overview.md) - - [板级驱动适配](porting-chip-board-driver.md) - - [HAL层实现](porting-chip-board-hal.md) - - [系统组件调用](porting-chip-board-component.md) - - [lwIP组件适配](porting-chip-board-lwip.md) - - [三方组件适配](porting-chip-board-bundle.md) - - [XTS认证](porting-chip-board-xts.md) + - [概述](porting-minichip-overview.md) + - [移植准备](porting-minichip-prepare.md) + - [移植内核](porting-minichip-kernel.md) + - 移植子系统 + - [移植子系统概述](porting-minichip-subsys-overview.md) + - [移植启动恢复子系统](porting-minichip-subsys-startup.md) + - [移植文件子系统](porting-minichip-subsys-filesystem.md) + - [移植安全子系统](porting-minichip-subsys-security.md) + - [移植通信子系统](porting-minichip-subsys-communication.md) + - [移植外设驱动子系统](porting-minichip-subsys-driver.md) + - [配置其他子系统](porting-minichip-subsys-others.md) + - [移植验证](porting-minichip-verification.md) - [常见问题](porting-chip-faqs.md) - 小型系统芯片移植指导 - 移植准备 diff --git a/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378282213.png b/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378282213.png new file mode 100644 index 0000000000000000000000000000000000000000..ac8aec399dec95557fe4956a97c07d340cca37e6 Binary files /dev/null and b/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378282213.png differ diff --git a/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378481233.png b/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378481233.png new file mode 100644 index 0000000000000000000000000000000000000000..662b54c3c5549b8d473aa89c930f84d8290066b2 Binary files /dev/null and b/zh-cn/device-dev/porting/figures/zh-cn_image_0000001378481233.png differ diff --git a/zh-cn/device-dev/porting/porting-bes2600w-on-minisystem-display-demo.md b/zh-cn/device-dev/porting/porting-bes2600w-on-minisystem-display-demo.md index b02d14e5221fae86cf4479cfc784f746cd984d4e..65cc1ca22807e33a5829c2378e2b428ea2055e04 100644 --- a/zh-cn/device-dev/porting/porting-bes2600w-on-minisystem-display-demo.md +++ b/zh-cn/device-dev/porting/porting-bes2600w-on-minisystem-display-demo.md @@ -1172,12 +1172,12 @@ HiviewRegisterHilogProc(HilogProc_Impl); ``` { - "subsystem": "distributedschedule", + "subsystem": "systemabilitymgr", "components": [ { "component": "samgr_lite", "features": [ - "config_ohos_distributedschedule_samgr_lite_shared_task_size = 4096" + "config_ohos_systemabilitymgr_samgr_lite_shared_task_size = 4096" ] } ] diff --git a/zh-cn/device-dev/porting/porting-chip-board-component.md b/zh-cn/device-dev/porting/porting-chip-board-component.md index 555559cd0a9942496560fb9e811e236af7c82efb..285f3d3b146f43308fab18d4bb463ed637b42d66 100644 --- a/zh-cn/device-dev/porting/porting-chip-board-component.md +++ b/zh-cn/device-dev/porting/porting-chip-board-component.md @@ -16,7 +16,7 @@ > 本组件在板级系统移植中必须要使用，否则其他服务组件无法运行。 -**SAMGR使用说明，请参考：[SAMGR 使用指导](https://gitee.com/openharmony/distributedschedule_samgr_lite/blob/master/README_zh.md)** +**SAMGR使用说明，请参考：[SAMGR 使用指导](https://gitee.com/openharmony/systemabilitymgr_samgr_lite/blob/master/README_zh.md)** ## DFX diff --git a/zh-cn/device-dev/porting/porting-chip-board-hal.md b/zh-cn/device-dev/porting/porting-chip-board-hal.md index 64cba25738125914d680563c9be14b6b00be4e1b..fb1b6eaf0b189a9230c40e7a6bf2f985c2f157a7 100755 --- a/zh-cn/device-dev/porting/porting-chip-board-hal.md +++ b/zh-cn/device-dev/porting/porting-chip-board-hal.md @@ -23,7 +23,7 @@ HAL层主要功能是实现轻OpenHarmony与芯片的解耦，以下模块描述 **IOT外设子系统HAL层接口说明**: -需要芯片适配相关接口的实现，对芯片设备外设接口依赖请参考[IOT外设子系统的HAL头文件](https://gitee.com/openharmony/iothardware_peripheral/tree/master/interfaces/kits)。 +需要芯片适配相关接口的实现，对芯片设备外设接口依赖请参考[IOT外设子系统的HAL头文件](https://gitee.com/openharmony/iothardware_peripheral/tree/master/interfaces/inner_api)。 ## WLAN服务 diff --git a/zh-cn/device-dev/porting/porting-chip-prepare-process.md b/zh-cn/device-dev/porting/porting-chip-prepare-process.md index eee8899860e35df47baad80ef1697cf9d04b26f3..cb649cab19f41b0f72a23a2f9537e5422ed15c54 100644 --- a/zh-cn/device-dev/porting/porting-chip-prepare-process.md +++ b/zh-cn/device-dev/porting/porting-chip-prepare-process.md @@ -1,7 +1,7 @@ # 编译构建适配流程 -编译构建的详细介绍请见[编译构建子系统介绍](../subsystems/subsys-build-mini-lite.md)。新增三方芯片时，编译相关的适配流程如下： +编译构建的详细介绍请见[编译构建子系统介绍](../subsystems/subsys-build-all.md)。新增三方芯片时，编译相关的适配流程如下： ## 编译构建适配流程 diff --git a/zh-cn/device-dev/porting/porting-minichip-kernel.md b/zh-cn/device-dev/porting/porting-minichip-kernel.md new file mode 100644 index 0000000000000000000000000000000000000000..b7917d9fff8183b0721bfa750f12b52739618197 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-kernel.md @@ -0,0 +1,262 @@ +# 移植内核 + + +## 移植芯片架构 + +芯片架构的移植是内核移植的基础，在OpenHarmony中芯片架构移植是可选过程，如果当前OpenHarmony已经支持对应芯片架构则不需要移植操作，在“liteos_m/arch”目录下可看到当前已经支持的架构，如表1： + + **表1** OpenHarmony已支持的架构 + +| **系列** | **型号** | +| -------- | -------- | +| arm | arm9
cortex-m3
cortex-m4
cortex-m7
cortex-m33 | +| csky | v2 | +| risc-v | nuclei
riscv32 | +| xtensa | lx6 | + + +如果当前OpenHarmony尚未支持对应芯片架构，则需要芯片厂商自行适配，arch/include目录包含了通用的芯片架构适配所需要实现的函数。部分芯片架构代码由汇编实现，而汇编代码会因编译器的不同而不同，因此在具体的芯片架构下，还包含使用不同编译器（iar、keil、gcc等）编译的架构代码。 + + + +``` +kernel/liteos_m/arch # 不同版本路径有差异 +├── arm # arm系列 +│ ├── arm9 +│ ├── cortex-m3 +│ ├── cortex-m33 +│ │ ├── gcc # 使用gcc编译器编译的架构代码 +│ │ └── iar # 使用iar编译器编译的架构代码 +│ ├── cortex-m4 +│ ├── cortex-m7 +├── csky # csky系列 +├── include # 包含通用的芯片架构所需要实现的函数 +│ ├── los_arch.h # 定义芯片架构初始化所需要的函数 +│ ├── los_atomic.h # 定义芯片架构所需要实现的原子操作函数 +│ ├── los_context.h # 定义芯片架构所需要实现的任务上下文相关函数 +│ ├── los_interrupt.h # 定义芯片架构所需要实现的中断和异常相关的函数 +│ └── los_timer.h # 定义芯片架构所需要实现的系统时钟相关的函数 +├── risc-v # risc-v系列 +│ ├── nuclei +│ └── riscv32 +└── xtensa # xtensa系列 + └── lx6 +``` + + +## 移植芯片厂商SDK + +编译框架搭建完成后，需要将芯片厂商的SDK加入OpenHarmony编译框架，从而可以编译出带SDK的烧录文件（此时编译出的是不带系统的裸机工程），以便OpenHarmony可以调用SDK中的接口。通过以下步骤将厂商SDK加入OpenHarmony编译框架中： + +1. 将芯片厂商sdk置于device目录下合适的位置，SDK的编译脚本/镜像打包脚本整合进编译框架中。 + 参考编译脚本：“device/MyDeviceCompany/MyBoard/BUILD.gn” + + + ``` + import("//build/lite/config/component/lite_component.gni") + + executable("OHOS_Image.elf") { # 生成可执行程序 + libs = [ + "xxx/xxx/libxxx.a", # 链接厂商闭源静态库方法一 + ] + asmflags = [ # 汇编编译参数 + "", + ] + ldflags = [ + "-T./xxx/xxx/xxx.ld", # 链接脚本文件 + "-Lxxx/xxx/", # 指定厂商静态库路径 + "-lxxx", # 链接厂商闭源静态库方法二 + "-Wl,--whole-archive", + "-lmodule_xxx", + "-Wl,--no-whole-archive", + ] + deps = [ + "//build/lite:ohos", # 依赖OpenHarmony静态库编译完成，链接OpenHarmony编译出来的静态库 + ":sdk", # 依赖厂商源码静态库编译完成，链接厂商源码生成的静态库 + ] + } + + copy("prebuilt") { # 准备镜像生成工具等，一般把镜像生成工具拷贝到out目录 + sources = [ ] # 复制的源文件 + outputs = [ ] # 复制的目标文件 + } + static_library("sdk") { + sources = [ ] # 添加厂商源码编译成静态库 + include_dirs = [ ] # 厂商源码包含头文件路径 + } + build_ext_component("image") { # 调用shell命令，生成可烧写镜像文件 + exec_path = rebase_path(root_out_dir) #指定shell命令执行目录 + objcopy = "arm-none-eabi-objcopy" + objdump = "arm-none-eabi-objdump" + command = "$objcopy -O binary OHOS_Image.elf OHOS_Image.bin" + command += " && sh -c '$objdump -t OHOS_Image.elf | sort > OHOS_Image.sym.sorted'" + command += " && sh -c '$objdump -d OHOS_Image.elf > OHOS_Image.asm'" + deps = [ + ":prebuilt", # 无需准备镜像生成工具等可以删除此依赖 + ":OHOS_Image.elf", # 依赖elf文件的生成 + ] + } + group("MyBoard") { # MyBoard与当前路径名称一致 + } + ``` + + **图1** 目标的依赖执行顺序   + ![zh-cn_image_0000001378481233](figures/zh-cn_image_0000001378481233.png) + +1. 自定义芯片厂“target_config.h”文件。 + 厂商应在“device/MyDeviceCompany/MyBoard”下合适位置创建内核配置文件“target_config.h”，并根据芯片的硬件资源修改参数（具体参数介绍详见表2target_config.h文件主要配置项）。 + + 参考文件路径：“device/hisilicon/hispark_pegasus/sdk_liteos/platform/os/Huawei_LiteOS/targets/hi3861v100/include/target_config.h” + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + > 1. 若已有的配置项不能满足需求，可查看“kernel/liteos_m/kernel/include/los_config.h”，其为liteos_m内核的全量配置文件。 + > + > 2. “target_config.h”文件中出现的配置将会覆盖“los_config.h”中的配置。 + + **表2** target_config.h文件主要配置项 + + | 配置项 | 说明 | 参考值 | + | -------- | -------- | -------- | + | OS_SYS_CLOCK | 系统时钟。 | 40000000UL | + | LOSCFG_BASE_CORE_TICK_PER_SECOND | 操作系统节拍的时钟周期。 | 100UL | + | LOSCFG_BASE_CORE_TICK_HW_TIME | 定时器裁剪的外部配置项。 | YES | + | LOSCFG_PLATFORM_HWI | 是否采用接管中断的方式。 | YES | + | LOSCFG_BASE_CORE_TSK_LIMIT | 支持的最大任务个数（除去空闲任务）。 | 32 | + | LOSCFG_BASE_CORE_TSK_IDLE_STACK_SIZE | 空闲任务的堆栈大小。 | 0x180UL | + | LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE | 指定默认的任务栈大小，任务栈的大小按 8 字节大小对齐。 | 0x1000UL | + | LOSCFG_BASE_CORE_TSK_MIN_STACK_SIZE | 表示任务最小需要的堆栈大小。 | ALIGN(0x180, 4) | + | LOSCFG_BASE_CORE_TIMESLICE_TIMEOUT | 具有相同优先级任务的最长执行时间。 | 2 | + | LOSCFG_BASE_IPC_SEM_LIMIT | 最大支持信号量的个数。 | 100 | + | LOSCFG_BASE_IPC_MUX_LIMIT | 最大支持互斥量的个数。 | 64 | + | LOSCFG_BASE_IPC_QUEUE_LIMIT | 最大支持消息队列量的个数。 | 64 | + | LOSCFG_BASE_CORE_SWTMR_LIMIT | 支持的最大软件定时器数量，而不是可用的软件定时器数量。 | 80 | + | LOSCFG_BASE_MEM_NODE_SIZE_CHECK | 配置内存节点大小检查。 | NO | + | LOSCFG_PLATFORM_EXC | 异常模块配置项。 | YES | + | LOSCFG_USE_SYSTEM_DEFINED_INTERRUPT | 是否使用OS默认的中断。 | NO | + +1. 修改内核中断。 + 内核提供了两种中断修改方式： + + 1. 使用厂商默认中断。 + + 将“target_config.h”中的宏"LOSCFG_USE_SYSTEM_DEFINED_INTERRUPT"置为NO (0)，但需要在xxx.s启动文件中作以下修改: + + - PendSV_Handler：厂商sdk自带中断入口函数，需要替换为OpenHarmony的接口HalPendSV; + - SysTick_Handler：厂商sdk自带时钟中断入口函数，需要替换为OpenHarmony的接口OsTickHandler。 + + 1. 系统初始化时重定向中断。 + + 将“target_config.h”中的宏"LOSCFG_USE_SYSTEM_DEFINED_INTERRUPT"和"LOSCFG_PLATFORM_HWI"置为YES (1)。 + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + > 重定向后的中断向量表g_hwiForm需要根据arch手册要求进行字节对齐，通常0x200字节对齐。 + + +## 添加内核子系统 + +添加完内核子系统后，可以编译出带有系统的工程。通过以下步骤添加内核子系统： + +1. 在“config.json”中添加内核子系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + ``` + { + "subsystem": "kernel", # 添加内核子系统 + "components": [ + { + "component": "liteos_m", "features":[""] + } + ] + }, + ``` + +2. 开启/关闭内核特性。 + 轻量级系统的内核提供了一些特性，此步骤将指导如何查看、开启/关闭这些特性。 + + 内核特性：liteos_m提供了包括文件系统、backtrace在内的一系列内核特性开关。 + + 路径：“kernel/liteos_m/BUILD.gn” + + + ``` + declare_args() { + enable_ohos_kernel_liteos_m_cppsupport = true # cpp支持 + enable_ohos_kernel_liteos_m_cpup = true # cpu占用率支持 + enable_ohos_kernel_liteos_m_exchook = true # 异常处理支持 + enable_ohos_kernel_liteos_m_kal = true # kal接口支持 + enable_ohos_kernel_liteos_m_fs = true # 文件系统支持 + enable_ohos_kernel_liteos_m_backtrace = true # backtrace支持 + } + group("kernel") { + deps = [ + "components/bounds_checking_function:sec", + "kernel:kernel", + "utils:utils", + ] + if (enable_ohos_kernel_liteos_m_cppsupport == true) { + deps += [ "components/cppsupport:cppsupport" ] # 如果内核特性true，则会加入相应的代码进行编译 + } + …… + if (enable_ohos_kernel_liteos_m_kal == true) { + deps += [ "kal:kal" ] + } + } + ``` + + 特性：可以选择cmsis接口或者posix接口支持。 + + 路径：“kernel/liteos_m/kal/BUILD.gn” + + + ``` + declare_args() { + enable_ohos_kernel_liteos_m_cmsis = true # cmsis支持 + enable_ohos_kernel_liteos_m_posix = true # posix支持 + } + static_library("kal") { + sources = [ "kal.c" ] + if (enable_ohos_kernel_liteos_m_cmsis == true) { + deps += [ "cmsis/" ] # 如果cmsis enable，加入cmsis目录编译 + } + if (enable_ohos_kernel_liteos_m_posix == true) { + deps += [ "posix/" ] # 如果posix enable，加入posix目录编译 + } + } + ``` + + 特性：可以选择fatfs支持。 + + 路径：“kernel/liteos_m/components/fs/BUILD.gn” + + + ``` + declare_args() { + enable_ohos_kernel_liteos_m_fatfs = true # fatfs支持 + } + group("fs") { + deps = [] + if (enable_ohos_kernel_liteos_m_fatfs == true) { + deps += [ "fatfs:fatfs" ] + } + } + ``` + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + > 内核特性开关可以在具体产品模组中配置。例如关闭fs和cppsupport特性 + > + > “vendor/MyVendorCompany/MyProduct/config.json” + > + > + > ``` + > "subsystem": "kernel", + > "components": [ + > { + > "component": "liteos_m", + > "features":["enable_ohos_kernel_liteos_m_fs = false", + > "enable_ohos_kernel_liteos_m_cppsupport = false"] + > } + > ] + > } + > ``` diff --git a/zh-cn/device-dev/porting/porting-minichip-overview.md b/zh-cn/device-dev/porting/porting-minichip-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..2b0ad4f6134ff6db5ae706409705a9fa70a5bff3 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-overview.md @@ -0,0 +1,50 @@ +# 概述 + + +本文档从芯片适配的端到端视角，为芯片/模组制造商提供基于OpenHarmony的芯片适配指导。典型的芯片架构，例如cortex-m、risc-v系列都可以按照本文档进行适配移植。 + + +## 约束与限制 + +本文档适用于OpenHarmony LTS 3.0.1及之前版本的轻量系统的适配。 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本文仅对OpenHarmony移植适配过程中需要关注的文件和配置项进行介绍，其他文件以及配置项开发者无需关注，故不作详细介绍。 + + +## 适配流程 + + 主要开展基于伙伴硬件平台面向OpenHarmony系统的移植适配工作，具体细分为：移植准备、移植内核、移植子系统和移植验证四个环节，见表1芯片适配步骤。 + + **表1** 芯片适配步骤 + +| 步骤 | 介绍 | +| -------- | -------- | +| 移植准备 | 从OpenHarmony开源社区下载代码，并完成编译环境搭建，基于此初步熟悉和了解OpenHarmony的编译构建框架。 | +| 移植内核 | 将伙伴的SDK移植到OpenHarmony平台，同时根据芯片arch支持情况确认是否需要开展arch的适配工作。 | +| 移植子系统 | 开展包括启动子系统、文件子系统、安全子系统、通信子系统和外设驱动的移植。 | +| 移植验证 | 在适配完成之后使用OpenHarmony社区提供的兼容性测试套件对适配的工程进行基本接口的测试验证，同时伙伴需要使用自有测试能力对适配工程开展质量验证活动。 | + + + **图1** 业务总体流程  + + +  ![zh-cn_image_0000001378282213](figures/zh-cn_image_0000001378282213.png) + + +## 基本概念 + + **表2** 基本概念 + +| 名词 | 介绍 | +| -------- | -------- | +| 子系统 | 是一个逻辑概念，它由一个或多个具体的组件组成。OpenHarmony整体遵从分层设计，从下向上依次为：内核层、系统服务层、框架层和应用层。系统功能按照“系统 > 子系统 > 组件”逐级展开，在多设备部署场景下，支持根据实际需求裁剪某些非必要的子系统或组件。 | +| 部件 | 系统最小的可复用、可配置、可裁剪的功能单元。部件具备目录独立可并行开发、可独立编译、可独立测试的特征。 | +| hb | OpenHarmony的命令行工具，用来执行编译命令。 | +| DP平台 | Devicepartner缩写，即华为智能硬件合作伙伴平台，为生态合作伙伴提供产品开发、认证、发布等一站式服务的平台。 | +| IR平台 | Developers IssueReporter缩写，是由华为运营的、面向所有华为开发者用户的产品服务平台。 | +| HOBT | HiLink SDK OHOS Basic Test缩写，是HiLink SDK 接入 OpenHarmony的基础功能测试，检验HiLink SDK依赖的相关接口功能是否完善。 | +| Token | 伙伴从[合作伙伴平台](https://devicepartner.huawei.com/cn/)申请的设备身份凭据，每个设备唯一；需要在产线上逐个设备写入，用来标识设备是经过华为授权的。 | +| Kit Framework | Kit Framework是Kit的基础框架，包含了OpenHarmony的安全组件，不可裁剪。 | +| HiLink SDK | HarmonyOS Connect套件的一个关键组成部分，用于实现设备的联网，以及设备与HarmonyOS Connect云和智慧生活App的互联互通。 | +| kv | 键值对(key-value)，描述数据存储的格式。 | diff --git a/zh-cn/device-dev/porting/porting-minichip-prepare.md b/zh-cn/device-dev/porting/porting-minichip-prepare.md new file mode 100644 index 0000000000000000000000000000000000000000..2060fa754d05290ea298c675f1c03f0e6972dfea --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-prepare.md @@ -0,0 +1,215 @@ +# 移植准备 + + +由于OpenHarmony工程需要在Linux环境下进行编译，此章节将指导厂商搭建OpenHarmony的编译环境、获取OpenHarmony源码，并且创建厂商工作目录完成厂商芯片的编译框架适配。 + + +## 搭建编译环境 + +开展移植前请参考[开发环境准备](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/quick-start/quickstart-lite-env-setup.md)完成环境搭建工作。 + + +## 获取源码 + + +### 获取操作 + +请参考[获取源码](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/get-code/sourcecode-acquire.md)完成源码下载并进行编译。 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本文档仅适用于OpenHarmony LTS 3.0.1及之前版本，所以请获取对应版本的源码。 + + +### 目录介绍 + +OpenHarmony源码重要目录介绍见表1 OpenHarmony重要目录，其中device和vendor目录为芯片厂商和终端模组厂商工作区域（在[搭建编译框架](#搭建编译框架)部分详细介绍）。 + + **表1** OpenHarmony重要目录 + +| 目录 | 用途 | +| -------- | -------- | +| build | 编译框架所在目录。 | +| kernel/liteos_m | 内核所在的目录，其中arch目录描述支撑的内核架构。 | +| device | 芯片厂商适配目录，其中“config.gni”描述当前芯片使用的arch，工具链，编译链接选项等。 | +| vendor | 终端模组厂商适配目录，其中“config.json”描述需要集成的OpenHarmony子系统列表。 | +| utils | file，kv等相关的适配。 | + + +## 搭建编译框架 + +厂商开展移植工作时，需要在工程中按照公司名、芯片型号、开发板型号等创建工作目录，并且将所创目录加入到OpenHarmony的编译框架中，使厂商的工作目录能够参与编译，开发者可参照以下步骤进行操作。 + +1. 新增芯片厂商。 + 基于某款芯片进行OpenHarmony的适配，需要在device目录下创建芯片厂商目录，目录内文件描述内核类型，编译工具链，编译链接选项，内核配置选项等。 + + 创建目录规则：“device/{芯片厂商}/{芯片开发板}”。 + + 例：“device/MyDeviceCompany/MyBoard” + + ``` + device + ├── hisilicon # hisilicon芯片相关目录，创建目录时可供参考 + ├── MyDeviceCompany # MyDeviceCompany 芯片厂商 + │ └── MyBoard # MyBoard 芯片型号 + │ ├── BUILD.gn + │ ├── liteos_m + │ │ └── config.gni # 芯片工具链，编译链接选项 + │ └── target_config.h # 内核配置选项 + └── qemu # qemu相关 + ``` + + 编译脚本：将“device/MyDeviceCompany/MyBoard”下的文件添加到OpenHarmony编译框架中。 + + 路径：“device/MyDeviceCompany/MyBoard/BUILD.gn” + + + ``` + group("MyBoard") { #将此BUILD.gn文件加入解析 + print("MyDeviceCompany MyBoard is under developing.") + } + ``` + + 开发板编译配置：包括内核类型、工具链类型以及编译参数等内容（详见表2“config.gni”主要配置项）。 + + 路径：“device/MyDeviceCompany/MyBoard/liteos_m/config.gni” + + + ``` + # Kernel type, e.g. "linux", "liteos_a", "liteos_m". + kernel_type = "liteos_m" + + # Kernel version. + kernel_version = "" + + # Board CPU type, e.g. "cortex-a7", "riscv32". + board_cpu = "cortex-m4" + + # Board arch, e.g. "armv7-a", "rv32imac". + board_arch = "" + + # Toolchain name used for system compiling. + # E.g. gcc-arm-none-eabi, arm-linux-harmonyeabi-gcc, ohos-clang, riscv32-unknown-elf. + # Note: The default toolchain is "ohos-clang". It's not mandatory if you use the default toochain. + board_toolchain = "arm-none-eabi-gcc" + + # The toolchain path instatlled, it's not mandatory if you have added toolchian path to your ~/.bashrc. + board_toolchain_path = "" + + # Compiler prefix. + board_toolchain_prefix = "arm-none-eabi-" + + # Compiler type, "gcc" or "clang". + board_toolchain_type = "gcc" + + # Board related common compile flags. + board_cflags = [] + board_cxx_flags = board_cflags + board_ld_flags = [] + + # Board related headfiles search path. + board_include_dirs = [] + + # Board adapter dir for OHOS components. + board_adapter_dir ="" + ``` + + **表2** “config.gni”主要配置项 + + | 配置项 | 介绍 | + | -------- | -------- | + | kernel_type | 开发板使用的内核类型，例如：“liteos_a”,“liteos_m”,“linux”。 | + | kernel_version | 开发板使用的内核版本。 | + | board_cpu | 开发板CPU类型，例如：“cortex-m4”，“cortex-a7”，“riscv32”。 | + | board_arch | 开发芯片arch指令集, 例如：“armv7-a”。 | + | board_toolchain | 开发板自定义的编译工具链名称，例如：“gcc-arm-none-eabi”。若为空，则使用默认为ohos-clang。 | + | board_toolchain_path | 编译工具链路径，为空则默认使用环境变量中的工具链。 | + | board_toolchain_prefix | 编译工具链前缀，例如：“arm-none-eabi-”。 | + | board_toolchain_type | 编译工具链类型，目前支持gcc和clang。 | + | board_cflags | 开发板配置的c文件编译选项。 | + | board_cxx_flags | 开发板配置的cpp文件编译选项。 | + | board_ld_flags | 开发板配置的链接选项。 | + | board_include_dirs | 开发板配置的系统头文件路径列表。 | + | board_adapter_dir | 开发板适配文件路径。 | + +1. 新增模组终端厂商。 + 基于某款具备OpenHarmony能力的芯片进行模组终端开发，需要在vendor下创建模组厂商目录，目录内容主要是使用的OpenHarmony子系统能力。 + + 创建目录规则：“vendor/{产品模组厂商}/{产品模组名称}”。 + + 例：“vendor/MyVendorCompany/MyProduct” + + ``` + vendor + ├── hisilicon # hisilicon 产品相关目录，可供参考 + └── MyVendorCompany # MyVendorCompany 产品模组厂商 + └── MyProduct # 具体产品 + ├── BUILD.gn + └── config.json # 产品子系统列表 + ``` + + 编译脚本：将“vendor/MyVendorCompany/MyProduct/BUILD.gn”下的文件添加到OpenHarmony编译框架中。 + + 路径：“vendor/MyVendorCompany/MyProduct/BUILD.gn” + + + ``` + group("MyProduct") { + print("MyVendorCompnay MyProduct is under developing.") + } + ``` + + 产品配置信息：包括产品名、设备厂商、内核类型以及所添加的子系统列表等信息（详见表3）。 + + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + + ``` + { + "product_name": "MyProduct", + "ohos_version": "OpenHarmony 1.0", + "device_company": "MyDeviceCompany", + "board": "MyBoard", + "kernel_type": "liteos_m", + "kernel_version": "", + "subsystems": [ + { + "subsystem": "startup", + "components": [ + { "component": "bootstrap", "features":[] }, + { "component": "syspara_lite", "features": + [ + "enable_ohos_startup_syspara_lite_use_thirdparty_mbedtls = false" + ] + } + ] + } + ], + "vendor_adapter_dir": "", + "third_party_dir": "", + "product_adapter_dir": "//vendor/MyVendorCompany/MyProduct/hals", + } + ``` + + **表3** “config.json”文件配置项 + + | 配置项 | 介绍 | + | -------- | -------- | + | product_name | 产品名称，hb set时显示产品名称。 | + | ohos_version | OpenHarmony版本号，与实际版本保持一致即可。 | + | device_company | 芯片厂商名称，与device的二级目录名称一致。 | + | board | 开发板名称，与device的三级目录名称一致。 | + | kernel_type | 内核类型，应与开发板移植的OpenHarmony系统内核类型匹配。 | + | kernel_version | 内核版本号，与config.gni中kernel_version值匹配。 | + | subsystem | 产品选择的子系统，应为OS支持的子系统。子系统定义请见build/lite/components目录下的各子系统描述文件。 | + | components | 产品选择的某个子系统下的组件，子系统支持的组件详见build/lite/components/{子系统}.json文件。 | + | features | 产品配置的某个组件的特性，详见子系统源码目录对应的BUILD.gn文件。 | + | vendor_adapter_dir | 适配IOT外设，UtilsFile文件读写能力，一般指向device下目录。使用详见[文件子系统移植实例步骤2。](porting-minichip-subsys-filesystem.md#移植实例) | + | third_party_dir | 芯片厂自身三方软件目录，例如mbedtls，lwip等。如果使用OpenHarmony提供的三方软件，可暂时设空，也可参考hispark_pegasus的配置 。 | + | product_adapter_dir | 适配hal_token以及系统参数，一般指向vendor下目录。使用详见[启动恢复子系统移植实例步骤1。](porting-minichip-subsys-startup.md#移植实例) | + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + > 1. 编译构建系统会对字段进行有效性检查，其中： + > + > - device_company，board，kernel_type，kernel_version应与芯片厂商配置匹配。 + > + > - subsystem，component应与“build/lite/components”下的部件描述匹配。 diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-communication.md b/zh-cn/device-dev/porting/porting-minichip-subsys-communication.md new file mode 100644 index 0000000000000000000000000000000000000000..fe6528653500ed2c28d19f9a84a9ecc7851d1c8b --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-communication.md @@ -0,0 +1,131 @@ +# 移植通信子系统 + + +通信子系统目前涉及Wi-Fi和蓝牙适配，厂商应当根据芯片自身情况进行适配。 + + +## 移植指导 + +Wi-Fi编译文件内容如下： + + 路径：“foundation/communication/wifi_lite/BUILD.gn” + +``` +group("wifi") { + deps = [ "$ohos_board_adapter_dir/hals/communication/wifi_lite/wifiservice:wifiservice" ] +} +``` + +从中可以看到厂商适配相关接口的.c文件存放目录应为“$ohos_board_adapter_dir/hals/communication/wifi_lite/wifiservice”，且该目录下BUILD.gn文件中的目标应为“wifiservice”。需要厂商适配的Wi-Fi接口见表1 、表2 和表3，蓝牙接口见表4和表5。 + + **表1** wifi_device.h + +| 接口 | 作用 | +| -------- | -------- | +| EnableWifi | 启用Wi-Fista模式。 | +| DisableWifi | 禁用Wi-Fi sta模式。 | +| IsWifiActive | 检查Wi-Fi sta模式是否启用。 | +| Scan | 扫描热点信息。 | +| GetScanInfoList | 获取所有扫描到的热点列表。 | +| AddDeviceConfig | 配置连接到的热点信息。 | +| GetDeviceConfigs | 获取配置连接到的热点信息。 | +| RemoveDevice | 删除指定的热点配置信息。 | +| ConnectTo | 接到指定的热点。 | +| Disconnect | 断开Wi-Fi连接。 | +| GetLinkedInfo | 获取热点连接信息。 | +| RegisterWifiEvent | 为指定的Wi-Fi事件注册回调。 | +| UnRegisterWifiEvent | 取消注册以前为指定Wi-Fi事件注册的回调。 | +| GetDeviceMacAddress | 获取设备的MAC地址。 | +| AdvanceScan | 根据指定参数启动Wi-Fi扫描。 | + + **表2** wifi_hotspot_config.h + +| 文件 | 接口 | 作用 | +| -------- | -------- | -------- | +| wifi_hotspot_config.h | SetBand | 设置该热点的频段。 | +| GetBand | 获取该热点的频段。 | + + **表3** wifi_hotspot.h + +| 接口 | 作用 | +| -------- | -------- | +| EnableHotspot | 启用Ap热点模式。 | +| DisableHotspot | 禁用Ap热点模式。 | +| SetHotspotConfig | 设置指定的热点配置。 | +| GetHotspotConfig | 获取指定的热点配置。 | +| IsHotspotActive | 检查Ap热点模式是否启用。 | +| GetStationList | 获取连接到此热点的一系列STA。 | +| GetSignalLevel | 获取指定接收信号强度指示器（RSSI）和频带指示的信号电平。 | +| DisassociateSta | 使用指定的MAC地址断开与STA的连接。 | +| AddTxPowerInfo | 将hotspot功率发送到beacon。 | + + **表4** ohos_bt_gatt.h + +| 接口 | 作用 | +| -------- | -------- | +| InitBtStack | 初始化蓝牙协议栈。 | +| EnableBtStack | 使能蓝牙协议栈。 | +| DisableBtStack | 禁用蓝牙协议栈。 | +| SetDeviceName | 设置蓝牙设备名称。 | +| BleSetAdvData | 设置广播数据。 | +| BleStartAdv | 开始广播。 | +| BleStartAdvEx | 传入构建好的广播数据，参数，开启蓝牙广播。 | +| BleStopAdv | 停止发送广播。 | +| BleUpdateAdv | 更新advertising参数。 | +| BleSetSecurityIoCap | 设置蓝牙的IO能力为NONE，配对方式为justworks。 | +| BleSetSecurityAuthReq | 设置蓝牙是否需要配对绑定。 | +| BleGattSecurityRsp | 响应安全连接请求。 | +| ReadBtMacAddr | 获取设备MAC地址。 | +| BleSetScanParameters | 设置扫描参数。 | +| BleStartScan | 开始扫描。 | +| BleStopScan | 停止扫描。 | +| BleGattRegisterCallbacks | 注册gap,GATT事件回调函数。 | + + **表5** ohos_bt_gatt_server.h + +| 接口 | 作用 | +| -------- | -------- | +| BleGattsRegister | 使用指定的应用程序UUID注册GATT服务器。 | +| BleGattsUnRegister | 断开GATT服务器与客户端的连接。 | +| BleGattsDisconnect | 断开GATT服务器与客户端的连接。 | +| BleGattsAddService | 添加了一个服务。 | +| BleGattsAddIncludedService | 将包含的服务添加到指定的服务。 | +| BleGattsAddCharacteristic | 向指定的服务添加特征。 | +| BleGattsAddDescriptor | 将描述符添加到指定的特征。 | +| BleGattsStartService | 启动一个服务。 | +| BleGattsStopService | 停止服务。 | +| BleGattsDeleteService | 删除一个服务。 | +| BleGattsClearServices | 清除所有服务。 | +| BleGattsSendResponse | 向接收到读取或写入请求的客户端发送响应。 | +| BleGattsSendIndication | 设备侧向APP发送蓝牙数据。 | +| BleGattsSetEncryption | 设置GATT连接的加密类型。 | +| BleGattsRegisterCallbacks | 注册GATT服务器回调。 | +| BleGattsStartServiceEx | 根据传入的服务列表，创建gatt服务。 | +| BleGattsStopServiceEx | 传入gatt服务句柄，停止gatt服务。 | + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 不同版本接口可能存在差异，需要根据当前版本的具体文件进行适配。 + + +## 适配实例 + +1. 在“config.json”中添加iot_hardware子系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + + ``` + { + subsystem": "communication", + components": [ + { "component": "wifi_lite", "features":[] } + ] + }, + ``` + +2. 添加适配文件。 + + 在“vendor/MyVendorCompany/MyProduct/config.json”文件中，通常将配置“ohos_board_adapter_dir”配置为 “//vendor/MyVendorCompany/MyProduct/adapter”。 + + 在“ohos_board_adapter_dir”目录下根据上述适配指导中提到的头文件，适配Wi-Fi、蓝牙接口。 diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-driver.md b/zh-cn/device-dev/porting/porting-minichip-subsys-driver.md new file mode 100644 index 0000000000000000000000000000000000000000..3388b6a9045e8f7a39b8e061b072c191376f752c --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-driver.md @@ -0,0 +1,115 @@ +# 移植外设驱动子系统 + + +外设驱动子系统提供OpenHarmony专有的外部设备操作接口。本模块提供设备操作接口有：FLASH, GPIO, I2C, PWM, UART, WATCHDOG等。 + + +OpenHarmony提供了两种驱动适配方式：使用外设驱动子系统、使用HDF驱动框架。由于轻量级系统的资源有限，这里建议使用IOT子系统方式。 + + +## 移植指导 + +厂商需要根据OpenHarmony提供的接口定义实现其功能，IOT子系统接口定义的头文件如下： + + +``` +base/iot_hardware/peripheral/ +├── BUILD.gn +└── interfaces + └── kits + ├── iot_errno.h + ├── iot_flash.h + ├── iot_gpio.h + ├── iot_i2c.h + ├── iot_pwm.h + ├── iot_uart.h + ├── iot_watchdog.h + ├── lowpower.h + └── reset.h +``` + +其中“base/iot_hardware/peripheral/BUILD.gn”文件如下： + + +``` +import("//build/lite/config/subsystem/lite_subsystem.gni") +import("//build/lite/ndk/ndk.gni") + +lite_subsystem("iothardware") { + subsystem_components = [ + "$ohos_vendor_adapter_dir/hals/iot_hardware/wifiiot_lite:hal_iothardware", + ] +} +if (ohos_kernel_type == "liteos_m") { + ndk_lib("iothardware_ndk") { + deps = [ + "$ohos_vendor_adapter_dir/hals/iot_hardware/wifiiot_lite:hal_iothardware", #依赖厂商的适配 + ] + head_files = [ "//base/iot_hardware/peripheral/interfaces/kits" ] + } +} +``` + +从中可以看到厂商适配相关接口的存放目录应为“$ohos_vendor_adapter_dir/hals/iot_hardware/wifiiot_lite”，且该目录下BUILD.gn文件中的目标应为hal_iothardware。 + + +## 移植实例 + +1. 在“config.json”中添加iot_hardware子系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + + ``` + { + subsystem": "iot_hardware", + components": [ + { "component": "iot_controller", "features":[] } + ] + }, + ``` + +2. 添加适配文件。 + + 在“vendor/MyVendorCompany/MyProduct/config.json”文件中，通常将配置“vendor_adapter_dir”配置为 “//device/MyDeviceCompany/MyBoard/adapter”。 + + 在“vendor_adapter_dir”目录下进行适配： + + + ``` + hals/iot_hardware/wifiiot_lite + ├── BUILD.gn + ├── iot_flash.c + ├── iot_gpio.c + ├── iot_i2c.c + ├── iot_lowpower.c + ├── iot_pwm.c + ├── iot_reset.c + ├── iot_uart.c + └── iot_watchdog.c + ``` + + 其中BUILD.gn内容如下： + + + ``` + static_library("hal_iothardware") { #目标名 + sources = [ #厂商适配的源文件 + "iot_watchdog.c", + "iot_reset.c", + "iot_flash.c", + "iot_i2c.c", + "iot_gpio.c", + "iot_pwm.c", + "iot_uart.c" + ] + include_dirs = [ ] + } + ``` + + 其中，“include_dirs”需要根据工程实际情况包含两个路径： + + - iot子系统的头文件路径 + + - 适配iot子系统所使用到的SDK的头文件路径 diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-filesystem.md b/zh-cn/device-dev/porting/porting-minichip-subsys-filesystem.md new file mode 100644 index 0000000000000000000000000000000000000000..fc2d572e5dfcdabbcb13f5235b2a35f9b71ced5d --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-filesystem.md @@ -0,0 +1,123 @@ +# 移植文件子系统 + + +utils部件可被各业务子系统及上层应用使用，依赖芯片文件系统实现，需要芯片平台提供文件打开、关闭、读写、获取大小等功能。 + + +## 移植指导 + +OpenHarmony文件系统需要适配如下HAL层接口： + + **表1** 文件打开或关闭 + +| **接口名** | **描述** | +| -------- | -------- | +| HalFileOpen | 文件打开或创建新文件。 | +| HalFileClose | 文件关闭。 | + + **表2** 文件操作 + +| **接口名** | **描述** | +| -------- | -------- | +| HalFileRead | 读文件。 | +| HalFileWrite | 写文件。 | +| HalFileDelete | 删除文件。 | +| HalFileStat | 获取文件属性。 | +| HalFileSeek | 文件查找。 | + + 厂商适配相关接口的实现，请参考OpenHarmony中file的接口和hal层适配接口的定义： + +``` +//utils/native/lite/file +├── BUILD.gn +└── src + └── file_impl_hal + └── file.c #file接口 +``` + + +``` +//utils/native/lite/hals +└── file +└── hal_file.h #hal层接口头文件 +``` + +其中BUILD.gn的内容如下： + + +``` +import("//build/lite/config/component/lite_component.gni") + +static_library("native_file") { + sources = [ + "src/file_impl_hal/file.c", + ] + include_dirs = [ + "//utils/native/lite/include", + "//utils/native/lite/hals/file", + ] + deps = ["$ohos_vendor_adapter_dir/hals/utils/file:hal_file_static"] #依赖厂商的适配 +} + +lite_component("file") { + features = [ + ":native_file", + ] +} +``` + +从中可以看到厂商适配相关接口的存放目录应为“$ohos_vendor_adapter_dir/hals/utils/file”，且该目录下BUILD.gn文件中的目标应为hal_file_static。 + +通常厂商可以采用下面三种方式适配hal层接口： + +1. 直接flash读写，模拟文件的操作。 + +2. 使用littlefs或者fatfs文件系统进行适配，littlefs或者fatfs都是轻量级文件系统适配简单，其中OpenHarmony的“//thirdparty”目录下已有fatfs可供参考。 + +3. 使用厂商已有的文件系统进行适配。 + + +## 移植实例 + +1. “config.json”添加文件系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + ``` + { + "subsystem": "utils", + "components": [ + { "component": "file", "features":[] }, + { "component": "kv_store", "features":[] }, + { "component": "os_dump", "features":[] } + ] + }, + ``` + +2. 添加适配文件。 + 在“vendor/MyVendorCompany/MyProduct/config.json”文件中，vendor_adapter_dir配置项通常进行如下配置： + + "vendor_adapter_dir": "//device/MyDeviceCompany/MyBoard/adapter"。 + + 在该目录下进行UtilsFile接口适配： + + + ``` + hals/utils/file + ├── BUILD.gn + └── src + └── hal_file.c + ``` + + 其中BUILD.gn内容如下： + + ``` + import("//build/lite/config/component/lite_component.gni") + static_library("hal_file_static") { #目标名 + sources = [ "src/hal_file.c" ] #厂商适配的源文件 + include_dirs = [ + "//utils/native/lite/hals/file", + ] + } + ``` diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-others.md b/zh-cn/device-dev/porting/porting-minichip-subsys-others.md new file mode 100644 index 0000000000000000000000000000000000000000..6f6393089084fb14244167f87f2854a5ab4adef2 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-others.md @@ -0,0 +1,23 @@ +# 配置其他子系统 + + +除上述子系统之外，还有一些必要但是无需进行移植的子系统。如：分布式任务调度子系统、DFX子系统。 + + + 这些子系统添加方式比较简单，在“vendor/MyVendorCompany/MyProduct/config.json”文件中进行如下配置即可： + +``` +{ + "subsystem": "distributed_schedule", + "components": [ + { "component": "system_ability_manager", "features":[] } # 此处部件名不同版本可能有变化，请根据实际代码填写 + ] +}, +{ + "subsystem": "hiviewdfx", + "components": [ + { "component": "hilog_lite", "features":[] }, + { "component": "hievent_lite", "features":[] } + ] +}, +``` diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-overview.md b/zh-cn/device-dev/porting/porting-minichip-subsys-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..a42474f82ed441079af1355072b0339137f588ba --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-overview.md @@ -0,0 +1,24 @@ +# 移植子系统概述 + + +OpenHarmony系统功能按照“系统 > 子系统 > 部件”逐级展开，支持根据实际需求裁剪某些非必要的部件（本文只对HarmonyOS Connect服务包所必需的子系统、部件进行介绍）。若想使用OpenHarmony系统的能力，需要对相应子系统进行适配。 + + +OpenHarmony芯片适配常见子系统列表如下（详见表1），需结合具体芯片再做增删减操作。 + + + **表1** OpenHarmony子系统 + +| 子系统 | 作用 | +| -------- | -------- | +| applications | 应用程序demo。可将应用相关源码存放在此目录下。 | +| kernel | 内核子系统。负责任务调度、内存管理等常见的内核功能。 | +| hiviewdfx | 可维可测子系统。提供日志相关功能。 | +| communication | 通信子系统。包含Wi-Fi，蓝牙功能。 | +| iot_hardware | IOT外设子系统。提供常见的外设接口，例如GPIO，I2C，SPI等。 | +| startup | 启动子系统。内核启动后运行的第一个子系统，负责在内核启动之后到应用启动之前的系统关键进程和服务的启动过程的功能。 | +| update | 升级子系统。用来支持OpenHarmony设备的OTA升级。 | +| utils | 公共基础库子系统。提供了一些常用的C、C++开发增强API。 | +| distributed_schedule | 分布式调度子系统。负责跨设备部件管理，提供访问和控制远程组件的能力，支持分布式场景下的应用协同。 | +| security | 安全子系统。包括系统安全、数据安全、应用安全等功能，为OpenHarmony提供有效保护应用和用户数据的能力。当前开源的功能，包括应用完整性保护、应用权限管理、设备认证、密钥管理服务、数据传输管控。 | +| test | 测试子系统。OpenHarmony为开发者提供了一套全面的自测试框架，开发者可根据测试需求开发相关测试用例，开发阶段提前发现缺陷，大幅提高代码质量。 | diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-security.md b/zh-cn/device-dev/porting/porting-minichip-subsys-security.md new file mode 100644 index 0000000000000000000000000000000000000000..961d2a0d0f94a006ca7dbc848c02294c6282bb86 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-security.md @@ -0,0 +1,109 @@ +# 移植安全子系统 + + +安全子系统提供网络设备连接、认证鉴权等功能，依赖mbedtls实现硬件随机数以及联网功能。 + + +由于每个厂商芯片硬件与实现硬件随机数的方式不同，需要适配硬件随机数接口。 + + +## 移植指导 + +OpenHarmony提供了mbedtls的开源三方库，路径为“//third_party/mbedtls”。此库中提供了“mbedtls_platform_entropy_poll”、“mbedtls_hardclock_poll”、“mbedtls_havege_poll”、“mbedtls_hardware_poll”等几种产生随机数的方式。厂商需要根据芯片适配“mbedtls_hardware_poll”方式。 + + +## 移植实例 + +1. “config.json”添加文件系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + ``` + { + "subsystem": "security", + "components": [ + { "component": "hichainsdk", "features":[] }, + { "component": "huks", "features":[]} + ] + }, + ``` + +2. 配置宏，打开硬件随机数接口相关代码。 + 根据mbedtls的编译文件可以看出，配置宏的位置在"MBEDTLS_CONFIG_FILE=<../port/config/config_liteos_m.h>"文件中。 + + 路径：“third_party/mbedtls/BUILD.gn” + + + ``` + if (ohos_kernel_type == "liteos_m") { + defines += [ + "__unix__", + "MBEDTLS_CONFIG_FILE=<../port/config/config_liteos_m.h>", + ] + } + ``` + + 根据代码我们可以看出需要配置“MBEDTLS_NO_PLATFORM_ENTROPY”、“MBEDTLS_ENTROPY_HARDWARE_ALT”两个宏，才能编译硬件随机数的相关代码。 + + 路径：“third_party/mbedtls/library/entropy.c” + + + ``` + #if !defined(MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES) + #if !defined(MBEDTLS_NO_PLATFORM_ENTROPY) + mbedtls_entropy_add_source( ctx, mbedtls_platform_entropy_poll, NULL, + MBEDTLS_ENTROPY_MIN_PLATFORM, + MBEDTLS_ENTROPY_SOURCE_STRONG ); + #endif + ...... + #if defined(MBEDTLS_ENTROPY_HARDWARE_ALT) + mbedtls_entropy_add_source( ctx, mbedtls_hardware_poll, NULL, + MBEDTLS_ENTROPY_MIN_HARDWARE, + MBEDTLS_ENTROPY_SOURCE_STRONG ); + #endif + ...... + #endif /* MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES */ + } + ``` + +3. 适配硬件随机数接口 + 接口定义如下： + + 路径：“third_party/mbedtls/include/mbedtls/entropy_poll.h” + + + ``` + int mbedtls_hardware_poll( void *data,unsigned char *output, size_t len, size_t *olen ); + ``` + + + **表1** 安全子系统配置项 + +| 配置项 | 意义 | +| -------- | -------- | +| disable_huks_binary | 是否编译HUKS源码。
(1) 默认值： false，不编译HUKS源码。
(2) 其他值： true，编译HUKS源码。 | +| disable_authenticate | 是否需要裁剪hichain认证功能。
(1) 默认值： true，不裁剪。
(2) 其他值： false，裁剪hichain认证功能。 | +| huks_use_lite_storage | 是否采用轻量化存储方案。无文件系统、仅有flash存储的设备，可采用轻量化存储方案。
(1) 默认值： true，使用轻量化存储。
(2) 其他值： false，不使用轻量化存储。 | +| huks_use_hardware_root_key | 是否使用硬件根密钥。设备存在硬件根密钥能力时，需要根据自身能力适配硬件根密钥方案；HUKS提供的RKC方案仅为模拟实现。
(1) 默认值：false，默认值，默认无硬件根密钥。
(2) 其他值：true，设备具有硬件根密钥相关能力时，应自行适配。 | +| huks_config_file | 是否使用HUKS默认配置文件。
(1) 默认值：""：使用HUKS默认配置文件hks_config.h。
(2) 其他文件：产品可在HUKS支持能力集合中自行选择所要支持的特性。 | + + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 在添加安全子系统时，可直接通过配置feature来选择安全子系统特性。 +> +> +> ``` +> { +> "subsystem": "security", +> "components": [ +> { "component": "hichainsdk", "features":[] }, +> { "component": "huks", "features": +> [ +> "disable_huks_binary = false", +> "disable_authenticate = false" +> ] +> } +> ] +> }, +> ``` diff --git a/zh-cn/device-dev/porting/porting-minichip-subsys-startup.md b/zh-cn/device-dev/porting/porting-minichip-subsys-startup.md new file mode 100644 index 0000000000000000000000000000000000000000..3cf1ecc836385cd664687b226da988d0b3968054 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-subsys-startup.md @@ -0,0 +1,154 @@ +# 移植启动恢复子系统 + + +启动恢复子系统负责在内核启动之后到应用启动之前的系统关键进程和服务的启动过程的功能。 + + +## 移植指导 + +针对轻量系统主要提供了各服务和功能的启动入口标识。在SAMGR启动时，会调用bootstrap标识的入口函数，并启动系统服务。 + +适配完成后，调用OHOS_SystemInit()接口，即可启动系统。 + +路径：“base/startup/bootstrap_lite/services/source/system_init.c” + + +``` +void OHOS_SystemInit(void) +{ + MODULE_INIT(bsp); //执行.zinitcall.bspX.init段中的函数 + MODULE_INIT(device); //执行.zinitcall.deviceX.init段中的函数 + MODULE_INIT(core); //执行.zinitcall.coreX.init段中的函数 + SYS_INIT(service); //执行.zinitcall.sys.serviceX.init段中的函数 + SYS_INIT(feature); //执行.zinitcall.sys.featureX.init段中的函数 + MODULE_INIT(run); //执行.zinitcall.runX.init段中的函数 + SAMGR_Bootstrap(); //SAMGR服务初始化 +} +``` + + +## 移植实例 + +1. 在“config.json”中添加启动子系统。 + 路径：“vendor/MyVendorCompany/MyProduct/config.json” + + 修改如下： + + + ``` + { + subsystem": "startup", + components": [ + { "component": "bootstrap_lite", "features":[] }, + { "component": "syspara_lite", "features":[] } + ] + }, + ``` + + 在startup子系统中有部分部件（如：syspara_lite等），会依赖“$ohos_product_adapter_dir/utils”中的模块。其中“ohos_product_adapter_dir”就是在config.json文件中配置的“product_adapter_dir”，我们通常配置其为“vendor/MyVendorCompany/MyProduct/hals”。 + +1. 添加zinitcall以及run定义。 + 在厂商ld链接脚本中.text段中，添加如下代码： + + + ``` + __zinitcall_bsp_start = .; + KEEP (*(.zinitcall.bsp0.init)) + KEEP (*(.zinitcall.bsp1.init)) + KEEP (*(.zinitcall.bsp2.init)) + KEEP (*(.zinitcall.bsp3.init)) + KEEP (*(.zinitcall.bsp4.init)) + __zinitcall_bsp_end = .; + __zinitcall_device_start = .; + KEEP (*(.zinitcall.device0.init)) + KEEP (*(.zinitcall.device1.init)) + KEEP (*(.zinitcall.device2.init)) + KEEP (*(.zinitcall.device3.init)) + KEEP (*(.zinitcall.device4.init)) + __zinitcall_device_end = .; + __zinitcall_core_start = .; + KEEP (*(.zinitcall.core0.init)) + KEEP (*(.zinitcall.core1.init)) + KEEP (*(.zinitcall.core2.init)) + KEEP (*(.zinitcall.core3.init)) + KEEP (*(.zinitcall.core4.init)) + __zinitcall_core_end = .; + __zinitcall_sys_service_start = .; + KEEP (*(.zinitcall.sys.service0.init)) + KEEP (*(.zinitcall.sys.service1.init)) + KEEP (*(.zinitcall.sys.service2.init)) + KEEP (*(.zinitcall.sys.service3.init)) + KEEP (*(.zinitcall.sys.service4.init)) + __zinitcall_sys_service_end = .; + __zinitcall_sys_feature_start = .; + KEEP (*(.zinitcall.sys.feature0.init)) + KEEP (*(.zinitcall.sys.feature1.init)) + KEEP (*(.zinitcall.sys.feature2.init)) + KEEP (*(.zinitcall.sys.feature3.init)) + KEEP (*(.zinitcall.sys.feature4.init)) + __zinitcall_sys_feature_end = .; + __zinitcall_run_start = .; + KEEP (*(.zinitcall.run0.init)) + KEEP (*(.zinitcall.run1.init)) + KEEP (*(.zinitcall.run2.init)) + KEEP (*(.zinitcall.run3.init)) + KEEP (*(.zinitcall.run4.init)) + __zinitcall_run_end = .; + __zinitcall_app_service_start = .; //SAMGR执行.zinitcall.app.serviceX.init段中的函数 + KEEP (*(.zinitcall.app.service0.init)) + KEEP (*(.zinitcall.app.service1.init)) + KEEP (*(.zinitcall.app.service2.init)) + KEEP (*(.zinitcall.app.service3.init)) + KEEP (*(.zinitcall.app.service4.init)) + __zinitcall_app_service_end = .; + __zinitcall_app_feature_start = .; //SAMGR执行.zinitcall.app.featureX.init段中的函数 + KEEP (*(.zinitcall.app.feature0.init)) + KEEP (*(.zinitcall.app.feature1.init)) + KEEP (*(.zinitcall.app.feature2.init)) + KEEP (*(.zinitcall.app.feature3.init)) + KEEP (*(.zinitcall.app.feature4.init)) + __zinitcall_app_feature_end = .; + __zinitcall_test_start = .; + KEEP (*(.zinitcall.test0.init)) + KEEP (*(.zinitcall.test1.init)) + KEEP (*(.zinitcall.test2.init)) + KEEP (*(.zinitcall.test3.init)) + KEEP (*(.zinitcall.test4.init)) + __zinitcall_test_end = .; + __zinitcall_exit_start = .; + KEEP (*(.zinitcall.exit0.init)) + KEEP (*(.zinitcall.exit1.init)) + KEEP (*(.zinitcall.exit2.init)) + KEEP (*(.zinitcall.exit3.init)) + KEEP (*(.zinitcall.exit4.init)) + __zinitcall_exit_end = .; + ``` + +1. 芯片SDK创建任务。 + 配置任务参数，系统启动后，启动任务，示例如下： + + + ``` + void mainTask(void) { + //厂商自定义功能 + OHOS_SystemInit(); //启动子系统初始化 + printf("MainTask running...\n"); + } + + void main(VOID) { + //硬件初始化，printf输出重定向到debug串口等 + if (LOS_KernelInit() == 0) { //ohos内核初始化 + task_init_param.usTaskPrio = 10; //任务优先级 + task_init_param.pcName = "mainTask"; //任务进程名 + task_init_param.pfnTaskEntry = (TSK_ENTRY_FUNC)mainTask; //任务入口函数 + task_init_param.uwStackSize = 8192; //任务栈大小 + LOS_TaskCreate(&tid, &task_init_param); //创建任务 + LOS_Start(); //启动任务 + } + else { + printf("[BUG] LOS_KernelInit fail\n"); + } + printf("[BUG] reach to unexpected code\n"); + while (1); + } + ``` diff --git a/zh-cn/device-dev/porting/porting-minichip-verification.md b/zh-cn/device-dev/porting/porting-minichip-verification.md new file mode 100644 index 0000000000000000000000000000000000000000..66f420e385c2986c8707892ee4971afce0584fa5 --- /dev/null +++ b/zh-cn/device-dev/porting/porting-minichip-verification.md @@ -0,0 +1,88 @@ +# 移植验证 + + +OpenHarmony芯片移植完成后，需要开展OpenHarmony兼容性测试以及芯片SDK功能性测试。除可获得测试认证之外，还可以在开发阶段提前发现缺陷，大幅提高代码质量。 + + +## OpenHarmony兼容性测试 + +OpenHarmony兼容性测试是XTS（OpenHarmony生态认证测试套件）之一，详见[OpenHarmony兼容性测试](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/XTS%E5%AD%90%E7%B3%BB%E7%BB%9F.md)。 + +1. 添加test子系统以及xts_acts部件。 + 在“vendor/xxx/xxx/config.json”文件中，添加如下代码： + + + ``` + { + "subsystem": "test", + "components": [ + { "component": "xts_acts", "features":[] }, + { "component": "xts_tools", "features":[] } + ] + } + ``` + +2. 链接XTS生成的.a库。 + 在链接选项中，需要链接生成于“out/MyBoard/MyProduct/libs”目录下的XTS的.a库，其库的名称格式为libmodule_ActsXxxTest.a，链接方式为"-lmodule_ActsXxxTest",示例代码如下： + + + ``` + "-Wl,--whole-archive", + ...... + "-lhctest", + "-lbootstrap", + "-lbroadcast", + "-lmodule_ActsBootstrapTest", + "-lmodule_ActsCMSISTest", + "-lmodule_ActsDfxFuncTest", + "-lmodule_ActsParameterTest", + "-lmodule_ActsSamgrTest", + "-lmodule_ActsSecurityDataTest", + ...... + "-Wl,--no-whole-archive", + ``` + +3. 根据测试报告调整代码。 + 将编译生成的文件烧录到开发板上，使用串口工具查看xts测试报告。如果出现"failed"的测试项，则需要整改代码。 + + 定位问题时，可在“test/xts/acts/build_lite/BUILD.gn”中，将不需要的测试项注释，以便调试。 + + + ``` + if (ohos_kernel_type == "liteos_m") { + all_features += [ + "//test/xts/acts/communication_lite/lwip_hal:ActsLwipTest", + "//test/xts/acts/communication_lite/softbus_hal:ActsSoftBusTest", + "//test/xts/acts/communication_lite/wifiservice_hal:ActsWifiServiceTest", + "//test/xts/acts/utils_lite/file_hal:ActsUtilsFileTest", + "//test/xts/acts/startup_lite/syspara_hal:ActsParameterTest", + "//test/xts/acts/iot_hardware_lite/iot_controller_hal:ActsWifiIotTest", + "//test/xts/acts/kernel_lite/kernelcmsis_hal:ActsCMSISTest", + "//test/xts/acts/utils_lite/kv_store_hal:ActsKvStoreTest", + "//test/xts/acts/security_lite/datahuks_hal:ActsSecurityDataTest", + "//test/xts/acts/hiviewdfx_lite/hilog_hal:ActsDfxFuncTest", + "//test/xts/acts/distributed_schedule_lite/samgr_hal:ActsSamgrTest", + "//test/xts/acts/update_lite/updater_hal:ActsUpdaterFuncTest", + "//test/xts/acts/startup_lite/bootstrap_hal:ActsBootstrapTest", + ] + } + ``` + +> ![icon-caution.gif](public_sys-resources/icon-caution.gif) **注意：** +> 1. XTS会在OHOS_SystemInit()调用之后，自行运行测试。 +> +> 2. 需要在"-Wl,--whole-archive"和"-Wl,--no-whole-archive"中间添加，否则链接不到。 +> +> 进行XTS测试时，必须链接以下静态库 +> +> +> ``` +> "-lhctest", +> "-lbootstrap", +> "-lbroadcast", +> ``` + + +## 厂商SDK功能性测试 + +芯片移植完成后需要客户验证SDK自身功能，例如Wi-Fi，蓝牙，OTA等基础能力是否正常。 diff --git a/zh-cn/device-dev/porting/porting-smallchip-kernel-linux.md b/zh-cn/device-dev/porting/porting-smallchip-kernel-linux.md index 87af95951ca85767253b2e7be0000cd010cb77e1..f2d0b59f8c4570e217cdd1a7cafa4aa82985fd37 100644 --- a/zh-cn/device-dev/porting/porting-smallchip-kernel-linux.md +++ b/zh-cn/device-dev/porting/porting-smallchip-kernel-linux.md @@ -61,7 +61,7 @@ Linux内核移植主要涉及基于linux内核基线合入三方芯片补丁后 基于上述流程，推荐按以下步骤完成验证： 1. 制作根文件系统镜像。 - 请参考[新建芯片解决方案和产品解决方案](../subsystems/subsys-build-mini-lite.md)生成根文件系统镜像rootfs.img。从上图可以看到启动过程与产品配置强相关，在制作rootfs.img过程中请完成如下四种配置： + 请参考[新建芯片解决方案和产品解决方案](../subsystems/subsys-build-all.md)生成根文件系统镜像rootfs.img。从上图可以看到启动过程与产品配置强相关，在制作rootfs.img过程中请完成如下四种配置： - 组件配置 产品组件配置文件vendor/{company}/{product}/config.json需配置启动恢复子系统(startup)的init_lite组件和内核子系统的linux_4_1_9组件。 diff --git a/zh-cn/device-dev/porting/porting-smallchip-prepare-building.md b/zh-cn/device-dev/porting/porting-smallchip-prepare-building.md index 1a5c4104231706bbf1e1d133e18ae82504cac47f..9a1463516ad1720c7e7d53a2e755ea40a6d8058a 100644 --- a/zh-cn/device-dev/porting/porting-smallchip-prepare-building.md +++ b/zh-cn/device-dev/porting/porting-smallchip-prepare-building.md @@ -12,7 +12,7 @@ sudo apt-get install gcc-arm-linux-gnueabi ## 编译构建系统介绍 -编译构建流程、编译脚本编写、目录规则、独立编译单个组件、独立编译芯片解决方案等介绍请见[编译构建子系统介绍](../subsystems/subsys-build-mini-lite.md)。 +编译构建流程、编译脚本编写、目录规则、独立编译单个组件、独立编译芯片解决方案等介绍请见[编译构建子系统介绍](../subsystems/subsys-build-all.md)。 ## 新建芯片解决方案 diff --git a/zh-cn/device-dev/porting/porting-stm32f407-on-minisystem-eth.md b/zh-cn/device-dev/porting/porting-stm32f407-on-minisystem-eth.md index 14751be9e570c1358310f745909f635a03532f7e..703676d6ba3b81acc09f5840bb32c230efe7e565 100644 --- a/zh-cn/device-dev/porting/porting-stm32f407-on-minisystem-eth.md +++ b/zh-cn/device-dev/porting/porting-stm32f407-on-minisystem-eth.md @@ -1081,13 +1081,13 @@ bool HilogProc_Impl(const HiLogContent *hilogContent, uint32_t len) HiviewRegisterHilogProc(HilogProc_Impl); ``` -### 分布式调度子系统适配 +### 系统服务管理子系统适配 -进行分布式调度子系统适配需要添加`samgr_lite`部件，直接在`config.json`配置即可。 +进行系统服务管理子系统适配需要添加`samgr_lite`部件，直接在`config.json`配置即可。 ``` { - "subsystem": "distributedschedule", + "subsystem": "systemabilitymgr", "components": [ { "component": "samgr_lite", @@ -1097,10 +1097,10 @@ HiviewRegisterHilogProc(HilogProc_Impl); } ``` -在轻量系统中，`samgr_lite`配置的共享任务栈大小默认为`2048`。在适配时可以在features中，通过`config_ohos_distributedschedule_samgr_lite_shared_task_size`重新设置共享任务栈大小。 +在轻量系统中，`samgr_lite`配置的共享任务栈大小默认为`2048`。在适配时可以在features中，通过`config_ohos_systemabilitymgr_samgr_lite_shared_task_size`重新设置共享任务栈大小。 ``` -"config_ohos_distributedschedule_samgr_lite_shared_task_size = 4096" +"config_ohos_systemabilitymgr_samgr_lite_shared_task_size = 4096" ``` ### 安全子系统适配 diff --git a/zh-cn/device-dev/porting/porting-w800-combo-demo.md b/zh-cn/device-dev/porting/porting-w800-combo-demo.md index 09a8cce377a411f1f67a1d6cc3abeda035e5596f..e9a7b107a690a6e962f9c844b9dc7cbe441fa181 100755 --- a/zh-cn/device-dev/porting/porting-w800-combo-demo.md +++ b/zh-cn/device-dev/porting/porting-w800-combo-demo.md @@ -636,7 +636,7 @@ HDF驱动框架提供了一套应用访问硬件的统一接口，可以简化 ``` { - "subsystem": "distributedschedule", + "subsystem": "systemabilitymgr", "components": [ { "component": "samgr_lite" diff --git a/zh-cn/device-dev/quick-start/quickstart-lite-env-setup.md b/zh-cn/device-dev/quick-start/quickstart-lite-env-setup.md index ceef078f3194ff55fc38d0d5e72c186fca77e2d2..765079d9e77c7662a60a411a3172570c2f2ad2f9 100644 --- a/zh-cn/device-dev/quick-start/quickstart-lite-env-setup.md +++ b/zh-cn/device-dev/quick-start/quickstart-lite-env-setup.md @@ -322,7 +322,7 @@ bash build/prebuilts_download.sh ## 安装编译工具 -想要详细了解OpenHarmony编译构建模块功能的开发者可参考[编译构建指南](../subsystems/subsys-build-mini-lite.md)。 +想要详细了解OpenHarmony编译构建模块功能的开发者可参考[编译构建指导](../subsystems/subsys-build-all.md)。 相关操作在Ubuntu环境下进行。 diff --git a/zh-cn/device-dev/quick-start/quickstart-lite-reference.md b/zh-cn/device-dev/quick-start/quickstart-lite-reference.md index 5252016ce20ad2ad8f7ef02798b665de73a46da1..513f7e8667a3133b4cf81d275b5a38749207beea 100644 --- a/zh-cn/device-dev/quick-start/quickstart-lite-reference.md +++ b/zh-cn/device-dev/quick-start/quickstart-lite-reference.md @@ -21,7 +21,7 @@ 编译所生成的文件都归档在out/{device_name}/目录下，结果镜像输出在out/{device_name}/packages/phone/images/ 目录下。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** - > 其他模块化编译操作，可参见[编译构建指导](../subsystems/subsys-build-mini-lite.md)。 + > 其他模块化编译操作，可参见[编译构建指导](../subsystems/subsys-build-all.md)。 ## 配置代理 diff --git a/zh-cn/device-dev/quick-start/quickstart-standard-env-setup.md b/zh-cn/device-dev/quick-start/quickstart-standard-env-setup.md index e8a0a88b3abc09605eb43d1e10ba23528b05ede5..c6324c073c011fad12242d7992c57fa8f325b55f 100644 --- a/zh-cn/device-dev/quick-start/quickstart-standard-env-setup.md +++ b/zh-cn/device-dev/quick-start/quickstart-standard-env-setup.md @@ -324,7 +324,7 @@ bash build/prebuilts_download.sh ## 安装编译工具 -hb是OpenHarmony的编译工具，可通过以下步骤在Ubuntu下进行安装。想要详细了解OpenHarmony编译构建模块功能的开发者可参考[编译构建指南](../subsystems/subsys-build-standard-large.md)。 +hb是OpenHarmony的编译工具，可通过以下步骤在Ubuntu下进行安装。想要详细了解OpenHarmony编译构建模块功能的开发者可参考[编译构建指导](../subsystems/subsys-build-all.md)。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** diff --git a/zh-cn/device-dev/quick-start/quickstart-standard-reference.md b/zh-cn/device-dev/quick-start/quickstart-standard-reference.md index 8908ded0e2efd7d108be727cb1a3201429fca944..513f7e8667a3133b4cf81d275b5a38749207beea 100644 --- a/zh-cn/device-dev/quick-start/quickstart-standard-reference.md +++ b/zh-cn/device-dev/quick-start/quickstart-standard-reference.md @@ -21,7 +21,7 @@ 编译所生成的文件都归档在out/{device_name}/目录下，结果镜像输出在out/{device_name}/packages/phone/images/ 目录下。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** - > 其他模块化编译操作，可参见[编译构建指南](../subsystems/subsys-build-standard-large.md)。 + > 其他模块化编译操作，可参见[编译构建指导](../subsystems/subsys-build-all.md)。 ## 配置代理 diff --git a/zh-cn/device-dev/reference/hdi-apis/_input_dev_desc.md b/zh-cn/device-dev/reference/hdi-apis/_input_dev_desc.md index 5950fca754533fbb0f35713da421cac14917b3a5..e2fbf7cf662776f9017cf4f4d17ae6114251b435 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_input_dev_desc.md +++ b/zh-cn/device-dev/reference/hdi-apis/_input_dev_desc.md @@ -30,8 +30,8 @@ Input设备描述信息。 ### devIndex -``` -uint32_t InputHotPlugEvent::devIndex +```cpp +uint32_t InputDevDesc::devIndex ``` **描述：** @@ -42,8 +42,8 @@ uint32_t InputHotPlugEvent::devIndex ### devType -``` -uint32_t InputHotPlugEvent::devType +```cpp +uint32_t InputDevDesc::devType ``` **描述：** diff --git a/zh-cn/device-dev/reference/hdi-apis/_input_dev_identify.md b/zh-cn/device-dev/reference/hdi-apis/_input_dev_identify.md index 8520f5f62c0ef6732a00091ae3fb49a910e03632..76839b56e7950a86e5232ea388b0e92fe7e3b142 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_input_dev_identify.md +++ b/zh-cn/device-dev/reference/hdi-apis/_input_dev_identify.md @@ -18,7 +18,7 @@ | [busType](#bustype) | 总线类型 | | [vendor](#vendor) | 生产商编号 | | [product](#product) | 产品编号 | -| [fuzz](#version) | 版本号 | +| [version](#version) | 版本号 | ## **详细描述** @@ -30,7 +30,7 @@ Input设备的识别信息。 ### busType -``` +```cpp uint16_t InputDevIdentify::busType ``` @@ -40,7 +40,7 @@ uint16_t InputDevIdentify::busType ### vendor -``` +```cpp uint16_t InputDevIdentify::vendor ``` @@ -50,7 +50,7 @@ uint16_t InputDevIdentify::vendor ### product -``` +```cpp uint16_t InputDevIdentify::product ``` @@ -60,7 +60,7 @@ uint16_t InputDevIdentify::product ### version -``` +```cpp uint16_t InputDevIdentify::version ``` diff --git a/zh-cn/device-dev/reference/hdi-apis/_input_manager.md b/zh-cn/device-dev/reference/hdi-apis/_input_manager.md index c5c7016d0063c53a65567dad243381d47aca58df..6f9a062e8fc5bec538ce8dcb044c1d0eb5fd0859 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_input_manager.md +++ b/zh-cn/device-dev/reference/hdi-apis/_input_manager.md @@ -26,7 +26,7 @@ 提供Input设备管理相关的接口。 -此类接口包Input设备的扫描、打开和关闭、特定设备信息查询，以及所有设备列表信息获取等接口。 +此类接口包含Input设备的扫描、打开和关闭、特定设备信息查询，以及所有设备列表信息获取等。 ## **类成员变量说明** @@ -35,7 +35,7 @@ ### CloseInputDevice -``` +```cpp int32_t(* InputManager::CloseInputDevice) (uint32_t devIndex) ``` @@ -59,7 +59,7 @@ INPUT_SUCCESS 表示执行成功。 ### GetInputDevice -``` +```cpp int32_t(* InputManager::GetInputDevice) (uint32_t devIndex, InputDeviceInfo **devInfo) ``` @@ -84,7 +84,7 @@ INPUT_SUCCESS 表示执行成功。 ### GetInputDeviceList -``` +```cpp int32_t(* InputManager::GetInputDeviceList) (uint32_t *devNum, InputDeviceInfo **devList, uint32_t size) ``` @@ -97,7 +97,7 @@ Input服务获取所有Input设备列表的设备信息。 | 名称 | 描述 | | -------- | -------- | | devNum | 输出参数，当前已经注册过的所有Input设备的总数。 | -| devInfo | 输出参数，Input设备列表所对应的设备信息，具体参考[InputDeviceInfo](_device_info.md)。 | +| devList | 输出参数，Input设备列表所对应的设备信息，具体参考[InputDeviceInfo](_device_info.md)。 | | size | 输入参数，即指定deviceList数组对应的元素个数。| 返回： @@ -110,7 +110,7 @@ INPUT_SUCCESS 表示执行成功。 ### OpenInputDevice -``` +```cpp int32_t(* InputManager::OpenInputDevice) (uint32_t devIndex) ``` @@ -134,7 +134,7 @@ INPUT_SUCCESS 表示执行成功。 ### ScanInputDevice -``` +```cpp int32_t(* InputManager::ScanInputDevice) (InputDevDesc *staArr, uint32_t arrLen) ``` diff --git a/zh-cn/device-dev/reference/hdi-apis/_input_reporter.md b/zh-cn/device-dev/reference/hdi-apis/_input_reporter.md index a478718b007d1bed0c2646471ec92f383919faa5..c940b505e9afd0e810da168a011514479fc285d6 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_input_reporter.md +++ b/zh-cn/device-dev/reference/hdi-apis/_input_reporter.md @@ -15,9 +15,9 @@ | Public 属性 | 描述 | | -------- | -------- | -| ( [RegisterReportCallback](#registerreportcallback) )(uint32_t devIndex, [InputHostCb](_input_report_event_cb.md) \*callback) | 注册对应设备的回调函数。 [更多...](#registerreportcallback) | +| ( [RegisterReportCallback](#registerreportcallback) )(uint32_t devIndex, [InputEventCb](_input_report_event_cb.md) \*callback) | 注册对应设备的回调函数。 [更多...](#registerreportcallback) | | ( [UnregisterReportCallback](#unregisterreportcallback) )(uint32_t devIndex) | 注销对应设备的回调函数。 [更多...](#unregisterreportcallback) | -| ( [RegisterHotPlugCallback](#registerhotplugcallback) )([InputHostCb](_input_report_event_cb.md) \*callback) | 注册Input设备的热插拔回调函数。 [更多...](#registerhotplugcallback) | +| ( [RegisterHotPlugCallback](#registerhotplugcallback) )([InputHostCb](_input_host_cb.md) \*callback) | 注册Input设备的热插拔回调函数。 [更多...](#registerhotplugcallback) | | ( [UnregisterHotPlugCallback](#unregisterhotplugcallback) )(void) | 注销Input设备的热插拔回调函数。 [更多...](#unregisterhotplugcallback) | @@ -34,7 +34,7 @@ ### RegisterHotPlugCallback -``` +```cpp int32_t(* InputReporter::RegisterHotPlugCallback) (InputHostCb *callback) ``` @@ -60,7 +60,7 @@ INPUT_SUCCESS 表示执行成功。 ### RegisterReportCallback -``` +```cpp int32_t(* InputReporter::RegisterReportCallback) (uint32_t devIndex, InputEventCb *callback) ``` @@ -87,7 +87,7 @@ INPUT_SUCCESS 表示执行成功。 ### UnregisterHotPlugCallback -``` +```cpp int32_t(* InputReporter::UnregisterHotPlugCallback) (void) ``` @@ -105,7 +105,7 @@ INPUT_SUCCESS 表示执行成功。 ### UnregisterReportCallback -``` +```cpp int32_t(* InputReporter::UnregisterReportCallback) (uint32_t devIndex) ``` diff --git a/zh-cn/device-dev/subsystems/Readme-CN.md b/zh-cn/device-dev/subsystems/Readme-CN.md index 250dc3c1f243fdaaf8b6b8ea60945c3408662156..5d0b61b469c27ba8995a85cd2c060a872e8d4440 100755 --- a/zh-cn/device-dev/subsystems/Readme-CN.md +++ b/zh-cn/device-dev/subsystems/Readme-CN.md @@ -70,6 +70,7 @@ - [应用权限管理开发指导](subsys-security-rightmanagement.md) - [IPC通信鉴权开发指导](subsys-security-communicationverify.md) - [设备安全等级管理开发指导](subsys-security-devicesecuritylevel.md) + - [OpenHarmony通用密钥库系统开发](subsys-security-huks-guide.md) - 启动恢复 - [启动恢复子系统概述](subsys-boot-overview.md) - init启动引导组件 diff --git a/zh-cn/device-dev/subsystems/figures/HUKS-CertChain.png b/zh-cn/device-dev/subsystems/figures/HUKS-CertChain.png new file mode 100644 index 0000000000000000000000000000000000000000..a81932766ac032896fc88cef17c04b60a0e239ef Binary files /dev/null and b/zh-cn/device-dev/subsystems/figures/HUKS-CertChain.png differ diff --git a/zh-cn/device-dev/subsystems/figures/HUKS-GenerateKey1.png b/zh-cn/device-dev/subsystems/figures/HUKS-GenerateKey1.png new file mode 100644 index 0000000000000000000000000000000000000000..aa7f52bdcad4f589d895a6b6dbee1b0c3e0de611 Binary files /dev/null and b/zh-cn/device-dev/subsystems/figures/HUKS-GenerateKey1.png differ diff --git a/zh-cn/device-dev/subsystems/figures/HUKS-KeyBlob.png b/zh-cn/device-dev/subsystems/figures/HUKS-KeyBlob.png new file mode 100644 index 0000000000000000000000000000000000000000..c548108c0a892ce43483f132a260ac4830395604 Binary files /dev/null and b/zh-cn/device-dev/subsystems/figures/HUKS-KeyBlob.png differ diff --git a/zh-cn/device-dev/subsystems/subsys-boot-init-service.md b/zh-cn/device-dev/subsystems/subsys-boot-init-service.md index 22c8c7f5fe91b780bcfb6f4624f503ce73c6c700..65dd5a51b14e8b89510ad2677d03fef6ea92082b 100644 --- a/zh-cn/device-dev/subsystems/subsys-boot-init-service.md +++ b/zh-cn/device-dev/subsystems/subsys-boot-init-service.md @@ -55,7 +55,7 @@ ``` - SA进程按需启动 - 具体参考 **[samgr组件(说明3)](https://gitee.com/openharmony/distributedschedule_samgr/blob/master/README_zh.md)**。 + 具体参考 **[samgr组件(说明3)](https://gitee.com/openharmony/systemabilitymgr_samgr/blob/master/README_zh.md)**。 - socket进程按需启动 1. init进程在pre-fork阶段为socket类进程创建好socket，init进程中监听创建好的socket上的读写事件。 diff --git a/zh-cn/device-dev/subsystems/subsys-build-all.md b/zh-cn/device-dev/subsystems/subsys-build-all.md index f29849524414ae18d5ad033cefc184273557e288..c5b47d68a3f7f350f94a2053665242b381ae3857 100644 --- a/zh-cn/device-dev/subsystems/subsys-build-all.md +++ b/zh-cn/device-dev/subsystems/subsys-build-all.md @@ -96,7 +96,7 @@ OpenHarmony编译子系统是以GN和Ninja构建为基座，对构建和配置 ## 配置规则 -为了实现芯片解决方案、产品解决方案与OpenHarmony是解耦的、可插拔的，子系统、产品、部件、芯片解决方案、模块和特性需遵循一定的规则，具体配置规则见如下链接： +为了实现芯片解决方案、产品解决方案与OpenHarmony是解耦的、可插拔的，子系统、产品、部件、芯片解决方案、模块、特性和系统能力需遵循一定的规则，具体配置规则见如下链接： - [产品配置规则](subsys-build-product.md#产品配置规则) - [子系统配置规则](subsys-build-subsystem.md#子系统配置规则) @@ -104,6 +104,7 @@ OpenHarmony编译子系统是以GN和Ninja构建为基座，对构建和配置 - [模块配置规则](subsys-build-module.md#模块配置规则) - [芯片解决方案配置规则](subsys-build-chip_solution.md#芯片解决方案配置规则) - [特性配置规则](subsys-build-feature.md#特性配置规则) +- [系统能力配置规则](subsys-build-syscap.md#如何按需配置部件的系统能力) ## 编译构建使用指导 diff --git a/zh-cn/device-dev/subsystems/subsys-build-syscap.md b/zh-cn/device-dev/subsystems/subsys-build-syscap.md new file mode 100644 index 0000000000000000000000000000000000000000..ab7228fef270becca644264ed1c5f4eae356b489 --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-build-syscap.md @@ -0,0 +1,48 @@ +# 如何按需配置部件的系统能力 +SysCap（SystemCapability，系统能力）是部件向开发者提供的接口的集合。 +## 部件配置系统能力 +部件配置系统能力是为了方便某个特定部件是否要打开或关闭特定的系统能力。 + +部件配置系统能力的位置在部件目录下的bundle.json，配置示例如下所示： +```json + "component": { + "name": "wifi", + "subsystem": "communication", + "syscap": [ + "SystemCapability.Communication.WiFi.STA = true", + "SystemCapability.Communication.WiFi.AP = true", + "SystemCapability.Communication.WiFi.P2P = false", + "SystemCapability.Communication.WiFi.Core = false", + "SystemCapability.Communication.WiFi.HotspotExt" + ] + ], + ... + } + +``` +在component下加入关键字syscap，对内部配置相应的系统能力。系统能力若无赋值，则默认为true，若有赋值，则按实际值为准。若值为true，则表示该部件默认开启此系统能力，若值为false，则表明该部件默认关闭此系统能力。 + +以上配置表明，WIFI的STA、AP、和HotspotExt三个系统能力是打开的，而P2P和Core是关闭的。 +## 产品配置系统能力 +产品配置系统能力是为了方便某个特定产品是否要打开或关闭特定的系统能力，若无配置，则以部件侧的配置为准，产品配置系统能力的位置在vender/{company}/{product}/config.json。 + +如果要对产品的系统能力进行精细化配置，可在产品配置中加入syscap关键字，并对要配置的系统能力赋值。产品侧的配置优先级大于部件系统能力默认配置，若某一个系统能力在部件侧默认配置为false，在产品侧配置为true，则这个系统能力的最终配置为true。示例如下： +```json +{ + "subsystem": "communication", + "components": [ + ... + { + "component": "wifi", + "features": [], + "syscap": [ + "SystemCapability.Communication.WiFi.AP = false", + "SystemCapability.Communication.WiFi.P2P = true", + "SystemCapability.Communication.WiFi.HotspotExt = false" + ] + }, + ... +``` +以上配置表明，WiFi的AP和HotspotExt系统能力是关闭的，而P2P是打开的。综合部件侧的配置，最终STA、P2P为打开系统能力，而AP、Core和HotspotExt为关闭的系统能力。 +## 部件侧配置和产品侧配置的作用 +一般来说，当产品没有特性化差异的时候，我们仅需在部件侧配置系统能力，部件侧配置的系统能力是我们的基础，只有当产品存在特性化差异，需要关闭某个默认打开的系统能力或打开某个系统默认关闭的系统能力时，我们才会需要在产品侧配置。 diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hilog-lite.md b/zh-cn/device-dev/subsystems/subsys-dfx-hilog-lite.md index cefdcee926126e79d498e549114c36c5ef6a1a32..0aff60913dda95767a7e574cc882987c9148fd84 100755 --- a/zh-cn/device-dev/subsystems/subsys-dfx-hilog-lite.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hilog-lite.md @@ -46,7 +46,7 @@ HILOG_INFO/HILOG_WARN/HILOG_ERROR/HILOG_FATAL HiLogRegisterModule(HILOG_MODULE_SAMGR, "SAMGR"); ``` -3. 在GN文件中添加头文件依赖，文件路径为：“foundation/distributedschedule/samgr_lite/samgr/BUILD.gn“ +3. 在GN文件中添加头文件依赖，文件路径为：“foundation/systemabilitymgr/samgr_lite/samgr/BUILD.gn“ ``` include_dirs = [ @@ -54,7 +54,7 @@ HILOG_INFO/HILOG_WARN/HILOG_ERROR/HILOG_FATAL ] ``` -4. 源文件“foundation/distributedschedule/samgr_lite/samgr/source/message.c“中引用头文件并调用接口。 +4. 源文件“foundation/systemabilitymgr/samgr_lite/samgr/source/message.c“中引用头文件并调用接口。 ``` #include diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md index ed9ee462bc0c7aa0c55077c2e3b0f5991292147e..43b117e43bf1154da0476d90b3840ebff1c16b3d 100644 --- a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md @@ -133,7 +133,7 @@ "hitrace_native", "ipc", "safwk", - "samgr_standard", + "samgr", "utils_base" ], "third_party": [] diff --git a/zh-cn/device-dev/subsystems/subsys-security-devicesecuritylevel.md b/zh-cn/device-dev/subsystems/subsys-security-devicesecuritylevel.md index 0cfe194a07a4765701f0fa69bc5903057c2f2aaa..e5e065f7dc57ff45c57f3db4a9cb3a167ed9402e 100644 --- a/zh-cn/device-dev/subsystems/subsys-security-devicesecuritylevel.md +++ b/zh-cn/device-dev/subsystems/subsys-security-devicesecuritylevel.md @@ -34,7 +34,7 @@ OpenHarmony设备安全等级管理（DSLM）模块，负责管理各种不同 - DSLM - DSLM(Device Security Level Managerment), 是OpenHarmony设备安全等级管理的管理模块。负责各OpenHarmony设备之间的设备安全等级信息的同步和验证。并对外提供查询各设备的安全等级的接口。 + DSLM(Device Security Level Management), 是OpenHarmony设备安全等级管理的管理模块。负责各OpenHarmony设备之间的设备安全等级信息的同步和验证。并对外提供查询各设备的安全等级的接口。 ### 运作机制 @@ -44,6 +44,8 @@ OpenHarmony设备安全等级管理（DSLM）模块，负责管理各种不同 OpenHarmony设备的默认安全等级为SL1，设备制造商可以根据设备实际情况定制更高的安全等级。详细请参考章节[设备安全等级定制](#设备安全等级定制)。 +应用开发者在调试分布式业务时，如遇到因设备安全等级过低而导致数据处理或流转失败的情况时，也可以参考章节[工具使用介绍](#工具使用介绍)临时提升相关设备的安全等级。 + ## 开发指导 ### 场景介绍 @@ -109,7 +111,7 @@ OpenHarmony设备的默认安全等级为SL1，设备制造商可以根据设备 - 当目标设备的设备安全等级大于或者等于SL3时，默认允许该文件的传递。 - 当目标设备的设备安全等级小于SL3时，默认拒绝该文件的外传，同时弹框告知用户。 -1. 同步接口使用示例 +同步接口使用示例 ```cpp void CheckDestDeviceSecurityLevel(const DeviceIdentify *device, RequestOption *option) @@ -142,7 +144,7 @@ void CheckDestDeviceSecurityLevel(const DeviceIdentify *device, RequestOption *o } ``` -1. 异步接口使用示例 +异步接口使用示例 ```cpp // 回调函数 @@ -180,7 +182,7 @@ void CheckDestDeviceSecurityLevelAsync(const DeviceIdentify *device, RequestOpti } ``` -## 设备安全等级定制 +## 定制设备安全等级 ### 设备安全等级凭据 @@ -192,7 +194,7 @@ OpenHarmony的设备安全等级管理模块提供了安全等级信息同步与 设备制造商可以根据设备实际情况，参考[基本概念](#基本概念)章节的描述，修改默认的设备安全等级信息。与此同时，设备制造商还可以将OpenHarmony中的默认实现替换为更加严格的验证策略，包括但不限于采用更加精确的一机一凭据策略、从服务器定期下载更新的凭据并严格认证凭据的签发者和有效期、使用TEE(Trusted Execution Environment)甚至SE(Secure Element)对凭据文件进行进一步的签名等流程。 -### 凭据文件生成步骤 +### 生成凭据文件 凭据文件为4段BASE64编码的字符串，中间用"."链接，示例如下： @@ -427,7 +429,7 @@ eyJ0eXAiOiAiRFNMIn0=.eyJ0eXBlIjogImRlYnVnIiwgIm1hbnVmYWN0dXJlIjogIm9ob3MiLCAiYnJ 2. 凭据文件的生成： - 生成一个名为cred.txt的凭据文件，并指定设备型号为rk3568、设备版本号为3.0.0、设备安全等级为SL3等payload信息。 + 生成一个名为cred.txt的凭据文件，并指定设备型号为rk3568、设备版本号为3.0.0、设备安全等级为SL3等payload信息。 ``` undefined ./dslm_cred_tool.py create --field-manufacture OHOS --field-brand rk3568 --field-model rk3568 --field-software-version 3.0.0 --field-security-level SL3 --cred-file cred.txt @@ -467,6 +469,24 @@ eyJ0eXAiOiAiRFNMIn0=.eyJ0eXBlIjogImRlYnVnIiwgIm1hbnVmYWN0dXJlIjogIm9ob3MiLCAiYnJ verify success! ``` +4. 将生成的凭据文件推送到调试设备中并使之生效： + + 临时关闭系统写保护： + ``` undefined + hdc_std target mount + hdc_std shell "setenforce 0" + ``` + + 将刚刚生成的凭据文件推送到设备中： + ``` undefined + hdc_std file send cred.txt /system/etc/dslm_finger.cfg + ``` + + 重启设备使新的凭据文件生效： + ``` undefined + hdc_std reboot + ``` + ## 常见问题 - Q：凭据工具如何在真实的生产环境中使用？ @@ -477,6 +497,6 @@ eyJ0eXAiOiAiRFNMIn0=.eyJ0eXBlIjogImRlYnVnIiwgIm1hbnVmYWN0dXJlIjogIm9ob3MiLCAiYnJ A：我们建议设备制造商使用妥善保管的私钥对凭据文件进行签名，同时替换OpenHarmony中对于凭据文件的默认校验流程，增加对凭据签名者的严格校验。例如仅认可信任机构签发的凭据文件、增加凭据和设备ID的一对一强绑定等校验。 -## 参考资料 +- Q：OpenHarmony设备的默认安全等级为SL1，此级别偏低。导致一些分布式业务（如分布式文件系统）在处理部分敏感数据时因权限不足而失败，该如何解决？ -无 + A：请参考章节[工具使用介绍](#工具使用介绍)临时提升相关调试设备的安全等级。 diff --git a/zh-cn/device-dev/subsystems/subsys-security-huks-guide.md b/zh-cn/device-dev/subsystems/subsys-security-huks-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..009a4989cccc4f494f5f4a51cec730b07abb8d22 --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-security-huks-guide.md @@ -0,0 +1,901 @@ +# OpenHarmony通用密钥库开发指导 + +## 概述 + +### 功能简介 + +HUKS（OpenHarmony Universal KeyStore）提供系统级的密钥管理能力，实现密钥全生命周期（生成、存储、使用、销毁）的管理和安全使用，满足生态应用和上层业务的诉求。其中，密钥的安全存储和安全使用环境是密钥安全最重要的约束，如对明文密钥的存储和使用不能出现在非安全环境中，需要保证在安全环境中使用（比如TEE，安全芯片等）；本文档介绍了开发者在OpenHarmony HUKS架构的基础上适配安全存储和安全使用环境的步骤，以及如何去验证适配是否正确，以保证API接口的兼容。 + +HUKS支持密钥全生命周期管理，包括以下特性： + +1. 密钥生成/导入 + +2. 密钥存储 + +3. 密钥使用（加解密、签名验签、密钥派生、密钥协商、哈希、密钥访问控制等） + +4. 密钥销毁 + +### 基本概念 + +- 服务层（HUKS Service） + + 承载密钥管理功能的一个独立的OpenHarmony Service附属于huks_service进程，HUKS Service并不直接处理密钥运算，依赖HUKS Core为上层提供服务。 + +- 核心层（HUKS CORE） + + 提供密钥管理服务的核心功能模块，需要保证该模块处于安全环境中且密钥全生命周期明文不出HUKS Core模块。 + +- 可信执行环境（Trusted Execution Environment） + + 通过划分软件和硬件资源的方法构建一个安全区域，使得安全区域内部的程序和数据得到保护。这种划分会分隔出两个执行环境——可信执行环境和普通执行环境。每个执行环境有独立的内部数据通路和计算所需存储空间，保证可信执行环境里的信息不会向外泄露。普通执行环境的应用不能访问可信执行环境的资源，可信执行环境中的应用在没有授权的情况下也无法相互访问。 + +- 三段式（Init-Update-Finish） + + Init：初始化密钥操作数据。 + + Update：分段操作数据并返回结果，或追加数据。 + + Finish：结束分段操作或追加数据，返回结果。 + +### 实现原理 + +以密钥的生成为例介绍HUKS Service与HUKS Core的通信过程，其他密钥操作类似： +上层应用通过密钥管理SDK调用到HUKS Service，HUKS Service再调用HUKS Core，HUKS Core会调用密钥管理模块生成密钥。之后HUKS Core使用基于RootKey派生的加密密钥对生成的密钥加密再传给Service侧，Service侧再以文件形式存储加密后的密钥。 + +![HUKS密钥生成流程图](figures/HUKS-GenerateKey1.png) + +### 约束与限制 + +* HUKS的实现需要在可信执行环境中实现，保证密钥管理和操作的可信可靠。 + +* HuksHdiAttestKey返回的证书链应该按照业务证书、设备证书、CA证书和根证书的顺序组装，在每项证书之前还需要加上证书的长度。证书链组装完成后添加整个证书链的长度组装成Blob格式。证书的具体格式如要自己实现应与服务器侧解析的格式相对应。 + +![CertChain格式图](figures/HUKS-CertChain.png) + +* 接口返回的密钥必须按照密钥存储态组装成KeyBlob，哪些接口需要遵循该限制请见[接口说明](#接口说明)。 + + KeyBlob存储密钥的同时存储它的属性，结构见下图。构造KeyBlob的示例请参见[hks_keyblob.c/HksBuildKeyBlob](https://gitee.com/openharmony/security_huks/blob/master/services/huks_standard/huks_engine/main/core/src/hks_keyblob.c)。 + +![KeyBlob格式图](figures/HUKS-KeyBlob.png) + +## 开发指导 + +### 场景介绍 + +HUKS Core作为向应用提供密钥库能力的基础，包括密钥管理及密钥的密码学操作等功能。如果想要使用自己的实现替换HUKS Core，需要实现以下接口。 + +### 接口说明 + +**表1** 接口功能介绍 + +| 接口名 | 功能介绍 | 约束与限制 | 对应的js接口 | +| ------------------------------------------------------------ | ---------------------------------------- | ----------------------------- | ------------------------------------------------------------ | +| [HuksHdiModuleInit()](#hukshdimoduleinit) | HUKS Core的初始化。 | 无 | 无 | +| [HuksHdiRefresh()](#hukshdirefresh) | 刷新根密钥。 | 无 | 无 | +| [HuksHdiGenerateKey()](#hukshdigeneratekey) | 生成密钥。 | 出参要遵循KeyBlob格式 |generateKey(keyAlias: string, options: HuksOptions)| +| [HuksHdiImportKey()](#hukshdiimportkey) | 导入明文密钥。 | 出参要遵循KeyBlob格式 | importKey(keyAlias: string, options: HuksOptions)| +| [HuksHdiImportWrappedKey()](#hukshdiimportwrappedkey) |导入加密密钥。 | 出参要遵循KeyBlob格式 | importWrappedKey(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions)| +| [HuksHdiExportPublicKey()](#hukshdiexportpublickey) | 导出公钥。 |无 | exportKey(keyAlias: string, options: HuksOptions) | +| [HuksHdiInit()](#hukshdiinit) | 三段式中的Init接口。 |无 | init(keyAlias: string, options: HuksOptions) | +| [HuksHdiUpdate()](#hukshdiupdate) | 三段式中的Update接口。 |签名验签时入参是原始数据 | update(handle: number, token?: Uint8Array, options: HuksOptions) | +| [HuksHdiFinish()](#hukshdifinish) | 三段式中的Finish接口。 |签名验签时入参是签名后数据 | finish(handle: number, options: HuksOptions) | +| [HuksHdiAbort()](#hukshdiabort) | 终止三段式。 |无 | abort(handle: number, options: HuksOptions) | +| [HuksHdiGetKeyProperties()](#hukshdigetkeyproperties) | 获取密钥属性。 |无 | getKeyProperties(keyAlias: string, options: HuksOptions)| +| [HuksHdiAttestKey()](#hukshdiattestkey) | 获取密钥证书。 |出参要遵循certChain格式 | attestKey(keyAlias: string, options: HuksOptions)| + +- - - + +#### HuksHdiModuleInit + +**接口描述** + +HUKS Core的初始化，包括锁，加密算法库，authtoken key和根密钥。 + +**接口原型** +
int32_t HuksHdiModuleInit();
+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiRefresh + +**接口描述** + +刷新根密钥。 + +**接口原型** +
int32_t HuksHdiRefresh();
+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiGenerateKey + +**接口描述** + +根据paramSet生成密钥。 + +**接口原型** +
int32_t HuksHdiGenerateKey(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet, const struct HksBlob *keyIn, struct HksBlob *keyOut);
+ +
+ 参数说明 + 
+  const struct HksBlob *keyAlias
+  将要生成的密钥的别名，要求：
+  1. keyAlias != null
+  2. keyAlias -> data != null
+  3. keyAlias -> size != 0
+  


+  const struct HksParamSet *paramSet
+  要生成密钥的参数
+  


+  const struct HksBlob *keyIn
+  在agree key时使用
+  


+  struct HksBlob *keyOut
+  出参，将paramset和生成的密钥存放在这里
+
+
+

+ +
+ 约束与限制 + + 1. 请在接口内检查上述参数是否符合要求，如是否是空指针、密钥算法是否支持等。 + + 2. keyOut请参照KeyBlob的结构。 + +
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiImportKey + +**接口描述** + +导入明文密钥。 + +**接口原型** +
int32_t HuksHdiImportKey(const struct HksBlob *keyAlias, const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *keyOut);
+ +
+ 参数说明 + 
+  const struct HksBlob *msg
+  将要导入的密钥的别名，要求：
+  1. keyAlias != null
+  2. keyAlias -> data != null
+  3. keyAlias -> size != 0
+  


+  const struct HksBlob *key
+  要导入的密钥，要求：
+  1. key != null
+  2. key -> data != null
+  3. key -> size != 0
+  


+  const struct HksParamSet *paramSet
+  导入密钥的参数
+  


+  struct HksBlob *keyOut
+  出参，将paramset和生成的密钥存放在这里
+  


+
+
+

+ +
+ 约束与限制 + + 1. 请在接口内检查上述参数是否符合要求，如是否是空指针、密钥算法是否支持等。 + + 2. keyOut请参照KeyBlob的结构。 + +
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiImportWrappedKey + +**接口描述** + +导入加密密钥。 + +**接口原型** +
int32_t HuksHdiImportWrappedKey(const struct HksBlob *keyAlias, const struct HksBlob *wrappingUsedkey, const struct HksBlob *wrappedKeyData, const struct HksParamSet *paramSet, struct HksBlob *keyOut);
+ +
+ 参数说明 + 
+  const struct HksBlob *KeyAlias
+  将要导入的密钥的别名，要求：
+  1. keyAlias != null
+  2. keyAlias -> data != null
+  3. keyAlias -> size != 0
+  


+  const struct HksBlob *key
+  要导入的密钥数据被加密时使用的密钥，要求：
+  1. wrappingUsedkey != null
+  2. wrappingUsedkey -> data != null
+  3. wrappingUsedkey -> size != 0
+  


+  const struct HksBlob *wrappedKeyData
+  要导入的密钥的加密数据，要求：
+  1. wrappedKeyData != null
+  2. wrappedKeyData -> data != null
+  3. wrappedKeyData -> size != 0
+  


+  const struct HksParamSet *paramSet
+  导入密钥的参数
+  


+  struct HksBlob *keyOut
+  出参，将paramset和生成的密钥存放在这里
+
+
+

+ +
+ 约束与限制 + + 1. 请在接口内检查上述参数是否符合要求，如是否是空指针、密钥算法是否支持等。 + + 2. keyOut请参照KeyBlob的结构。 + +
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiExportPublicKey + +**接口描述** + +导出公钥。 + +**接口原型** +
int32_t HuksHdiExportPublicKey(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *keyOut);
+ +
+ 参数说明 + 
+  const struct HksBlob *key
+  与要导出的公钥对应的私钥，要求：
+  1. key != null
+  2. key -> data != null
+  3. key -> size != 0
+  


+  const struct HksParamSet *paramSet
+  空参数
+  


+  struct HksBlob *keyOut
+  出参，存放导出的公钥
+
+
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiInit + +**接口描述** + +三段式中的Init接口。 + +**接口原型** +
int32_t HuksHdiInit(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *handle, struct HksBlob *token);
+ +
+ 参数说明 + 
+  const struct HksBlob *key
+  Init操作的密钥，要求：
+  1. key != null
+  2. key -> data != null
+  3. key -> size != 0
+  


+  const struct HksParamSet *paramSet
+  Init操作的参数
+  


+  struct HksBlob *handle
+  三段式的句柄
+  


+  struct HksBlob *token
+  存放安全访问控制的challenge
+
+
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiUpdate + +**接口描述** + +三段式中的Update接口。 + +**接口原型** +
int32_t HuksHdiUpdate(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, struct HksBlob *outData);
+ +
+ 参数说明 + 
+  const struct HksBlob *handle
+  三段式的句柄
+  


+   const struct HksParamSet *paramSet
+  Update操作的参数
+  


+   const struct HksBlob *inData
+  Update操作的输入
+  


+   struct HksBlob *outData
+  Update操作的结果
+
+
+

+ +
+ 约束与限制 + + 1. 在进行签名验签时inData要传入原文数据。 + +
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiFinish + +**接口描述** + +三段式中的Finish接口。 + +**接口原型** +
int32_t HuksHdiFinish(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, struct HksBlob *outData);
+ +
+ 参数说明 + 
+  const struct HksBlob *handle
+  三段式的句柄
+  


+  const struct HksParamSet *paramSet
+  Finish操作的参数
+  


+  const struct HksBlob *inData
+  Finish操作的输入
+  


+  struct HksBlob *outData
+  Finish操作的结果
+
+
+

+ +
+ 约束与限制 + + 1. 在进行签名验签时inData要传入需要验证的签名数据，通过返回结果表示验签是否成功。 + +
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiAbort + +**接口描述** + +终止三段式。当Init，Update和Finish操作中的任一阶段发生错误时，都要调用abort来终止密钥的使用。 + +**接口原型** +
int32_t HuksHdiAbort(const struct HksBlob *handle, const struct HksParamSet *paramSet);
+ +
+ 参数说明 + 
+  const struct HksBlob *handle
+  三段式的句柄
+  


+  const struct HksParamSet *paramSet
+  Abort操作的参数
+
+
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiGetKeyProperties + +**接口描述** + +获取密钥属性。 + +**接口原型** +
int32_t HuksHdiGetKeyProperties(const struct HksParamSet *paramSet, const struct HksBlob *key);
+ +
+ 参数说明 + 
+  const struct HksParamSet *paramSet
+  空对象
+  


+  const struct HksBlob *key
+  要获取属性的密钥
+
+
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +#### HuksHdiAttestKey + +**接口描述** + +获取密钥证书。 + +**接口原型** +
int32_t (*HuksHdiAttestKey)(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *certChain);
+ +
+ 参数说明 + 
+  const struct HksBlob *key
+  要获取证书的密钥
+  


+  const struct HksParamSet *paramSet
+  获取证书操作的参数
+  


+  struct HksBlob *certChain
+  出参，存放证书
+
+
+

+ +
+ 约束与限制 + + 1. certChain的格式需遵循[约束与限制第二点](#约束与限制)。 + +
+

+ +
+ 返回值 + + - HKS_SUCCESS：成功 + + - 其他：失败 +
+ +- - - + +### 开发步骤 + +HDI接口到HUKS Core的适配在以下目录中： + +```undefined +// base/security/user_auth/services/huks_standard/huks_engine/main +├── BUILD.gn # 编译脚本 +├── core_dependency # 实现依赖 +└── core # HUKS Core层的软实现 + ├── BUILD.gn # 编译脚本 + ├── include + └── src + ├── hks_core_interfaces.c # HDI到HUKS Core的适配层 + └── hks_core_service.c # 具体实现 + └── ... #其他功能代码 +``` + +关于HUKS Core接口的具体实现，开发者必须采用三段式。以下是三段式的开发步骤以及HUKS CORE的代码示例，开发者应参考以下代码实现所有的Hdi接口。 + +其他HUKS Core接口的代码可以参考[hks_core_service.c](https://gitee.com/openharmony/security_huks/blob/master/services/huks_standard/huks_engine/main/core/src/hks_core_service.c)文件。 + +1. 创建一个句柄，通过这个句柄在session中存储密钥操作相关的信息，使得外部可以通过这个句柄分多次进行同一密钥操作。 + + ```c + + //三段式Init接口 + + int32_t HksCoreInit(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *handle, + struct HksBlob *token) + { + HKS_LOG_D("HksCoreInit in Core start"); + uint32_t pur = 0; + uint32_t alg = 0; + //检查参数 + if (key == NULL || paramSet == NULL || handle == NULL || token == NULL) { + HKS_LOG_E("the pointer param entered is invalid"); + return HKS_FAILURE; + } + + if (handle->size < sizeof(uint64_t)) { + HKS_LOG_E("handle size is too small, size : %u", handle->size); + return HKS_ERROR_INSUFFICIENT_MEMORY; + } + //解密密钥文件 + struct HuksKeyNode *keyNode = HksCreateKeyNode(key, paramSet); + if (keyNode == NULL || handle == NULL) { + HKS_LOG_E("the pointer param entered is invalid"); + return HKS_ERROR_BAD_STATE; + } + //通过handle向session中存储信息，供Update/Finish使用。使得外部可以通过同个handle分多次进行同一密钥操作。 + handle->size = sizeof(uint64_t); + (void)memcpy_s(handle->data, handle->size, &(keyNode->handle), handle->size); + //从参数中提取出算法 + int32_t ret = GetPurposeAndAlgorithm(paramSet, &pur, &alg); + if (ret != HKS_SUCCESS) { + HksDeleteKeyNode(keyNode->handle); + return ret; + } + //检查密钥参数 + ret = HksCoreSecureAccessInitParams(keyNode, paramSet, token); + if (ret != HKS_SUCCESS) { + HKS_LOG_E("init secure access params failed"); + HksDeleteKeyNode(keyNode->handle); + return ret; + } + //通过密钥使用目的获取对应的算法库处理函数 + uint32_t i; + uint32_t size = HKS_ARRAY_SIZE(g_hksCoreInitHandler); + for (i = 0; i < size; i++) { + if (g_hksCoreInitHandler[i].pur == pur) { + HKS_LOG_E("Core HksCoreInit [pur] = %d, pur = %d", g_hksCoreInitHandler[i].pur, pur); + ret = g_hksCoreInitHandler[i].handler(keyNode, paramSet, alg); + break; + } + } + //异常结果检查 + if (ret != HKS_SUCCESS) { + HksDeleteKeyNode(keyNode->handle); + HKS_LOG_E("CoreInit failed, ret : %d", ret); + return ret; + } + + if (i == size) { + HksDeleteKeyNode(keyNode->handle); + HKS_LOG_E("don't found purpose, pur : %u", pur); + return HKS_FAILURE; + } + + HKS_LOG_D("HksCoreInit in Core end"); + return ret; + } + ``` + +2. 在执行密钥操作前通过句柄获得上下文信息，执行密钥操作时放入分片数据并取回密钥操作结果或者追加数据。 + + ```c + //三段式Update接口 + int32_t HksCoreUpdate(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, + struct HksBlob *outData) + { + HKS_LOG_D("HksCoreUpdate in Core start"); + uint32_t pur = 0; + uint32_t alg = 0; + //检查参数 + if (handle == NULL || paramSet == NULL || inData == NULL) { + HKS_LOG_E("the pointer param entered is invalid"); + return HKS_FAILURE; + } + + uint64_t sessionId; + struct HuksKeyNode *keyNode = NULL; + //根据handle获取本次三段式操作需要的上下文 + int32_t ret = GetParamsForUpdateAndFinish(handle, &sessionId, &keyNode, &pur, &alg); + if (ret != HKS_SUCCESS) { + HKS_LOG_E("GetParamsForCoreUpdate failed"); + return ret; + } + //校验密钥参数 + ret = HksCoreSecureAccessVerifyParams(keyNode, paramSet); + if (ret != HKS_SUCCESS) { + HksDeleteKeyNode(sessionId); + HKS_LOG_E("HksCoreUpdate secure access verify failed"); + return ret; + } + //调用对应的算法库密钥处理函数 + uint32_t i; + uint32_t size = HKS_ARRAY_SIZE(g_hksCoreUpdateHandler); + for (i = 0; i < size; i++) { + if (g_hksCoreUpdateHandler[i].pur == pur) { + struct HksBlob appendInData = { 0, NULL }; + ret = HksCoreAppendAuthInfoBeforeUpdate(keyNode, pur, paramSet, inData, &appendInData); + if (ret != HKS_SUCCESS) { + HKS_LOG_E("before update: append auth info failed"); + break; + } + ret = g_hksCoreUpdateHandler[i].handler(keyNode, paramSet, + appendInData.data == NULL ? inData : &appendInData, outData, alg); + if (appendInData.data != NULL) { + HKS_FREE_BLOB(appendInData); + } + break; + } + } + //异常结果检查 + if (ret != HKS_SUCCESS) { + HksDeleteKeyNode(keyNode->handle); + HKS_LOG_E("CoreUpdate failed, ret : %d", ret); + return ret; + } + + if (i == size) { + HksDeleteKeyNode(sessionId); + HKS_LOG_E("don't found purpose, pur : %u", pur); + return HKS_FAILURE; + } + return ret; + } + ``` + +3. 结束密钥操作并取回结果，销毁句柄。 + + ```c + //三段式Finish接口 + int32_t HksCoreFinish(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, + struct HksBlob *outData) + { + HKS_LOG_D("HksCoreFinish in Core start"); + uint32_t pur = 0; + uint32_t alg = 0; + //检查参数 + if (handle == NULL || paramSet == NULL || inData == NULL) { + HKS_LOG_E("the pointer param entered is invalid"); + return HKS_FAILURE; + } + + uint64_t sessionId; + struct HuksKeyNode *keyNode = NULL; + //根据handle获取本次三段式操作需要的上下文 + int32_t ret = GetParamsForUpdateAndFinish(handle, &sessionId, &keyNode, &pur, &alg); + if (ret != HKS_SUCCESS) { + HKS_LOG_E("GetParamsForCoreUpdate failed"); + return ret; + } + //校验密钥参数 + ret = HksCoreSecureAccessVerifyParams(keyNode, paramSet); + if (ret != HKS_SUCCESS) { + HksDeleteKeyNode(sessionId); + HKS_LOG_E("HksCoreFinish secure access verify failed"); + return ret; + } + //调用对应的算法库密钥处理函数 + uint32_t i; + uint32_t size = HKS_ARRAY_SIZE(g_hksCoreFinishHandler); + for (i = 0; i < size; i++) { + if (g_hksCoreFinishHandler[i].pur == pur) { + uint32_t outDataBufferSize = (outData == NULL) ? 0 : outData->size; + struct HksBlob appendInData = { 0, NULL }; + ret = HksCoreAppendAuthInfoBeforeFinish(keyNode, pur, paramSet, inData, &appendInData); + if (ret != HKS_SUCCESS) { + HKS_LOG_E("before finish: append auth info failed"); + break; + } + ret = g_hksCoreFinishHandler[i].handler(keyNode, paramSet, + appendInData.data == NULL ? inData : &appendInData, outData, alg); + if (appendInData.data != NULL) { + HKS_FREE_BLOB(appendInData); + } + if (ret != HKS_SUCCESS) { + break; + } + //添加密钥操作结束标签 + ret = HksCoreAppendAuthInfoAfterFinish(keyNode, pur, paramSet, outDataBufferSize, outData); + break; + } + } + if (i == size) { + HKS_LOG_E("don't found purpose, pur : %d", pur); + ret = HKS_FAILURE; + } + //删除对应的session + HksDeleteKeyNode(sessionId); + HKS_LOG_D("HksCoreFinish in Core end"); + return ret; + } + ``` + +### 调测验证 + +开发完成后，通过[HUKS JS接口](https://gitee.com/openharmony/security_huks/blob/master/interfaces/kits/js/@ohos.security.huks.d.ts)开发JS应用来验证能力是否完备。 + +对于每个HDI接口，[接口说明](#接口说明)都提供了对应的JS接口。可以通过调用JS接口组合来验证对应的HDI接口的能力，也可以通过完整的密钥操作来验证接口的能力。 + +JS测试代码示例如下，如果整个流程能够正常运行，代表HDI接口能力正常。更多的密钥操作类型请见[huks-guidelines.md](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/huks-guidelines.md)。 + +**AES生成密钥和加密** + +1. 引入HUKS模块 + + ```js + import huks from '@ohos.security.huks' + ``` + +2. 使用generateKey接口生成密钥。 + + ```js + var alias = 'testAlias'; + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_ECC + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_224 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_AGREE + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_NONE + }; + var options = { + properties: properties + } + var resultA = huks.generateKey(alias, options); + ``` + +3. 使用Init接口进行init操作。 + + ```js + var alias = 'test001' + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_DH + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_AGREE + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_DH_KEY_SIZE_4096 + }; + var options = { + properties: properties + }; + huks.init(alias, options, function(err, data) { + if (err.code !== 0) { + console.log("test init err information: " + JSON.stringify(err)); + } else { + console.log(`test init data: ${JSON.stringify(data)}`); + } + }) + ``` + +4. 使用Update接口进行update操作。 + + ```js + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_DH + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_AGREE + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_DH_KEY_SIZE_4096 + }; + var options = { + properties: properties + }; + var result = huks.update(handle, options) + ``` + +5. 使用Finish接口进行finish操作。 + + ```js + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_DH + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_AGREE + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_DH_KEY_SIZE_4096 + }; + var options = { + properties: properties + }; + var result = huks.finish(handle, options) + ``` \ No newline at end of file diff --git a/zh-cn/device-dev/website.md b/zh-cn/device-dev/website.md index 3554669de0f544e90530523f64e038ffcfad7b69..9d5a0eafe938b8a2a99a799977150e35e36fef03 100644 --- a/zh-cn/device-dev/website.md +++ b/zh-cn/device-dev/website.md @@ -111,22 +111,18 @@ - 移植 - 轻量系统芯片移植指导 - - - 移植准备 - - [移植须知](porting/porting-chip-prepare-knows.md) - - [编译构建适配流程](porting/porting-chip-prepare-process.md) - - 内核移植 - - [移植概述](porting/porting-chip-kernel-overview.md) - - [内核基础适配](porting/porting-chip-kernel-adjustment.md) - - [内核移植验证](porting/porting-chip-kernel-verify.md) - - 板级系统移植 - - [移植概述](porting/porting-chip-board-overview.md) - - [板级驱动适配](porting/porting-chip-board-driver.md) - - [HAL层实现](porting/porting-chip-board-hal.md) - - [系统组件调用](porting/porting-chip-board-component.md) - - [lwIP组件适配](porting/porting-chip-board-lwip.md) - - [三方组件适配](porting/porting-chip-board-bundle.md) - - [XTS认证](porting/porting-chip-board-xts.md) + - [概述](porting/porting-minichip-overview.md) + - [移植准备](porting/porting-minichip-prepare.md) + - [移植内核](porting/porting-minichip-kernel.md) + - 移植子系统 + - [移植子系统概述](porting/porting-minichip-subsys-overview.md) + - [移植启动恢复子系统](porting/porting-minichip-subsys-startup.md) + - [移植文件子系统](porting/porting-minichip-subsys-filesystem.md) + - [移植安全子系统](porting/porting-minichip-subsys-security.md) + - [移植通信子系统](porting/porting-minichip-subsys-communication.md) + - [移植外设驱动子系统](porting/porting-minichip-subsys-driver.md) + - [配置其他子系统](porting/porting-minichip-subsys-others.md) + - [移植验证](porting/porting-minichip-verification.md) - [常见问题](porting/porting-chip-faqs.md) - 小型系统芯片移植指导 @@ -401,11 +397,9 @@ - [Vibrator](driver/driver-peripherals-vibrator-des.md) - [WLAN](driver/driver-peripherals-external-des.md) - 编译构建 - - [轻量和小型系统编译构建指导](subsystems/subsys-build-mini-lite.md) - - [标准系统编译构建指导](subsystems/subsys-build-standard-large.md) + - [编译构建指导](subsystems/subsys-build-all.md) - [构建系统编码规范和最佳实践指导](subsystems/subsys-build-gn-coding-style-and-best-practice.md) - [编译构建Kconfig可视化配置指导](subsystems/subsys-build-gn-kconfig-visual-config-guide.md) - - [HAP编译构建指导](subsystems/subsys-build-gn-hap-compilation-guide.md) - [分布式远程启动](subsystems/subsys-remote-start.md) - 图形图像 - [图形图像概述](subsystems/subsys-graphics-overview.md) @@ -474,7 +468,13 @@ - [设备安全等级管理开发指导](subsystems/subsys-security-devicesecuritylevel.md) - 启动恢复 - [启动恢复子系统概述](subsystems/subsys-boot-overview.md) - - [init启动引导组件](subsystems/subsys-boot-init.md) + - init启动引导组件 + - [引导启动配置文件](subsystems/subsys-boot-init-cfg.md) + - [jobs管理](subsystems/subsys-boot-init-jobs.md) + - [服务管理](subsystems/subsys-boot-init-service.md) + - [系统参数](subsystems/subsys-boot-init-sysparam.md) + - [沙盒管理](subsystems/subsys-boot-init-sandbox.md) + - [插件](subsystems/subsys-boot-init-plugin.md) - [appspawn应用孵化组件](subsystems/subsys-boot-appspawn.md) - [bootstrap服务启动组件](subsystems/subsys-boot-bootstrap.md) - [常见问题](subsystems/subsys-boot-faqs.md) diff --git "a/zh-cn/readme/AI\344\270\232\345\212\241\345\255\220\347\263\273\347\273\237.md" "b/zh-cn/readme/AI\344\270\232\345\212\241\345\255\220\347\263\273\347\273\237.md" index 50fa8c9cec1fdda474e58ebd020eaf85343af346..8e062d1450bace80dad9f071044b54c3a64b94a4 100644 --- "a/zh-cn/readme/AI\344\270\232\345\212\241\345\255\220\347\263\273\347\273\237.md" +++ "b/zh-cn/readme/AI\344\270\232\345\212\241\345\255\220\347\263\273\347\273\237.md" @@ -424,7 +424,7 @@ AI业务子系统是OpenHarmony提供原生的分布式AI能力的子系统。 [build\_lite](https://gitee.com/openharmony/build_lite/blob/master/README_zh.md) -[distributedschedule\_samgr\_lite](https://gitee.com/openharmony/distributedschedule_samgr_lite/blob/master/README_zh.md) +[systemabilitymgr\_samgr\_lite](https://gitee.com/openharmony/systemabilitymgr_samgr_lite/blob/master/README_zh.md) [startup\_init\_lite](https://gitee.com/openharmony/startup_init_lite/blob/master/README_zh.md) diff --git "a/zh-cn/readme/\347\263\273\347\273\237\346\234\215\345\212\241\347\256\241\347\220\206\345\255\220\347\263\273\347\273\237.md" "b/zh-cn/readme/\347\263\273\347\273\237\346\234\215\345\212\241\347\256\241\347\220\206\345\255\220\347\263\273\347\273\237.md" index 1e588345a38e90405827fb135df023923e2bb30f..26b7704d75d1c3ebfba4954a3cb01540528f5e66 100755 --- "a/zh-cn/readme/\347\263\273\347\273\237\346\234\215\345\212\241\347\256\241\347\220\206\345\255\220\347\263\273\347\273\237.md" +++ "b/zh-cn/readme/\347\263\273\347\273\237\346\234\215\345\212\241\347\256\241\347\220\206\345\255\220\347\263\273\347\273\237.md" @@ -21,7 +21,7 @@ ## 目录 ``` -/foundation/distributedschedule +/foundation/systemabilitymgr ├── safwk # 系统服务框架模块 ├── samgr # 系统服务管理模块 ├── safwk_lite # 轻量foundation进程 @@ -32,10 +32,10 @@ **系统服务管理子系统** -[distributedschedule\_safwk](https://gitee.com/openharmony/distributedschedule_safwk) +[systemabilitymgr\_safwk](https://gitee.com/openharmony/systemabilitymgr_safwk) -[distributedschedule\_samgr](https://gitee.com/openharmony/distributedschedule_samgr) +[systemabilitymgr\_samgr](https://gitee.com/openharmony/systemabilitymgr_samgr) -[distributedschedule\_safwk\_lite](https://gitee.com/openharmony/distributedschedule_safwk_lite) +[systemabilitymgr\_safwk\_lite](https://gitee.com/openharmony/systemabilitymgr_safwk_lite) -[distributedschedule\_samgr\_lite](https://gitee.com/openharmony/distributedschedule_samgr_lite) +[systemabilitymgr\_samgr\_lite](https://gitee.com/openharmony/systemabilitymgr_samgr_lite) diff --git a/zh-cn/release-notes/OpenHarmony-1-0.md b/zh-cn/release-notes/OpenHarmony-1-0.md index 1994214ff1e17c22858157bfaa5b67302e6952ad..10935823396f1044c333f60e313b6c7f965eccb6 100755 --- a/zh-cn/release-notes/OpenHarmony-1-0.md +++ b/zh-cn/release-notes/OpenHarmony-1-0.md @@ -1,85 +1,30 @@ -# OpenHarmony 1.0（2020-09-10） +# OpenHarmony 1.0（2020-09-10） -- [版本概述](#section249611124916) -- [版本源码获取](#section127301717165113) - - [通过镜像站点获取](#section157648475298) - - [通过repo命令获取](#section49746186307) - -## 版本概述 +## 版本概述 首次发布OpenHarmony 1.0。 -## 版本源码获取 +## 版本源码获取 -### 通过镜像站点获取 +### 通过镜像站点获取 **表 1** 源码获取路径 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

版本源码

-

版本信息

-

下载站点

-

SHA256校验码

-

全量代码

-

1.0

-

站点

-

SHA256 校验码

-

Hi3861解决方案（二进制）

-

1.0

-

站点

-

SHA256 校验码

-

Hi3518解决方案（二进制）

-

1.0

-

站点

-

SHA256 校验码

-

Hi3516解决方案（二进制）

-

1.0

-

站点

-

SHA256 校验码

-

RELEASE-NOTES

-

1.0

-

站点

-

-

-
+| 版本源码 | 版本信息 | 下载站点 | SHA256校验码 | +| ------------------------ | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 全量代码 | 1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.0/code-1.0.tar.gz) | [SHA256 校验码](https://repo.huaweicloud.com/harmonyos/os/1.0/code-1.0.tar.gz.sha256) | +| Hi3861解决方案（二进制） | 1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.0/wifiiot-1.0.tar.gz) | [SHA256 校验码](https://repo.huaweicloud.com/harmonyos/os/1.0/wifiiot-1.0.tar.gz.sha256) | +| Hi3518解决方案（二进制） | 1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.0/ipcamera_hi3518ev300-1.0.tar.gz) | [SHA256 校验码](https://repo.huaweicloud.com/harmonyos/os/1.0/ipcamera_hi3518ev300-1.0.tar.gz.sha256) | +| Hi3516解决方案（二进制） | 1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.0/ipcamera_hi3516dv300-1.0.tar.gz) | [SHA256 校验码](https://repo.huaweicloud.com/harmonyos/os/1.0/ipcamera_hi3516dv300-1.0.tar.gz.sha256) | +| RELEASE-NOTES | 1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.0/RELEASE-NOTES.txt) | - | + -### 通过repo命令获取 +### 通过repo命令获取 方式一（推荐）：通过repo下载 -``` +```shell repo init -u https://gitee.com/openharmony/manifest.git -b master --no-repo-verify repo sync -c ``` @@ -88,7 +33,6 @@ repo sync -c 进入[代码仓库主页](https://gitee.com/openharmony)，选择需要克隆的代码仓库，执行命令，如： -``` +```shell git clone https://gitee.com/openharmony/manifest.git -b master -``` - +``` \ No newline at end of file diff --git a/zh-cn/release-notes/OpenHarmony-1-1-0-LTS.md b/zh-cn/release-notes/OpenHarmony-1-1-0-LTS.md index ad84abad5fe0c7500e779451ba8cac2ad5caebdd..6d4aacf8dd8cce555537c57f891a3ac8e0302bf6 100755 --- a/zh-cn/release-notes/OpenHarmony-1-1-0-LTS.md +++ b/zh-cn/release-notes/OpenHarmony-1-1-0-LTS.md @@ -1,14 +1,6 @@ -# OpenHarmony 1.1.0 LTS（2021-04-01） +# OpenHarmony 1.1.0 LTS（2021-04-01） -- [版本概述](#section1846294912228) -- [源码获取](#section84808293211) - - [通过镜像站点获取](#section8394142222113) - - [通过repo下载](#section7180193542317) - -- [更新说明](#section175225345334) -- [已修复缺陷列表](#section11935243172612) - -## 版本概述 +## 版本概述 首次发布LTS（long-term support）长期支持版本OpenHarmony 1.1.0，本版本在1.0版本的基础上新增了部分功能和修复了部分缺陷。 @@ -19,234 +11,54 @@ - 图形子系统针对UI能力及JS框架性能和内存得到优化。 - 对目录结构及组件仓做了大幅优化。 -## 源码获取 +## 源码获取 -### 通过镜像站点获取 +### 通过镜像站点获取 **表 1** 源码获取路径 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

版本源码

-

版本信息

-

下载站点

-

SHA256校验码

-

全量代码

-

1.1.0

-

站点

-

SHA256 校验码

-

Hi3861解决方案（二进制）

-

1.1.0

-

站点

-

SHA256 校验码

-

Hi3518解决方案（二进制）

-

1.1.0

-

站点

-

SHA256 校验码

-

Hi3516解决方案（二进制）

-

1.1.0

-

站点

-

SHA256 校验码

-

Release Notes

-

1.1.0

-

站点

-

-

-
+| 版本源码 | 版本信息 | 下载站点 | SHA256校验码 | +| ------------------------ | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 全量代码 | 1.1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.0/code-1.1.0.tar.gz) | [SHA256 校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.0/code-1.1.0.tar.gz.sha256) | +| Hi3861解决方案（二进制） | 1.1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.0/wifiiot-1.1.0.tar.gz) | [SHA256 校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.0/wifiiot-1.1.0.tar.gz.sha256) | +| Hi3518解决方案（二进制） | 1.1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.0/ipcamera_hi3518ev300-1.1.0.tar.gz) | [SHA256 校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.0/ipcamera_hi3518ev300-1.1.0.tar.gz.sha256) | +| Hi3516解决方案（二进制） | 1.1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.0/ipcamera_hi3516dv300-1.1.0.tar.gz) | [SHA256 校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.0/ipcamera_hi3516dv300-1.1.0.tar.gz.sha256) | +| Release Notes | 1.1.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.0/OpenHarmony_Release_Notes_zh_cn.zip) | - | -### 通过repo下载 + +### 通过repo下载 下载命令如下： -``` +```shell repo init -u https://gitee.com/openharmony/manifest.git -b refs/tags/OpenHarmony_release_v1.1.0 --no-repo-verify repo sync -c ``` -## 更新说明 +## 更新说明 本版本完全继承了OpenHarmony 1.0的所有特性，并在OpenHarmony 1.0版本的基础上，对各模块进行了功能扩展和优化，详情请参考下表 。 **表 2** 特性更新说明 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

类别

-

新增特性

-

修改特性

-

删除特性

-

内核

-
  • LiteOS-M支持Cortex-M7、Cortex-M33和RISC-V芯片架构，新增对应的单板target样例。
  • LiteOS-M支持MPU功能。
  • LiteOS-M支持部分POSIX接口。
  • LiteOS-M支持FatFS文件系统。
  • LiteOS-M支持异常回调函数注册机制。
  • LiteOS-M三方芯片易适配性架构调整。
  • LiteOS-M、LiteOS-A支持堆内存调测功能，包括内存泄漏、踩内存、内存统计。
  • LiteOS-M、LiteOS-A支持TLSF堆内存算法，提高内存申请和释放效率，降低碎片率。
-

LiteOS-A调度优化。

-

None

-

泛Sensor

-

新增Sensor组件，提供了Sensor列表查询、Sensor启停、Sensor订阅/去订阅、设置数据上报模式、设置采样间隔等功能。

-

None

-

None

-

全球化

-

新增79种语言的数字格式化、日期和时间格式化、单复数C/C++国际化接口。

-

None

-

None

-

JS应用开发框架

-
  • 新增JS前端opacity全局属性支持。
  • 新增prompt.showDialog API。
  • 新增二维码组件qrcode。
  • 新增事件冒泡机制
-
  • 国际化性能优化，加速页面跳转，支持数字国际化及时间日期转换。
  • 前端布局能力增强，部分样式值支持设置百分比。
  • input及switch组件尺寸自适应能力增强。
  • image组件能力增强，支持显示应用私有数据目录图片。
  • image-animator组件能力增强，支持结束帧指定。
  • canvas组件能力增强，新增部分API。
  • device.getInfo API增强，新增部分返回字段。
  • DFX能力增强，支持跟踪异常的方法栈。
-

国际化功能不再支持回溯特性。

-

测试

-
  • 新增测试工具按照用例级别筛选要执行的测试用例。
  • 新增测试demo用例。
-

None

-

None

-

图形

-
  • 新增组件级旋转缩放、组件级透明度。
  • 新增事件冒泡机制，新增旋转表冠事件。
  • 新增GIF图片解析显示，新增百分比宽高布局，新增Video和二维码控件。
-

局部渲染和SIMD性能优化。

-

None

-

公共基础

-
  • 新增dump系统属性功能。
  • 为上层各模块新增内存池管理接口。
-

None

-

None

-

驱动

-
  • 新增sensor、input、display驱动模型。
  • 新增mipi dsi以及pwm（脉冲宽度调制）。
  • 新增WIFI HDI接口以及WIFI的流控。
  • 新增驱动框架IO服务分组特性。
-

优化驱动加载流程，支持分段加载。

-

None

-

分布式通信

-
  • 新增WiFi Aware特性模块。
  • IPC新增对非对齐序列化的支持。
-

None

-

None

-

安全

-
  • 新增HUKS提供SHA256/RSA3072/RSA2048/AES128/ECC安全算法以及接口，以及提供密钥管理和存储能力。
  • HiChain提供轻量非账号的轻量级组件，用于设备群组管理和认证，支撑软总线通讯安全；提供API给系统服务与应用。
  • 权限管理新增统一的权限管理机制，满足轻量设备权限授权需求。
-

None

-

None

-

AI子系统

-
  • 新增统一的AI引擎框架，实现算法能力快速插件化集成。框架中主要包含插件管理、模块管理和通信管理等模块，对AI算法能力进行生命周期管理和按需部署
  • 为开发者提供开发指南，并提供2个基于AI引擎框架开发的AI能力插件和对应的AI应用Sample，方便开发者在AI引擎框架中快速集成AI算法能力。
-

None

-

None

-

升级服务

-

新增轻量级设备升级能力框架，框架包括升级包的效验和解析能力，以及安装的接口，统一轻设备升级能力框架。

-

None

-

None

-

XTS认证

-

增加AI、DFX、global、OTA兼容性测试用例。

-

应用程序框架、公共通信、分布式任务调度、IOT、内核等测试能力增强。

-

None

-

编译构建

-
  • 新增命令行工具hb, 采用hb set和hb build方式构建，并支持在源码目录下及任意子目录下构建。
  • 支持独立芯片厂商组件。
  • 支持使用组件名单独构建组件。
  • 支持按开发板自定义编译工具链和编译选项。
-

产品配置与build_lite仓解耦，修改为“vendor/解决方案厂商/产品/config.json”。

-

None

-

电源管理

-
  • 电量查询功能。
  • 亮屏锁管理功能及接口。
-

None

-

None

-
+| 类别 | 新增特性 | 修改特性 | 删除特性 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ---------------------------- | +| 内核 | - LiteOS-M支持Cortex-M7、Cortex-M33和RISC-V芯片架构，新增对应的单板target样例。
- LiteOS-M支持MPU功能。
- LiteOS-M支持部分POSIX接口。
- LiteOS-M支持FatFS文件系统。
- LiteOS-M支持异常回调函数注册机制。
- LiteOS-M三方芯片易适配性架构调整。
- LiteOS-M、LiteOS-A支持堆内存调测功能，包括内存泄漏、踩内存、内存统计。
- LiteOS-M、LiteOS-A支持TLSF堆内存算法，提高内存申请和释放效率，降低碎片率。 | LiteOS-A调度优化。 | None | +| 泛Sensor | 新增Sensor组件，提供了Sensor列表查询、Sensor启停、Sensor订阅/去订阅、设置数据上报模式、设置采样间隔等功能。 | None | None | +| 全球化 | 新增79种语言的数字格式化、日期和时间格式化、单复数C/C++国际化接口。 | None | None | +| JS应用开发框架 | - 新增JS前端opacity全局属性支持。
- 新增prompt.showDialog API。
- 新增二维码组件qrcode。
- 新增事件冒泡机制 | - 国际化性能优化，加速页面跳转，支持数字国际化及时间日期转换。
- 前端布局能力增强，部分样式值支持设置百分比。
- input及switch组件尺寸自适应能力增强。
- image组件能力增强，支持显示应用私有数据目录图片。
- image-animator组件能力增强，支持结束帧指定。
- canvas组件能力增强，新增部分API。
- device.getInfo API增强，新增部分返回字段。
- DFX能力增强，支持跟踪异常的方法栈。 | 国际化功能不再支持回溯特性。 | +| 测试 | - 新增测试工具按照用例级别筛选要执行的测试用例。
- 新增测试demo用例。 | None | None | +| 图形 | - 新增组件级旋转缩放、组件级透明度。
- 新增事件冒泡机制，新增旋转表冠事件。
- 新增GIF图片解析显示，新增百分比宽高布局，新增Video和二维码控件。 | 局部渲染和SIMD性能优化。 | None | +| 公共基础 | - 新增dump系统属性功能。
- 为上层各模块新增内存池管理接口。 | None | None | +| 驱动 | - 新增sensor、input、display驱动模型。
- 新增mipi dsi以及pwm（脉冲宽度调制）。
- 新增WIFI HDI接口以及WIFI的流控。
- 新增驱动框架IO服务分组特性。 | 优化驱动加载流程，支持分段加载。 | None | +| 分布式通信 | - 新增WiFi Aware特性模块。
- IPC新增对非对齐序列化的支持。 | None | None | +| 安全 | - 新增HUKS提供 SHA256 / RSA3072 / RSA2048 / AES128 / ECC 安全算法以及接口，以及提供密钥管理和存储能力。
- HiChain提供轻量非账号的轻量级组件，用于设备群组管理和认证，支撑软总线通讯安全；
- 提供API给系统服务与应用。权限管理新增统一的权限管理机制，满足轻量设备权限授权需求。 | None | None | +| AI子系统 | - 新增统一的AI引擎框架，实现算法能力快速插件化集成。框架中主要包含插件管理、模块管理和通信管理等模块，对AI算法能力进行生命周期管理和按需部署
- 为开发者提供开发指南，并提供2个基于AI引擎框架开发的AI能力插件和对应的AI应用Sample，方便开发者在AI引擎框架中快速集成AI算法能力。 | None | None | +| 升级服务 | 新增轻量级设备升级能力框架，框架包括升级包的效验和解析能力，以及安装的接口，统一轻设备升级能力框架。 | None | None | +| XTS认证 | 增加AI、DFX、global、OTA兼容性测试用例。 | 应用程序框架、公共通信、分布式任务调度、IOT、内核等测试能力增强。 | None | +| 编译构建 | - 新增命令行工具hb, 采用hb set和hb build方式构建，并支持在源码目录下及任意子目录下构建。
- 支持独立芯片厂商组件。
- 支持使用组件名单独构建组件。
- 支持按开发板自定义编译工具链和编译选项。 | 产品配置与build_lite仓解耦，修改为“vendor/解决方案厂商/产品/config.json”。 | None | +| 电源管理 | - 电量查询功能。
- 亮屏锁管理功能及接口。 | None | None | + 组件仓优化如下表所示。 @@ -256,912 +68,141 @@ repo sync -c **表 3** 组建仓库优化 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

OpenHarmony1.0

-

OpenHarmony1.1.0

-

优化方式

-

ace_lite_jsfwk

-

ace_engine_lite

-

仓名变更

-

ace_interfaces_innerkits_builtin

-

-

-

只读归档

-

-

-

ai_engine

-

新增组件

-

hiviewdfx_frameworks_hievent_lite

-

hiviewdfx_hievent_lite

-

仓名变更

-

hiviewdfx_frameworks_hilog_lite

-

hiviewdfx_hilog_lite

-

仓名变更

-

hiviewdfx_utils_lite

-

hiviewdfx_hiview_lite

-

仓名变更

-

hiviewdfx_frameworks_ddrdump_lite

-

-

-

只读归档

-

hiviewdfx_interfaces_innerkits_hievent_lite

-

-

-

只读归档

-

hiviewdfx_interfaces_innerkits_hilog

-

-

-

只读归档

-

hiviewdfx_interfaces_kits_hilog

-

-

-

只读归档

-

hiviewdfx_interfaces_kits_hilog_lite

-

-

-

只读归档

-

hiviewdfx_services_hilogcat_lite

-

-

-

只读归档

-

hiviewdfx_services_hiview_lite

-

-

-

只读归档

-

iothardware_hals_wifiiot_lite

-

-

-

只读归档

-

iothardware_interfaces_kits_wifiiot_lite

-

-

-

只读归档

-

iothardware_frameworks_wifiiot_lite

-

iothardware_peripheral

-

仓名变更

-

-

-

applications_camera_sample_communication

-

新增组件

-

-

-

applications_camera_screensaver_app

-

新增组件

-

-

-

sensors_miscdevice_lite

-

新增组件

-

-

-

sensors_sensor_lite

-

新增组件

-

xts_tools_lite

-

xts_tools

-

仓名变更

-

security_services_iam_lite

-

security_permission

-

仓名变更

-

security_interfaces_innerkits_iam_lite

-

-

-

只读归档

-

security_interfaces_kits_iam_lite

-

-

-

只读归档

-

security_services_secure_os

-

security_itrustee_ree_lite

-

仓名变更

-

security_interfaces_innerkits_secure_os

-

-

-

只读归档

-

security_frameworks_secure_os

-

-

-

只读归档

-

security_services_app_verify

-

security_appverify

-

仓名变更

-

security_interfaces_innerkits_app_verify

-

-

-

只读归档

-

security_services_hichainsdk_lite

-

security_deviceauth

-

仓名变更

-

security_interfaces_innerkits_hichainsdk_lite

-

-

-

只读归档

-

security_services_huks_lite

-

security_huks

-

仓名变更

-

security_interfaces_innerkits_huks_lite

-

-

-

只读归档

-

security_frameworks_crypto_lite

-

-

-

只读归档

-

security_interfaces_innerkits_crypto_lite

-

-

-

只读归档

-

-

-

signcenter_tool

-

新增组件

-

-

-

third_party_cryptsetup

-

新增组件

-

-

-

third_party_JSON-C

-

新增组件

-

-

-

third_party_libuuid

-

新增组件

-

-

-

third_party_LVM2

-

新增组件

-

-

-

third_party_popt

-

新增组件

-

communication_interfaces_kits_wifi_lite

-

-

-

只读归档

-

communication_frameworks_wifi_lite

-

-

-

只读归档

-

-

-

communication_wifi_lite

-

新增组件

-

-

-

powermgr_powermgr_lite

-

新增组件

-

distributedschedule_services_dtbschedmgr_lite

-

distributedschedule_dms_fwk_lite

-

仓名变更

-

distributedschedule_services_safwk_lite

-

distributedschedule_safwk_lite

-

仓名变更

-

distributedschedule_services_samgr_lite

-

distributedschedule_samgr_lite

-

仓名变更

-

distributedschedule_interfaces_innerkits_samgr_lite

-

-

-

只读归档

-

distributedschedule_interfaces_kits_samgr_lite

-

-

-

只读归档

-

multimedia_frameworks_audio_lite

-

multimedia_audio_lite

-

仓名变更

-

multimedia_frameworks_camera_lite

-

multimedia_camera_lite

-

仓名变更

-

multimedia_frameworks_player_lite

-

multimedia_media_lite

-

仓名变更

-

multimedia_hals_camera_lite

-

-

-

只读归档

-

multimedia_frameworks_recorder_lite

-

-

-

只读归档

-

multimedia_interfaces_kits_audio_lite

-

-

-

只读归档

-

multimedia_interfaces_kits_camera_lite

-

-

-

只读归档

-

multimedia_interfaces_kits_player_lite

-

-

-

只读归档

-

multimedia_interfaces_kits_recorder_lite

-

-

-

只读归档

-

multimedia_services_media_lite

-

-

-

只读归档

-

kernel_liteos_a_huawei_proprietary_fs_proc

-

-

-

只读归档

-

-

-

third_party_mksh

-

新增组件

-

-

-

third_party_optimized_routines

-

新增组件

-

-

-

third_party_toybox

-

新增组件

-

vendor_huawei_camera

-

-

-

只读归档

-

vendor_huawei_wifi_iot

-

-

-

只读归档

-

startup_services_bootstrap_lite

-

startup_bootstrap_lite

-

仓名变更

-

startup_frameworks_syspara_lite

-

startup_syspara_lite

-

仓名变更

-

startup_hals_syspara_lite

-

-

-

只读归档

-

startup_interfaces_kits_syspara_lite

-

-

-

只读归档

-

graphic_lite

-

graphic_surface

-

仓名变更

-

-

-

graphic_ui

-

新增组件

-

-

-

graphic_utils

-

新增组件

-

-

-

graphic_wms

-

新增组件

-

-

-

third_party_giflib

-

新增组件

-

-

-

third_party_qrcodegen

-

新增组件

-

-

-

drivers_adapter_khdf_linux

-

新增组件

-

drivers_hdf_lite

-

drivers_adapter_khdf_liteos

-

仓名变更

-

-

-

drivers_adapter_uhdf

-

新增组件

-

drivers_hdf_frameworks

-

drivers_framework

-

仓名变更

-

-

-

drivers_peripheral_audio

-

新增组件

-

-

-

drivers_peripheral_codec

-

新增组件

-

-

-

drivers_peripheral_display

-

新增组件

-

-

-

drivers_peripheral_format

-

新增组件

-

-

-

drivers_peripheral_input

-

新增组件

-

-

-

drivers_peripheral_sensor

-

新增组件

-

-

-

drivers_peripheral_wlan

-

新增组件

-

-

-

global_cust_lite

-

新增组件

-

-

-

global_i18n_lite

-

新增组件

-

global_frameworks_resmgr_lite

-

global_resmgr_lite

-

仓名变更

-
  

third_party_icu

-

新增组件

-

global_interfaces_innerkits_resmgr_lite

-

-

-

只读归档

-

communication_frameworks_ipc_lite

-

communication_ipc_lite

-

仓名变更

-

communication_interfaces_kits_ipc_lite

-

-

-

只读归档

-

communication_interfaces_kits_softbuskit_lite

-

-

-

只读归档

-

communication_hals_wifi_lite

-

-

-

只读归档

-

communication_services_softbus_lite

-

communication_softbus_lite

-

仓名变更

-

-

-

communication_wifi_aware

-

新增组件

-

-

-

update_ota_lite

-

新增组件

-

vendor_hisi_hi35xx_hi35xx_init

-

device_hisilicon_build

-

仓名变更

-

vendor_hisi_hi35xx_platform

-

device_hisilicon_drivers

-

仓名变更

-

vendor_hisi_hi35xx_hardware

-

device_hisilicon_hardware

-

仓名变更

-

vendor_hisi_hi35xx_hi3518ev300

-

device_hisilicon_hispark_aries

-

仓名变更

-

vendor_hisi_hi3861_hi3861

-

device_hisilicon_hispark_pegasus

-

仓名变更

-

vendor_hisi_hi35xx_hi3516dv300

-

device_hisilicon_hispark_taurus

-

仓名变更

-

vendor_hisi_hi35xx_middleware

-

device_hisilicon_modules

-

仓名变更

-

vendor_hisi_hi35xx_middleware_source_third_party_ffmpeg

-

device_hisilicon_third_party_ffmpeg

-

仓名变更

-

vendor_hisi_hi35xx_thirdparty_uboot_src

-

device_hisilicon_third_party_uboot

-

仓名变更

-

-

-

vendor_hisilicon

-

新增组件

-

vendor_hisi_hi35xx_hi3516dv300_uboot

-

-

-

只读归档

-

vendor_hisi_hi35xx_hi3518ev300_uboot

-

-

-

只读归档

-

aafwk_interfaces_innerkits_abilitykit_lite

-

-

-

只读归档

-

aafwk_interfaces_innerkits_intent_lite

-

aafwk_aafwk_lite

-

仓名变更

-

aafwk_interfaces_innerkits_abilitymgr_lite

-

-

-

只读归档

-

appexecfwk_kits_appkit_lite

-

appexecfwk_appexecfwk_lite

-

仓名变更

-

aafwk_frameworks_kits_ability_lite

-

-

-

只读归档

-
  

developtools_packing_tool

-

新增组件

-

aafwk_interfaces_kits_ability_lite

-

-

-

只读归档

-

appexecfwk_frameworks_bundle_lite

-

-

-

只读归档

-

aafwk_services_abilitymgr_lite

-

-

-

只读归档

-

appexecfwk_interfaces_innerkits_appexecfwk_lite

-

-

-

只读归档

-

appexecfwk_interfaces_innerkits_bundlemgr_lite

-

-

-

只读归档

-

appexecfwk_services_bundlemgr_lite

-

-

-

只读归档

-

aafwk_frameworks_kits_content_lite

-

-

-

只读归档

-
- -## 已修复缺陷列表 +| OpenHarmony1.0 | OpenHarmony1.1.0 | 优化方式 | +| ------------------------------------------------------------ | --------------------------------------------- | -------- | +| ace_lite_jsfwk | ace_engine_lite | 仓名变更 | +| ace_interfaces_innerkits_builtin | - | 只读归档 | +| - | ai_engine | 新增组件 | +| hiviewdfx_frameworks_hievent_lite | hiviewdfx_hievent_lite | 仓名变更 | +| hiviewdfx_frameworks_hilog_lite | hiviewdfx_hilog_lite | 仓名变更 | +| hiviewdfx_utils_lite | hiviewdfx_hiview_lite | 仓名变更 | +| hiviewdfx_frameworks_ddrdump_lite | - | 只读归档 | +| hiviewdfx_interfaces_innerkits_hievent_
lite | - | 只读归档 | +| hiviewdfx_interfaces_innerkits_hilog | - | 只读归档 | +| hiviewdfx_interfaces_kits_hilog | - | 只读归档 | +| hiviewdfx_interfaces_kits_hilog_lite | - | 只读归档 | +| hiviewdfx_services_hilogcat_lite | - | 只读归档 | +| hiviewdfx_services_hiview_lite | - | 只读归档 | +| iothardware_hals_wifiiot_lite | - | 只读归档 | +| iothardware_interfaces_kits_wifiiot_lite | - | 只读归档 | +| iothardware_frameworks_wifiiot_lite | iothardware_peripheral | 仓名变更 | +| - | applications_camera_sample_
communication | 新增组件 | +| - | applications_camera_screensaver_
app | 新增组件 | +| - | sensors_miscdevice_lite | 新增组件 | +| - | sensors_sensor_lite | 新增组件 | +| xts_tools_lite | xts_tools | 仓名变更 | +| security_services_iam_lite | security_permission | 仓名变更 | +| security_interfaces_innerkits_iam_lite | - | 只读归档 | +| security_interfaces_kits_iam_lite | - | 只读归档 | +| security_services_secure_os | security_itrustee_ree_lite | 仓名变更 | +| security_interfaces_innerkits_secure_os | - | 只读归档 | +| security_frameworks_secure_os | - | 只读归档 | +| security_services_app_verify | security_appverify | 仓名变更 | +| security_interfaces_innerkits_app_verify | - | 只读归档 | +| security_services_hichainsdk_lite | security_deviceauth | 仓名变更 | +| security_interfaces_innerkits_hichainsdk_
lite | - | 只读归档 | +| security_services_huks_lite | security_huks | 仓名变更 | +| security_interfaces_innerkits_huks_lite | - | 只读归档 | +| security_frameworks_crypto_lite | - | 只读归档 | +| security_interfaces_innerkits_crypto_lite | - | 只读归档 | +| - | signcenter_tool | 新增组件 | +| - | third_party_cryptsetup | 新增组件 | +| - | third_party_JSON-C | 新增组件 | +| - | third_party_libuuid | 新增组件 | +| - | third_party_LVM2 | 新增组件 | +| - | third_party_popt | 新增组件 | +| communication_interfaces_kits_wifi_lite | - | 只读归档 | +| communication_frameworks_wifi_lite | - | 只读归档 | +| - | communication_wifi_lite | 新增组件 | +| - | powermgr_powermgr_lite | 新增组件 | +| distributedschedule_services_
dtbschedmgr_lite | distributedschedule_dms_fwk_lite | 仓名变更 | +| distributedschedule_services_safwk_lite | distributedschedule_safwk_lite | 仓名变更 | +| distributedschedule_services_samgr_lite | distributedschedule_samgr_lite | 仓名变更 | +| distributedschedule_interfaces_innerkits_
samgr_lite | - | 只读归档 | +| distributedschedule_interfaces_kits_samgr_
lite | - | 只读归档 | +| multimedia_frameworks_audio_lite | multimedia_audio_lite | 仓名变更 | +| multimedia_frameworks_camera_lite | multimedia_camera_lite | 仓名变更 | +| multimedia_frameworks_player_lite | multimedia_media_lite | 仓名变更 | +| multimedia_hals_camera_lite | - | 只读归档 | +| multimedia_frameworks_recorder_lite | - | 只读归档 | +| multimedia_interfaces_kits_audio_lite | - | 只读归档 | +| multimedia_interfaces_kits_camera_lite | - | 只读归档 | +| multimedia_interfaces_kits_player_lite | - | 只读归档 | +| multimedia_interfaces_kits_recorder_lite | - | 只读归档 | +| multimedia_services_media_lite | - | 只读归档 | +| kernel_liteos_a_huawei_proprietary_fs_
proc | - | 只读归档 | +| - | third_party_mksh | 新增组件 | +| - | third_party_optimized_routines | 新增组件 | +| - | third_party_toybox | 新增组件 | +| vendor_huawei_camera | - | 只读归档 | +| vendor_huawei_wifi_iot | - | 只读归档 | +| startup_services_bootstrap_lite | startup_bootstrap_lite | 仓名变更 | +| startup_frameworks_syspara_lite | startup_syspara_lite | 仓名变更 | +| startup_hals_syspara_lite | - | 只读归档 | +| startup_interfaces_kits_syspara_lite | - | 只读归档 | +| graphic_lite | graphic_surface | 仓名变更 | +| - | graphic_ui | 新增组件 | +| - | graphic_utils | 新增组件 | +| - | graphic_wms | 新增组件 | +| - | third_party_giflib | 新增组件 | +| - | third_party_qrcodegen | 新增组件 | +| - | drivers_adapter_khdf_linux | 新增组件 | +| drivers_hdf_lite | drivers_adapter_khdf_liteos | 仓名变更 | +| - | drivers_adapter_uhdf | 新增组件 | +| drivers_hdf_frameworks | drivers_framework | 仓名变更 | +| - | drivers_peripheral_audio | 新增组件 | +| - | drivers_peripheral_codec | 新增组件 | +| - | drivers_peripheral_display | 新增组件 | +| - | drivers_peripheral_format | 新增组件 | +| - | drivers_peripheral_input | 新增组件 | +| - | drivers_peripheral_sensor | 新增组件 | +| - | drivers_peripheral_wlan | 新增组件 | +| - | global_cust_lite | 新增组件 | +| - | global_i18n_lite | 新增组件 | +| global_frameworks_resmgr_lite | global_resmgr_lite | 仓名变更 | +| | third_party_icu | 新增组件 | +| global_interfaces_innerkits_resmgr_lite | - | 只读归档 | +| communication_frameworks_ipc_lite | communication_ipc_lite | 仓名变更 | +| communication_interfaces_kits_ipc_lite | - | 只读归档 | +| communication_interfaces_kits_
softbuskit_lite | - | 只读归档 | +| communication_hals_wifi_lite | - | 只读归档 | +| communication_services_softbus_lite | communication_softbus_lite | 仓名变更 | +| - | communication_wifi_aware | 新增组件 | +| - | update_ota_lite | 新增组件 | +| vendor_hisi_hi35xx_hi35xx_init | device_hisilicon_build | 仓名变更 | +| vendor_hisi_hi35xx_platform | device_hisilicon_drivers | 仓名变更 | +| vendor_hisi_hi35xx_hardware | device_hisilicon_hardware | 仓名变更 | +| vendor_hisi_hi35xx_hi3518ev300 | device_hisilicon_hispark_aries | 仓名变更 | +| vendor_hisi_hi3861_hi3861 | device_hisilicon_hispark_pegasus | 仓名变更 | +| vendor_hisi_hi35xx_hi3516dv300 | device_hisilicon_hispark_taurus | 仓名变更 | +| vendor_hisi_hi35xx_middleware | device_hisilicon_modules | 仓名变更 | +| vendor_hisi_hi35xx_middleware_source_
third_party_ffmpeg | device_hisilicon_third_party_ffmpeg | 仓名变更 | +| vendor_hisi_hi35xx_thirdparty_uboot_src | device_hisilicon_third_party_uboot | 仓名变更 | +| - | vendor_hisilicon | 新增组件 | +| vendor_hisi_hi35xx_hi3516dv300_uboot | - | 只读归档 | +| vendor_hisi_hi35xx_hi3518ev300_uboot | - | 只读归档 | +| aafwk_interfaces_innerkits_abilitykit_lite | - | 只读归档 | +| aafwk_interfaces_innerkits_intent_lite | aafwk_aafwk_lite | 仓名变更 | +| aafwk_interfaces_innerkits_abilitymgr_
lite | - | 只读归档 | +| appexecfwk_kits_appkit_lite | appexecfwk_appexecfwk_lite | 仓名变更 | +| aafwk_frameworks_kits_ability_lite | - | 只读归档 | +| | developtools_packing_tool | 新增组件 | +| aafwk_interfaces_kits_ability_lite | - | 只读归档 | +| appexecfwk_frameworks_bundle_lite | - | 只读归档 | +| aafwk_services_abilitymgr_lite | - | 只读归档 | +| appexecfwk_interfaces_innerkits_
appexecfwk_lite | - | 只读归档 | +| appexecfwk_interfaces_innerkits_
bundlemgr_lite | - | 只读归档 | +| appexecfwk_services_bundlemgr_lite | - | 只读归档 | +| aafwk_frameworks_kits_content_lite | - | 只读归档 | + +## 已修复缺陷列表 针对OpenHarmony 1.0版本的缺陷列表，解决并修复的问题请参见下表。 **表 4** 修复问题列表 - - - - - - - - - - - - - - - -

ISSUE

-

问题描述

-

I3EALU

-

【多媒体】cameraActs 用例执行时，找不到相机配置文件，初始失败的问题

-

I3EGUX

-

【可靠性问题】反复reset，出现一次KIdle进程crash，系统挂死无法启动

-

I3DHIL

-

【系统问题】HI3518开源板剩余空间不足，导致ACTS用例大量失败

-
- +| ISSUE | 问题描述 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [I3EALU](https://gitee.com/openharmony/multimedia_camera_lite/issues/I3EALU) | 【多媒体】cameraActs 用例执行时，找不到相机配置文件，初始失败的问题 | +| [I3EGUX](https://gitee.com/openharmony/release-management/issues/I3EGUX) | 【可靠性问题】反复reset，出现一次KIdle进程crash，系统挂死无法启动 | +| [I3DHIL](https://gitee.com/openharmony/community/issues/I3DHIL) | 【系统问题】HI3518开源板剩余空间不足，导致ACTS用例大量失败 | diff --git a/zh-cn/release-notes/OpenHarmony-1-1-1-LTS.md b/zh-cn/release-notes/OpenHarmony-1-1-1-LTS.md index d53773891dc03fe832145d8b8d9788d3b1bf3282..31eeea9bde4d857f6f9ad4a0c515ee2051cecb18 100755 --- a/zh-cn/release-notes/OpenHarmony-1-1-1-LTS.md +++ b/zh-cn/release-notes/OpenHarmony-1-1-1-LTS.md @@ -1,140 +1,45 @@ -# OpenHarmony 1.1.1 LTS（2021-06-22） +# OpenHarmony 1.1.1 LTS（2021-06-22） -- [版本概述](#section1846294912228) -- [源码获取](#section84808293211) - - [通过镜像站点获取](#section8394142222113) - - [通过repo下载](#section7180193542317) - -- [更新说明](#section175225345334) - -## 版本概述 +## 版本概述 更新发布LTS（long-term support）长期支持版本OpenHarmony 1.1.1，本版本在1.1.0版本的基础上新增了部分功能和修复了部分缺陷。 -## 源码获取 +## 源码获取 -### 通过镜像站点获取 +### 通过镜像站点获取 **表 1** 源码获取路径 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

版本源码

-

版本信息

-

下载站点

-

SHA256校验码

-

全量代码

-

1.1.1

-

站点

-

SHA256校验码

-

Hi3861解决方案（二进制）

-

1.1.1

-

站点

-

SHA256校验码

-

Hi3518解决方案（二进制）

-

1.1.1

-

站点

-

SHA256校验码

-

Hi3516解决方案（二进制）

-

1.1.1

-

站点

-

SHA256校验码

-

Release Notes

-

1.1.1

-

站点

-

-

-
- -### 通过repo下载 +| 版本源码 | 版本信息 | 下载站点 | SHA256校验码 | +| ------------------------ | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 全量代码 | 1.1.1 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.1/code-v1.1.1-LTS.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.1/code-v1.1.1-LTS.tar.gz.sha256) | +| Hi3861解决方案（二进制） | 1.1.1 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.1/wifiiot-1.1.0.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.1/wifiiot-1.1.0.tar.gz.sha256) | +| Hi3518解决方案（二进制） | 1.1.1 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.1/ipcamera_hi3518ev300-1.1.1.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.1/ipcamera_hi3518ev300-1.1.1.tar.gz.sha256) | +| Hi3516解决方案（二进制） | 1.1.1 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.1/ipcamera_hi3516dv300-1.1.1.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.1/ipcamera_hi3516dv300-1.1.1.tar.gz.sha256) | +| Release Notes | 1.1.1 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.1/OpenHarmony_Release_Notes_1.1.1_LTS.md) | - | + + +### 通过repo下载 下载命令如下： -repo init -u [https://gitee.com/openharmony/manifest.git](https://gitee.com/openharmony/manifest.git) -b refs/tags/OpenHarmony-v1.1.1-LTS --no-repo-verify +repo init -u https://gitee.com/openharmony/manifest.git -b refs/tags/OpenHarmony-v1.1.1-LTS --no-repo-verify -## 更新说明 +## 更新说明 本版本完全继承了OpenHarmony 1.1.0的所有特性，并在OpenHarmony 1.1.0版本的基础上，对各模块进行了缺陷修复和性能优化，详情请参考下表。 **表 2** 版本更新说明 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

类别

-

更新内容

-

通信

-
  • 更新了部分STA相关功能的数据类以及新增了几个AP相关功能的innerkits接口
  • 新增了蓝牙相关功能的innerkits接口，包括BLE设备gatt相关的操作，以及BLE广播、扫描等功能
-

安全

-
  • 支持调用方仅使用绑定的能力，裁剪设备认证能力
  • 支持了huks裁剪设备认证
-

内核

-
  • 修复clang编译的系统镜像内核栈回溯功能失效
  • 解决调度中存在有符号数与无符号数比较
  • 修复setitimer中定时给进程发信号时未持有调度锁，导致踩内存等问题
  • lwip适配内核posix接口
  • 修复sigaction中sigsuspend的后执行信号顺序与预期不符，信号注册时未屏蔽用户传入信号屏蔽字段
-

驱动

-
  • liteos_m上的编译错误修复
  • 合入解决mmc crash的问题
-

AI

-
  • AI添加共享内存机制
  • AI添加linux内核适配
  • 同步算法禁用异步调用
  • 添加gitignore和Cmakelist
-

图形

-
  • 修复circle progress开启端点样式情况下，进度为0，圆形端点需要绘制问题
  • 修改旋转表冠灵敏度及方向相关问题
  • 增加 UIList 自动对齐动画时间设置功能
  • 修复当LineBreakMode为LINE_BRAK_ELLIPSIS时UILabel GetText宽度值错误
  • slider组件新增样式属性
  • UITimePicker增加设置循环接口
  • 修复定点数优化导致的NEON旋转缩放变换显示异常的BUG
  • 修复换行算法在字符串中有多个换行符时存在的换行错误
  • 修复表盘指针显示花屏问题
-

全球化

-
  • 添加日期时间模板Ed和MEd
-

ACE框架

-
  • 修复checkbox/radio点击事件异常
  • 修复list和if指令场景JS应用crash问题
  • slider样式归一处理
  • pickerview组件支持循环滑动
  • 修改align-item设置值为stretch情况下，子项居中显示的问题
-
+| 类别 | 更新内容 | +| ------- | ------------------------------------------------------------ | +| 通信 | - 更新了部分STA相关功能的数据类以及新增了几个AP相关功能的innerkits接口
- 新增了蓝牙相关功能的innerkits接口，包括BLE设备gatt相关的操作，以及BLE广播、扫描等功能 | +| 安全 | - 支持调用方仅使用绑定的能力，裁剪设备认证能力
- 支持了huks裁剪设备认证 | +| 内核 | - 修复clang编译的系统镜像内核栈回溯功能失效
- 解决调度中存在有符号数与无符号数比较
- 修复setitimer中定时给进程发信号时未持有调度锁，导致踩内存等问题
- lwip适配内核posix接口
- 修复sigaction中sigsuspend的后执行信号顺序与预期不符，信号注册时未屏蔽用户传入信号屏蔽字段 | +| 驱动 | - liteos_m上的编译错误修复
- 合入解决mmc crash的问题 | +| AI | - AI添加共享内存机制
- AI添加linux内核适配
- 同步算法禁用异步调用
- 添加gitignore和Cmakelist | +| 图形 | - 修复circle progress开启端点样式情况下，进度为0，圆形端点需要绘制问题
- 修改旋转表冠灵敏度及方向相关问题
- 增加 UIList 自动对齐动画时间设置功能
- 修复当LineBreakMode为LINE_BRAK_ELLIPSIS时UILabel GetText宽度值错误
- slider组件新增样式属性
- UITimePicker增加设置循环接口
- 修复定点数优化导致的NEON旋转缩放变换显示异常的BUG
- 修复换行算法在字符串中有多个换行符时存在的换行错误
- 修复表盘指针显示花屏问题 | +| 全球化 | - 添加日期时间模板Ed和MEd | +| ACE框架 | - 修复checkbox/radio点击事件异常
- 修复list和if指令场景JS应用crash问题
- slider样式归一处理
- pickerview组件支持循环滑动
- 修改align-item设置值为stretch情况下，子项居中显示的问题 | + diff --git a/zh-cn/release-notes/OpenHarmony-2-0-Canary.md b/zh-cn/release-notes/OpenHarmony-2-0-Canary.md index 576270b301ae728f682a1ce80d99504ad90cf073..bcc67cb3889ef73af438e1e5f8e066f3bb4f66a3 100644 --- a/zh-cn/release-notes/OpenHarmony-2-0-Canary.md +++ b/zh-cn/release-notes/OpenHarmony-2-0-Canary.md @@ -1,11 +1,6 @@ -# OpenHarmony 2.0 Canary（2021-06-01） +# OpenHarmony 2.0 Canary（2021-06-01） -- [版本概述](#section1677664815431) -- [配套关系](#section13201781528) -- [源码获取](#源码获取) -- [更新说明](#section11256141314463) - -## 版本概述 +## 版本概述 当前版本在OpenHarmony 1.1.0的基础上，增加标准系统版本，具备的主要功能如下： @@ -16,44 +11,18 @@ - 提供媒体框架，支持音视频功能开发。 - 提供图形框架能力，支持窗口管理和合成，支持GPU能力。 -## 配套关系 +## 配套关系 **表 1** 版本软件和工具配套关系 - - - - - - - - - - - - - - - - - - - -

软件

-

版本

-

备注

-

OpenHarmony

-

2.0 Canary

-

NA

-

HUAWEI DevEco Studio（可选）

-

DevEco Studio 2.1 Release

-

OpenHarmony应用开发推荐使用。

-

HUAWEI DevEco Device Tool（可选）

-

Deveco DeviceTool 2.2 Beta1

-

OpenHarmony智能设备集成开发环境推荐使用。

-
- -## 源码获取 +| 软件 | 版本 | 备注 | +| --------------------------------- | --------------------------- | ----------------------------------------- | +| OpenHarmony | 2.0 Canary | NA | +| HUAWEI DevEco Studio（可选） | DevEco Studio 2.1 Release | OpenHarmony应用开发推荐使用。 | +| HUAWEI DevEco Device Tool（可选） | Deveco DeviceTool 2.2 Beta1 | OpenHarmony智能设备集成开发环境推荐使用。 | + + +## 源码获取 ### 通过repo下载 @@ -62,7 +31,7 @@ 通过repo + ssh 下载（需注册公钥，请参考[码云帮助中心](https://gitee.com/help/articles/4191)）。 - ``` + ```shell repo init -u git@gitee.com:openharmony/manifest.git -b refs/tags/OpenHarmony-2.0-Canary --no-repo-verify repo sync -c repo forall -c 'git lfs pull' @@ -72,7 +41,7 @@ repo forall -c 'git lfs pull' 通过repo + https 下载。 -``` +```shell repo init -u https://gitee.com/openharmony/manifest.git -b refs/tags/OpenHarmony-2.0-Canary --no-repo-verify repo sync -c repo forall -c 'git lfs pull' @@ -82,169 +51,46 @@ repo forall -c 'git lfs pull' **表2** 源码获取路径 -| 版本源码 | 版本信息 | 下载站点 | SHA256校验码 | +| 版本源码 | 版本信息 | 下载站点 | SHA256校验码 | | -------- | -------- | -------- | -------- | -| 全量代码 | 2.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.0/code-2.0-canary_20210601.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.0/code-2.0-canary_20210601.tar.gz.sha256) | -| Release Notes | 2.0 | [站点](https://gitee.com/openharmony/docs/blob/master/zh-cn/release-notes/OpenHarmony-2-0-Canary.md) | - | +| 全量代码 | 2.0 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.0/code-2.0-canary_20210601.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.0/code-2.0-canary_20210601.tar.gz.sha256) | +| Release Notes | 2.0 | [站点](https://gitee.com/openharmony/docs/blob/master/zh-cn/release-notes/OpenHarmony-2-0-Canary.md) | - | -## 更新说明 +## 更新说明 本版本完全继承了OpenHarmony 1.1.0的所有特性，并在OpenHarmony 1.1.0版本的基础上，新增标准系统版本形态，详情请参考下表 。 **表 3** 版本新增特性表 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

子系统名称

-

新增特性

-

内核

-

基于Linux Kernel LTS社区开源基线，回合CVE补丁，包含了OpenHarmony上层特性适配。

-

分布式文件

-

提供本地同步文件 JS 接口，包括文件读写、目录访问以及文件Stat。

-

图形图像

-
  • 新增窗口管理功能，包括创建、销毁和窗口栈管理等。
  • 新增合成器功能，包括CPU、GPU和TDE合成。
  • 新增bufferqueue功能，支持进程间传递。
  • 新增vsync管理功能。
-

驱动

-

新增用户态驱动框架。

-

电源管理服务

-

新增电源管理能力，包括关机服务、亮灭屏管理、亮度调节、电池状态查询、系统电源管理、休眠锁管理等功能。

-

多模输入子系统

-

新增支持单指触屏输入能力。

-

启动恢复子系统

-

系统属性管理新增JS API。

-

升级服务

-
  • 新增recovery系统升级服务能力。
  • 新增差分包升级能力。
  • 新增系统属性管理JS API。
-

帐号

-

提供分布式云帐号登录状态管理功能。

-

编译构建

-
  • 支持按照部件名或模块名编译指定目标。
  • 支持不同芯片平台接入，配置产品部件列表。
-

测试

-

新增开发者自测试能力，支持C++ API单元测试，API性能测试等。

-

数据管理

-

提供轻量级Key-Value操作，支持本地应用存储少量数据，数据存储在本地文件中，同时也加载在内存中的，所以访问速度更快，效率更高。

-

语言编译运行时

-

提供了JS、C/C++语言程序的编译、执行环境，提供支撑运行时的基础库，以及关联的API接口、编译器和配套工具。

-

分布式任务调度

-

提供系统服务的启动、注册、查询及管理能力。

-

JS UI框架

-
  • 提供40+UI基础组件和容器组件。
  • 提供标准CSS动画。
  • 支持原子化布局、栅格布局。
  • 提供类Web开发范式的UI编程框架。
  • JS API扩展机制。
-

媒体

-
  • 新增媒体播放和录制基本功能。
  • 新增相机管理和相机采集基本功能。
  • 新增音频音量和设备管理基本功能。
-

事件通知

-

新增发布、订阅、接收公共事件的基本功能。

-

杂散软件服务

-

新增设置时间的能力。

-

用户程序框架

-

新增包安装、卸载、运行及管理能力。

-

电话服务

-
  • 新增获得信号强度、获得驻网状态能力。
  • 新增获得SIM卡状态能力。
  • 新增拨打电话、拒接电话、挂断电话能力。
  • 新增发送短信、接收短信能力。
-

公共基础类库

-

提供了一些常用的C、C++开发增强API。

-

研发工具链

-
  • 新增设备连接调试器。
  • 新增性能跟踪能力。
  • 新增实时内存和trace调优工具，和端侧插件能力。
-

分布式软总线

-
  • 新增跨进程通信(IPC)和跨设备的远程过程调用(RPC)能力。
  • 新增支持设备发现、组网、传输能力的软总线服务。
  • 新增WiFi服务，可提供STA开关、扫描、连接等基本能力。
-

XTS

-

新增各业务特性公共API兼容性看护用例套件。

-

系统应用

-

桌面:

-
  • 新增全量应用图标展示、启动和卸载应用能力。
  • 新增桌面管理界面，可切换网格布局与列表布局。
  • 新增最近任务管理能力，可热启动和清理任务。
-

设置：

-
  • 新增设置应用，包括亮度设置，应用信息，时间设置和关于设备。
-

SystemUI：

-
  • 新增系统栏展示，包括时间、电量信息。
  • 新增系统导航展示。
-

DFX

-
  • 新增流水日志。
  • 新增应用故障收集和订阅。
  • 新增系统事件记录接口。
  • 新增应用事件记录接口及框架。
-

全球化子系统

-
  • 新增支持资源解析读取能力。
  • 新增支持时间日期格式化能力。
-

安全

-
  • 新增系统权限管理，包括系统权限声明，应用安装时申请或申明的权限解析，权限查询，权限授予。
  • 新增应用签名和验签能力。
  • 新增点对点设备连接时的互信认证能力和设备群组管理能力。
-
+| 子系统名称 | 新增特性 | +| -------------- | ------------------------------------------------------------ | +| 内核 | 基于Linux Kernel LTS社区开源基线，回合CVE补丁，包含了OpenHarmony上层特性适配。 | +| 分布式文件 | 提供本地同步文件 JS 接口，包括文件读写、目录访问以及文件Stat。 | +| 图形图像 | - 新增窗口管理功能，包括创建、销毁和窗口栈管理等。
- 新增合成器功能，包括CPU、GPU和TDE合成。
- 新增bufferqueue功能，支持进程间传递。
- 新增vsync管理功能。 | +| 驱动 | 新增用户态驱动框架。 | +| 电源管理服务 | 新增电源管理能力，包括关机服务、亮灭屏管理、亮度调节、电池状态查询、系统电源管理、休眠锁管理等功能。 | +| 多模输入子系统 | 新增支持单指触屏输入能力。 | +| 启动恢复子系统 | 系统属性管理新增JS API。 | +| 升级服务 | - 新增recovery系统升级服务能力。
- 新增差分包升级能力。
- 新增系统属性管理JS API。 | +| 帐号 | 提供分布式云帐号登录状态管理功能。 | +| 编译构建 | - 支持按照部件名或模块名编译指定目标。
- 支持不同芯片平台接入，配置产品部件列表。 | +| 测试 | 新增开发者自测试能力，支持C++ API单元测试，API性能测试等。 | +| 数据管理 | 提供轻量级Key-Value操作，支持本地应用存储少量数据，数据存储在本地文件中，同时也加载在内存中的，所以访问速度更快，效率更高。 | +| 语言编译运行时 | 提供了JS、C/C++语言程序的编译、执行环境，提供支撑运行时的基础库，以及关联的API接口、编译器和配套工具。 | +| 分布式任务调度 | 提供系统服务的启动、注册、查询及管理能力。 | +| JS UI框架 | - 提供40+UI基础组件和容器组件。
- 提供标准CSS动画。
- 支持原子化布局、栅格布局。
- 提供类Web开发范式的UI编程框架。
- JS API扩展机制。 | +| 媒体 | - 新增媒体播放和录制基本功能。
- 新增相机管理和相机采集基本功能。
- 新增音频音量和设备管理基本功能。 | +| 事件通知 | 新增发布、订阅、接收公共事件的基本功能。 | +| 杂散软件服务 | 新增设置时间的能力。 | +| 用户程序框架 | 新增包安装、卸载、运行及管理能力。 | +| 电话服务 | - 新增获得信号强度、获得驻网状态能力。
- 新增获得SIM卡状态能力。
- 新增拨打电话、拒接电话、挂断电话能力。
- 新增发送短信、接收短信能力。 | +| 公共基础类库 | 提供了一些常用的C、C++开发增强API。 | +| 研发工具链 | - 新增设备连接调试器。
- 新增性能跟踪能力。
- 新增实时内存和trace调优工具，和端侧插件能力。 | +| 分布式软总线 | - 新增跨进程通信(IPC)和跨设备的远程过程调用(RPC)能力。
- 新增支持设备发现、组网、传输能力的软总线服务。
- 新增WiFi服务，可提供STA开关、扫描、连接等基本能力。 | +| XTS | 新增各业务特性公共API兼容性看护用例套件。 | +| 系统应用 | 桌面:
- 新增全量应用图标展示、启动和卸载应用能力。
- 新增桌面管理界面，可切换网格布局与列表布局。
- 新增最近任务管理能力，可热启动和清理任务。
设置：
- 新增设置应用，包括亮度设置，应用信息，时间设置和关于设备。
SystemUI：
- 新增系统栏展示，包括时间、电量信息。
- 新增系统导航展示。 | +| DFX | - 新增流水日志。
- 新增应用故障收集和订阅。
- 新增系统事件记录接口。
- 新增应用事件记录接口及框架。 | +| 全球化子系统 | - 新增支持资源解析读取能力。
- 新增支持时间日期格式化能力。 | +| 安全 | - 新增系统权限管理，包括系统权限声明，应用安装时申请或申明的权限解析，权限查询，权限授予。
- 新增应用签名和验签能力。
- 新增点对点设备连接时的互信认证能力和设备群组管理能力。 | + diff --git a/zh-cn/release-notes/OpenHarmony-v1-1-3-LTS.md b/zh-cn/release-notes/OpenHarmony-v1-1-3-LTS.md index df9f1e2bf2775f9d3bcfbe78bacbc29955beb85e..06220f8a394909e0599b45be324bea2416c0c3b8 100644 --- a/zh-cn/release-notes/OpenHarmony-v1-1-3-LTS.md +++ b/zh-cn/release-notes/OpenHarmony-v1-1-3-LTS.md @@ -1,54 +1,26 @@ -# OpenHarmony v1.1.3 LTS +# OpenHarmony v1.1.3 LTS -- [版本概述](#section1846294912228) -- [配套关系](#section395983762117) -- [源码获取](#section84808293211) - - [通过镜像站点获取](#section8394142222113) - -- [更新说明](#section175225345334) -- [已修复缺陷列表](#section11935243172612) - -## 版本概述 +## 版本概述 更新发布LTS（long-term support）长期支持版本OpenHarmony v1.1.3 LTS，本版本在OpenHarmony v1.1.2 LTS版本的基础上新增了一些特性和修复了部分缺陷。 -## 配套关系 +## 配套关系 **表 1** 版本软件和工具配套关系 - - - - - - - - - - - - - - - -

软件

-

版本

-

备注

-

OpenHarmony

-

1.1.3 LTS

-

NA

-

HUAWEI DevEco Device Tool（可选）

-

HUAWEI DevEco Device Tool 2.1 Release

-

OpenHarmony智能设备集成开发环境推荐使用。

-
- -## 源码获取 +| 软件 | 版本 | 备注 | +| --------------------------------- | ------------------------------------- | ----------------------------------------- | +| OpenHarmony | 1.1.3 LTS | NA | +| HUAWEI DevEco Device Tool（可选） | HUAWEI DevEco Device Tool 2.1 Release | OpenHarmony智能设备集成开发环境推荐使用。 | + + +## 源码获取 通过repo下载 方式一（推荐）：通过repo + ssh 下载（需注册公钥，请参考[码云帮助中心](https://gitee.com/help/articles/4191)）。 -``` +```shell repo init -u git@gitee.com:openharmony/manifest.git -b refs/tags/OpenHarmony-v1.1.3-LTS --no-repo-verify repo sync -c repo forall -c 'git lfs pull' @@ -56,166 +28,53 @@ repo forall -c 'git lfs pull' 方式二：通过repo + https 下载。 -``` +```shell repo init -u https://gitee.com/openharmony/manifest.git -b refs/tags/OpenHarmony-v1.1.3-LTS --no-repo-verify repo sync -c repo forall -c 'git lfs pull' ``` -### 通过镜像站点获取 +### 通过镜像站点获取 **表 2** 源码获取路径 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

版本源码

-

版本信息

-

下载站点

-

SHA256校验码

-

全量代码

-

1.1.3

-

站点

-

SHA256校验码

-

Hi3861解决方案（二进制）

-

1.1.3

-

站点

-

SHA256校验码

-

Hi3518解决方案（二进制）

-

1.1.3

-

站点

-

SHA256校验码

-

Hi3516解决方案（二进制）

-

1.1.3

-

站点

-

SHA256校验码

-

Release Notes

-

1.1.3

-

站点

-

-

-
- -## 更新说明 +| 版本源码 | 版本信息 | 下载站点 | SHA256校验码 | +| ------------------------ | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 全量代码 | 1.1.3 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.3/code-v1.1.3-LTS.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.3/code-v1.1.3-LTS.tar.gz.sha256) | +| Hi3861解决方案（二进制） | 1.1.3 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.3/wifiiot-1.1.3.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.3/wifiiot-1.1.3.tar.gz.sha256) | +| Hi3518解决方案（二进制） | 1.1.3 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.3/ipcamera_hi3518ev300-1.1.3.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.3/ipcamera_hi3518ev300-1.1.3.tar.gz.sha256) | +| Hi3516解决方案（二进制） | 1.1.3 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.3/ipcamera_hi3516dv300-1.1.3.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.3/ipcamera_hi3516dv300-1.1.3.tar.gz.sha256) | +| Release Notes | 1.1.3 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.3/OpenHarmony-Release-Notes-1.1.3-LTS.zip) | - | + + +## 更新说明 本版本完全继承了OpenHarmony v1.1.2 LTS的所有特性，并在OpenHarmony v1.1.2 LTS版本的基础上，新增了轻量设备可以在windows环境下的编译版本的特性（请参考[windows开发环境准备](https://device.harmonyos.com/cn/docs/documentation/guide/ide-install-windows-0000001050164976)）。 **表 3** 特性更新说明 - - - - - - - - - - - - - -

子系统

-

新增特性

-

修改特性

-

删除特性

-

芯片平台

-

支持了轻量设备在windows环境下编译版本（pulls/60）

-

N/A

-

N/A

-
- -## 已修复缺陷列表 +| 子系统 | 新增特性 | 修改特性 | 删除特性 | +| -------- | ------------------------------------------------------------ | -------- | -------- | +| 芯片平台 | 支持了轻量设备在windows环境下编译版本（[pulls/60](https://gitee.com/openharmony/device_hisilicon_hispark_pegasus/pulls/60)） | N/A | N/A | + + +## 已修复缺陷列表 在OpenHarmony v1.1.2 LTS版本的基础上，解决并修复的问题见下表。 **表 4** 已修复问题列表 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

ISSUE

-

问题描述

-

I43MZK

-

release1.0.1分支命名中出现空格字符，与外部接口标准不符

-

I44ZGK

-

组件ffmpeg 4.2.2存在未修复的漏洞

-

I41ZMV

-

HI3516刷机之后，在系统bin目录下存在module_ActsUiInterfaceTest1.bin测试文件

-

I3ZOIO

-

los_disk_deinit 资源释放失败

-

I43WLG

-

OsMountRootfs启动失败

-

I48FKQ

-

osEventFlagsGet传NULL时应该返回0

-

I48FL1

-

osThreadNew函数attr为NULL时，创建线程失败

-

I48FLX

-

shell命令中使用rm -r指令尝试删除dev下节点时会导致系统出错

-

I48FMK

-

小型系统的ActsProcessApiTest/UidGidTest/testGetgroup测试用例失败

-

I48FMT

-

nanosleep函数实现存在缺陷

-
+| ISSUE | 问题描述 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [I43MZK](https://gitee.com/openharmony/startup_syspara_lite/issues/I43MZK?from=project-issue) | release1.0.1分支命名中出现空格字符，与外部接口标准不符 | +| [I44ZGK](https://gitee.com/openharmony/device_hisilicon_third_party_ffmpeg/issues/I44ZGK?from=project-issue) | 组件ffmpeg 4.2.2存在未修复的漏洞 | +| [I41ZMV](https://gitee.com/openharmony/graphic_utils/issues/I41ZMV?from=project-issue) | HI3516刷机之后，在系统bin目录下存在module_ActsUiInterfaceTest1.bin测试文件 | +| [I3ZOIO](https://gitee.com/openharmony/kernel_liteos_a/issues/I3ZOIO?from=project-issue) | los_disk_deinit 资源释放失败 | +| [I43WLG](https://gitee.com/openharmony/kernel_liteos_a/issues/I43WLG?from=project-issue) | OsMountRootfs启动失败 | +| [I48FKQ](https://gitee.com/openharmony/kernel_liteos_m/issues/I48FKQ?from=project-issue) | osEventFlagsGet传NULL时应该返回0 | +| [I48FL1](https://gitee.com/openharmony/kernel_liteos_m/issues/I48FL1?from=project-issue) | osThreadNew函数attr为NULL时，创建线程失败 | +| [I48FLX](https://gitee.com/openharmony/kernel_liteos_a/issues/I48FLX?from=project-issue) | shell命令中使用rm -r指令尝试删除dev下节点时会导致系统出错 | +| [I48FMK](https://gitee.com/openharmony/kernel_liteos_a/issues/I48FMK?from=project-issue) | 小型系统的ActsProcessApiTest/UidGidTest/testGetgroup测试用例失败 | +| [I48FMT](https://gitee.com/openharmony/kernel_liteos_a/issues/I48FMT?from=project-issue) | nanosleep函数实现存在缺陷 | + diff --git a/zh-cn/release-notes/OpenHarmony-v1.1.2-LTS.md b/zh-cn/release-notes/OpenHarmony-v1.1.2-LTS.md index 9f7f102cfe2515603feea3c273dba132d70b95f9..69048b3421fe3c5b6e2740135534e1e338a17e71 100644 --- a/zh-cn/release-notes/OpenHarmony-v1.1.2-LTS.md +++ b/zh-cn/release-notes/OpenHarmony-v1.1.2-LTS.md @@ -1,118 +1,39 @@ -# OpenHarmony v1.1.2 LTS +# OpenHarmony v1.1.2 LTS -- [版本概述](#section1846294912228) -- [配套关系](#section395983762117) -- [源码获取](#section84808293211) - - [通过镜像站点获取](#section8394142222113) - - [通过repo下载](#section7180193542317) - -- [更新说明](#section175225345334) -- [已修复缺陷列表](#section11935243172612) - -## 版本概述 +## 版本概述 更新发布LTS（long-term support）长期支持版本OpenHarmony v1.1.2 LTS，本版本在v1.1.1 LTS版本的基础上新增了一些特性和修复了部分缺陷。 -## 配套关系 +## 配套关系 **表 1** 版本软件和工具配套关系 - - - - - - - - - - - - - - - -

软件

-

版本

-

备注

-

OpenHarmony

-

1.1.2 LTS

-

NA

-

HUAWEI DevEco Device Tool（可选）

-

Deveco DeviceTool 2.2 Beta1

-

OpenHarmony智能设备集成开发环境推荐使用。

-
+| 软件 | 版本 | 备注 | +| --------------------------------- | --------------------------- | ----------------------------------------- | +| OpenHarmony | 1.1.2 LTS | NA | +| HUAWEI DevEco Device Tool（可选） | Deveco DeviceTool 2.2 Beta1 | OpenHarmony智能设备集成开发环境推荐使用。 | -## 源码获取 -### 通过镜像站点获取 +## 源码获取 + +### 通过镜像站点获取 **表 2** 源码获取路径 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

版本源码

-

版本信息

-

下载站点

-

SHA256校验码

-

全量代码

-

1.1.2

-

站点

-

SHA256校验码

-

Hi3861解决方案（二进制）

-

1.1.2

-

站点

-

SHA256校验码

-

Hi3518解决方案（二进制）

-

1.1.2

-

站点

-

SHA256校验码

-

Hi3516解决方案（二进制）

-

1.1.2

-

站点

-

SHA256校验码

-

Release Notes

-

1.1.2

-

站点

-

-

-
+| 版本源码 | 版本信息 | 下载站点 | SHA256校验码 | +| ------------------------ | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 全量代码 | 1.1.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.2/code-v1.1.2-LTS.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.2/code-v1.1.2-LTS.tar.gz.sha256) | +| Hi3861解决方案（二进制） | 1.1.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.2/wifiiot-1.1.2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.2/wifiiot-1.1.2.tar.gz.sha256) | +| Hi3518解决方案（二进制） | 1.1.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.2/ipcamera_hi3518ev300-1.1.2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.2/ipcamera_hi3518ev300-1.1.2.tar.gz.sha256) | +| Hi3516解决方案（二进制） | 1.1.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.2/ipcamera_hi3516dv300-1.1.2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/1.1.2/ipcamera_hi3516dv300-1.1.2.tar.gz.sha256) | +| Release Notes | 1.1.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/1.1.2/OpenHarmony-Release-Notes-1.1.2-LTS.zip) | - | + -### 通过repo下载 +### 通过repo下载 方式一（推荐）：通过repo + ssh 下载（需注册公钥，请参考[码云帮助中心](https://gitee.com/help/articles/4191)）。 -``` +```shell repo init -u git@gitee.com:openharmony/manifest.git -b refs/tags/OpenHarmony-v1.1.2-LTS --no-repo-verify repo sync -c repo forall -c 'git lfs pull' @@ -120,246 +41,58 @@ repo forall -c 'git lfs pull' 方式二：通过repo + https 下载。 -``` +```shell repo init -u https://gitee.com/openharmony/manifest.git -b refs/tags/OpenHarmony-v1.1.2-LTS --no-repo-verify repo sync -c repo forall -c 'git lfs pull' ``` -## 更新说明 +## 更新说明 本版本完全继承了OpenHarmony 1.1.1的所有特性，并在OpenHarmony 1.1.1版本的基础上，对部分模块进行了功能扩展和优化，详情请参考下表。 **表 3** 特性更新说明 - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

子系统

-

新增特性

-

修改特性

-

删除特性

-

轻图形

-

新增滑动条修改，支持了滑块样式的设置

-

none

-

none

-

升级

-

适配升级包rsa3072长度的签名算法

-

none

-

none

-

驱动

-

新增了一些osal内部接口

-

sensor模型的优化

-

none

-

全球化

-
  • 新增数字开关、星期等相关数据功能
-
  • 新增Get12HourTimeWithoutAmpm接口
-

none

-

none

-
+| 子系统 | 新增特性 | 修改特性 | 删除特性 | +| ------ | ------------------------------------------------------------ | ---------------- | -------- | +| 轻图形 | 新增滑动条修改，支持了滑块样式的设置 | none | none | +| 升级 | 适配升级包rsa3072长度的签名算法 | none | none | +| 驱动 | 新增了一些osal内部接口 | sensor模型的优化 | none | +| 全球化 | 新增数字开关、星期等相关数据功能新增Get12HourTimeWithoutAmpm接口 | none | none | -## 已修复缺陷列表 + +## 已修复缺陷列表 在OpenHarmony 1.1.1版本的基础上，解决并修复的问题见下表。 **表 4** 已修复问题列表 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

子系统

-

PR NO.

-

问题描述

-

用户程序框架

-

aafwk_aafwk_lite/pulls/35

-

解決linux系统上小概率无法关机的问题

-

-

AI

-

ai_engine/pulls/50

-

修复测试用例client端未释放问题

-

ai_engine/pulls/46

-

修复类成员未初始化的问题

-

IOT硬件

-

applications_sample_wifi_iot/pulls/12

-

修复编译构建错误的问题

-

编译构建

-

build_lite/pulls/151

-

开发的测试用例加入到编译流程

-

-

-

芯片平台

-

-

third_party_ffmpeg/pulls/9

-

修复CVE-2020-22025安全漏洞

-

third_party_ffmpeg/pulls/6

-

修复部分环境依赖valgrind，导致编译失败问题

-

vendor_hisilicon/pulls/39

-

解决release版本编译失败的问题

-

-

分布式调度

-

distributedschedule_dms_fwk_lite/pulls/23

-

测试用例名称更换

-

distributedschedule_samgr_lite/pulls/25

-

修复CVE-2021-22478安全漏洞

-

-

全球化

-

-

global_i18n_lite/pulls/24

-

代码重构，优化全球化i18n.dat资源加载

-

third_party_jerryscript/pulls/22

-

修复mac版本上debug调试时断点概率性无法停住的问题

-

轻图形

-

graphic_ui/pulls/220

-

修复Add和Remove未配套使用问题，修改后UIViewGroup析构不清理子节点

-

graphic_ui/pulls/199

-

修复图片更新路径之后不刷新的问题

-

-

轻内核

-

-

kernel_liteos_a/pulls/385

-

修复CVE-2021-22479安全漏洞

-

kernel_liteos_a/pulls/299

-

删除PRINTK多余的维测日志

-

third_party_musl/pulls/44

-

修复设置随机数种子函数srand的实现的问题

-

启动

-

startup_syspara_lite/pulls/31

-

修改安全补丁日期

-

-

驱动

-

drivers_adapter_khdf_linux/pulls/28

-

修复CVE-2021-22441安全漏洞

-

drivers_adapter/pulls/50

-

修复CVE-2021-22480安全漏洞

-

-

-

-

测试

-

xts_acts/pulls/294

-

删除fs_posix模块的不稳定测试用例

-

xts_acts/pulls/287

-

修复acts测试失败的相关问题

-

xts_acts/pulls/283

-

修复CMSIS测试部分用例概率失败问题

-

xts_acts/pulls/270

-

修改不稳定用例：shared_memory 模块ShmTest.cpp用例ShmTest.testShmatSHM_REMAP 未按照预想逻辑运行问题。

-

xts_acts/pulls/314

-

修复net_posix模块测试卡死问题

-
+| 子系统 | PR NO. | 问题描述 | +| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 用户程序框架 | aafwk_aafwk_lite/pulls/35 | 解決linux系统上小概率无法关机的问题 | +| AI | [ai_engine/pulls/50](https://gitee.com/openharmony/ai_engine/pulls/50) | 修复测试用例client端未释放问题 | +| | [ai_engine/pulls/46](https://gitee.com/openharmony/ai_engine/pulls/46) | 修复类成员未初始化的问题 | +| IOT硬件 | [applications_sample_wifi_iot/pulls/12](https://gitee.com/openharmony/applications_sample_wifi_iot/pulls/12) | 修复编译构建错误的问题 | +| 编译构建 | [build_lite/pulls/151](https://gitee.com/openharmony/build_lite/pulls/151) | 开发的测试用例加入到编译流程 | +| 芯片平台 | [third_party_ffmpeg/pulls/9](https://gitee.com/openharmony/device_hisilicon_third_party_ffmpeg/pulls/9) | 修复CVE-2020-22025安全漏洞 | +| | [third_party_ffmpeg/pulls/6](https://gitee.com/openharmony/device_hisilicon_third_party_ffmpeg/pulls/6) | 修复部分环境依赖valgrind，导致编译失败问题 | +| | [vendor_hisilicon/pulls/39](https://gitee.com/openharmony/vendor_hisilicon/pulls/39) | 解决release版本编译失败的问题 | +| 分布式调度 | distributedschedule_dms_fwk_lite/pulls/23 | 测试用例名称更换 | +| | distributedschedule_samgr_lite/pulls/25 | 修复CVE-2021-22478安全漏洞 | +| 全球化 | [global_i18n_lite/pulls/24](https://gitee.com/openharmony/global_i18n_lite/pulls/24) | 代码重构，优化全球化i18n.dat资源加载 | +| | [third_party_jerryscript/pulls/22](https://gitee.com/openharmony/third_party_jerryscript/pulls/22) | 修复mac版本上debug调试时断点概率性无法停住的问题 | +| 轻图形 | [graphic_ui/pulls/220](https://gitee.com/openharmony/graphic_ui/pulls/220) | 修复Add和Remove未配套使用问题，修改后UIViewGroup析构不清理子节点 | +| | [graphic_ui/pulls/199](https://gitee.com/openharmony/graphic_ui/pulls/199) | 修复图片更新路径之后不刷新的问题 | +| 轻内核 | [kernel_liteos_a/pulls/385](https://gitee.com/openharmony/kernel_liteos_a/pulls/385) | 修复CVE-2021-22479安全漏洞 | +| | [kernel_liteos_a/pulls/299](https://gitee.com/openharmony/kernel_liteos_a/pulls/299) | 删除PRINTK多余的维测日志 | +| | [third_party_musl/pulls/44](https://gitee.com/openharmony/third_party_musl/pulls/44) | 修复设置随机数种子函数srand的实现的问题 | +| 启动 | [startup_syspara_lite/pulls/31](https://gitee.com/openharmony/startup_syspara_lite/pulls/31) | 修改安全补丁日期 | +| 驱动 | [drivers_adapter_khdf_linux/pulls/28](https://gitee.com/openharmony/drivers_adapter_khdf_linux/pulls/28) | 修复CVE-2021-22441安全漏洞 | +| | [drivers_adapter/pulls/50](https://gitee.com/openharmony/drivers_adapter/pulls/50) | 修复CVE-2021-22480安全漏洞 | +| 测试 | [xts_acts/pulls/294](https://gitee.com/openharmony/xts_acts/pulls/294) | 删除fs_posix模块的不稳定测试用例 | +| | [xts_acts/pulls/287](https://gitee.com/openharmony/xts_acts/pulls/287) | 修复acts测试失败的相关问题 | +| | [xts_acts/pulls/283](https://gitee.com/openharmony/xts_acts/pulls/283) | 修复CMSIS测试部分用例概率失败问题 | +| | [xts_acts/pulls/270](https://gitee.com/openharmony/xts_acts/pulls/270) | 修改不稳定用例：shared_memory 模块ShmTest.cpp用例ShmTest.testShmatSHM_REMAP 未按照预想逻辑运行问题。 | +| | [xts_acts/pulls/314](https://gitee.com/openharmony/xts_acts/pulls/314) | 修复net_posix模块测试卡死问题 | + diff --git a/zh-cn/release-notes/OpenHarmony-v2.2-beta2.md b/zh-cn/release-notes/OpenHarmony-v2.2-beta2.md index 1c922e63beb187c63e564a241e392da7319b41fb..6bf93212e98e983dbdb0df840e1f61b111daa45d 100644 --- a/zh-cn/release-notes/OpenHarmony-v2.2-beta2.md +++ b/zh-cn/release-notes/OpenHarmony-v2.2-beta2.md @@ -1,12 +1,6 @@ -# OpenHarmony v2.2 Beta2 +# OpenHarmony v2.2 Beta2 -- [版本概述](#section1677664815431) -- [配套关系](#section13201781528) -- [源码获取](#section1350215462116) -- [更新说明](#section11256141314463) -- [修复缺陷列表](#section3442123281619) - -## 版本概述 +## 版本概述 当前版本在OpenHarmony 2.0 Canary的基础上，针对轻量系统、小型系统和标准系统都有增加新的特性： @@ -24,44 +18,18 @@ - DFX能力增强支持，包括HiLog功能增强、HiEvent功能增强，提供轻量级系统信息dump工具、提供重启维侧框架等。 - AI能力增强支持，包括新增linux内核适配支持、AI引擎支持基于共享内存的数据传输。 -## 配套关系 +## 配套关系 **表 1** 版本软件和工具配套关系 - - - - - - - - - - - - - - - - - - - -

软件

-

版本

-

备注

-

OpenHarmony

-

2.2 Beta2

-

NA

-

HUAWEI DevEco Studio（可选）

-

DevEco Studio 2.2 Beta1

-

OpenHarmony应用开发推荐使用。

-

HUAWEI DevEco Device Tool（可选）

-

Deveco DeviceTool 2.2 Beta1

-

OpenHarmony智能设备集成开发环境推荐使用。

-
- -## 源码获取 +| 软件 | 版本 | 备注 | +| --------------------------------- | --------------------------- | ----------------------------------------- | +| OpenHarmony | 2.2 Beta2 | NA | +| HUAWEI DevEco Studio（可选） | DevEco Studio 2.2 Beta1 | OpenHarmony应用开发推荐使用。 | +| HUAWEI DevEco Device Tool（可选） | Deveco DeviceTool 2.2 Beta1 | OpenHarmony智能设备集成开发环境推荐使用。 | + + +## 源码获取 ### 通过repo下载 @@ -69,7 +37,7 @@ 通过repo + ssh 下载（需注册公钥，请参考[码云帮助中心](https://gitee.com/help/articles/4191)）。 -``` +```shell repo init -u git@gitee.com:openharmony/manifest.git -b refs/tags/OpenHarmony-v2.2-Beta2 --no-repo-verify repo sync -c repo forall -c 'git lfs pull' @@ -79,7 +47,7 @@ repo forall -c 'git lfs pull' 通过repo + https 下载。 -``` +```shell repo init -u https://gitee.com/openharmony/manifest.git -b refs/tags/OpenHarmony-v2.2-Beta2 --no-repo-verify repo sync -c repo forall -c 'git lfs pull' @@ -89,18 +57,18 @@ repo forall -c 'git lfs pull' **表2** 源码获取路径 -| 版本源码 | 版本信息 | 下载站点 | SHA256校验码 | +| 版本源码 | 版本信息 | 下载站点 | SHA256校验码 | | -------- | -------- | -------- | -------- | -| 全量代码（标准、轻量和小型系统） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/code-v2.2-beta2_20210730.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/code-v2.2-beta2_20210730.tar.gz.sha256) | -| 标准系统解决方案（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/standard-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/standard-2.2-Beta2.tar.gz.sha256) | -| Hi3861解决方案（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_pegasus-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_pegasus-2.2-Beta2.tar.gz.sha256) | -| Hi3518解决方案（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_aries-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_aries-2.2-Beta2.tar.gz.sha256) | -| Hi3516解决方案-LiteOS（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_taurus-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_taurus-2.2-Beta2.tar.gz.sha256) | -| Hi3516解决方案-Linux（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_taurus_linux-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_taurus_linux-2.2-Beta2.tar.gz.sha256) | -| Release Notes | 2.2 | [站点](https://gitee.com/openharmony/docs/blob/master/zh-cn/release-notes/OpenHarmony-v2.2-beta2.md) | - | +| 全量代码（标准、轻量和小型系统） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/code-v2.2-beta2_20210730.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/code-v2.2-beta2_20210730.tar.gz.sha256) | +| 标准系统解决方案（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/standard-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/standard-2.2-Beta2.tar.gz.sha256) | +| Hi3861解决方案（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_pegasus-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_pegasus-2.2-Beta2.tar.gz.sha256) | +| Hi3518解决方案（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_aries-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_aries-2.2-Beta2.tar.gz.sha256) | +| Hi3516解决方案-LiteOS（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_taurus-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_taurus-2.2-Beta2.tar.gz.sha256) | +| Hi3516解决方案-Linux（二进制） | 2.2 | [站点](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_taurus_linux-2.2-Beta2.tar.gz) | [SHA256校验码](https://repo.huaweicloud.com/harmonyos/os/2.2-Beta2/hispark_taurus_linux-2.2-Beta2.tar.gz.sha256) | +| Release Notes | 2.2 | [站点](https://gitee.com/openharmony/docs/blob/master/zh-cn/release-notes/OpenHarmony-v2.2-beta2.md) | - | -## 更新说明 +## 更新说明 本版本在继承了OpenHarmony 2.0 Canary的基础上有如下变更。 @@ -108,164 +76,29 @@ repo forall -c 'git lfs pull' **表 3** 版本新增特性表 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

子系统名称

-

标准系统

-

轻量、小型系统

-

分布式文件

-

提供本地system.file异步文件操作JS API，包括文件读写、目录访问、增删等接口。

-

NA

-

驱动

-

3QE85：新增Audio、Camera、USB、马达、ADC驱动模型。

-

LiteOS-M支持HDF框架。

-

电源管理服务

-

新增系统电源状态机、休眠运行锁、休眠唤醒功能。

-
  • 新增充放电状态查询接口、电量查询接口。
  • 提供低功耗模式支持，并提供低功耗模式统一API支持。
-

升级服务

-

新增恢复出厂功能。

-

NA

-

媒体

-
  • 新增音频服务，提供音频基础控制能力。
  • 新增相机服务，提供预览、拍照等基础功能力。
  • 新增媒体服务，提供音频、视频播放能力。
-

NA

-

JS UI框架

-

支持使用JS与C/C++混合开发JS API。

-

NA

-

事件通知

-

支持应用本地发送、取消多行文本通知能力。

-

NA

-

分布式软总线

-

新增软总线自组网功能，可信设备接入到局域网中（ETH\WiFi）后可自发现、无感知的接入到软总线。

-

NA

-

分布式数据管理

-
  • 新增分布式数据管理能力，支持分布式数据库在本地加密存储
  • 支持轻量级偏好数据库
-
  • 提供数据库内容的删除能力。
  • 提供统一的HAL文件系统操作函数实现。
  • 提供相关数据存储的原子操作能力。
  • 提供二进制Value的写入读取能力。
-

系统应用

-

桌面:

-
  • 桌面设置界面UX优化。
  • 新增桌面图标拖拽特性。
-

设置：

-
  • 新增Wlan设置功能。
-

SystemUI：

-
  • 新增卡信号图标显示功能。
-

图库：

-
  • 新增图片、视频资源的查看、移动、复制、删除、重命名等功能。
-

NA

-

全球化子系统

-
  • 完善时间日期格式化能力。
  • 支持时间段的格式化。
  • 新增数字格式化能力。
-
  • 新增构建自定义数据编译能力。
  • 新增构建星期、单复数、数字开关国际化能力。
  • 新增构建应用资源解析和加载机制。
  • 新增构建资源回溯机制。
-

Sample应用

-
  • 计算器中新增分布式功能，组网后支持拉起另一台组网设备上的计算器，两台设备可协同计算，计算数据实时同步。
  • 新增音频播放器应用，支持本地音频播放，组网后可将音乐播放接续至其他组网设备上。
-

NA

-

分布式设备管理

-

新增设备管理系统服务，提供分布式设备账号无关的认证组网能力。

-

NA

-

DFX

-

NA

-
  • 提供LiteOS内核系统信息dump工具。
  • 提供LiteOS内核死机重启维测框架。
  • 新增数字格式化能力。
  • HiLog功能增强。
  • HiEvent功能增强。
-

内核

-

NA

-
  • 支持轻量级Linux版本。
  • proc文件系统增强。
  • 新增mksh命令解析器。
  • 文件系统维测增强。
  • LiteOS-A內核模块支持可配置。
  • 支持LiteOS-A小系统三方芯片适配。
  • LiteOS-M支持三方组件Mbedtls编译。
  • LiteOS-M支持三方组件curl编译。
  • 支持轻量级shell框架和常用调测命令。
  • LiteOS-M支持ARM9架构。
  • 支持基于NOR Flash的littlefs文件系统。
  • LiteOS-M对外提供统一的文件系统操作接口。
  • 新增Namecache模块、Vnode管理、Lookup模块。
-

图形图像

-

NA

-
  • 支持A4\A8、LUT8、TSC图片格式作为输入。
  • 支持多语言字体对齐。
  • UIKit支持显示控件轮廓。
  • ScrollView/List支持通过弧形进度条展示滑动进度。
  • 支持开关按钮/复选框/单选按钮动效。
  • UIKit支持点阵字体产品化解耦。
  • UI框架提供统一多后端框架支持多芯片平台。
  • UIKit组件支持margin/padding。
  • 圆形/胶囊按钮支持缩放和白色蒙层动效。
-

编译构建

-

NA

-

支持开源软件的通用patch框架。

-

启动恢复

-

NA

-

支持恢复出厂设置支持多语言字体对齐。

-

分布式调度

-

NA

-

支持轻量设备启动富设备上的Ability。

-

AI

-

NA

-
  • AI子系统添加Linux内核适配，编译选项支持。
  • AI引擎支持基于共享内存的数据传输。
-
+| 子系统名称 | 标准系统 | 轻量、小型系统 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 分布式文件 | 提供本地system.file异步文件操作JS API，包括文件读写、目录访问、增删等接口。 | NA | +| 驱动 | 新增Audio、Camera、USB、马达、ADC驱动模型。 | LiteOS-M支持HDF框架。 | +| 电源管理服务 | 新增系统电源状态机、休眠运行锁、休眠唤醒功能。 | - 新增充放电状态查询接口、电量查询接口。
- 提供低功耗模式支持，并提供低功耗模式统一API支持。 | +| 升级服务 | 新增恢复出厂功能。 | NA | +| 媒体 | - 新增音频服务，提供音频基础控制能力。
- 新增相机服务，提供预览、拍照等基础功能力。
- 新增媒体服务，提供音频、视频播放能力。 | NA | +| JS UI框架 | 支持使用JS与C/C++混合开发JS API。 | NA | +| 事件通知 | 支持应用本地发送、取消多行文本通知能力。 | NA | +| 分布式软总线 | 新增软总线自组网功能，可信设备接入到局域网中（ETH\WiFi）后可自发现、无感知的接入到软总线。 | NA | +| 分布式数据管理 | - 新增分布式数据管理能力，支持分布式数据库在本地加密存储
- 支持轻量级偏好数据库 | - 提供数据库内容的删除能力。
- 提供统一的HAL文件系统操作函数实现。
- 提供相关数据存储的原子操作能力。
- 提供二进制Value的写入读取能力。 | +| 系统应用 | 桌面:
- 桌面设置界面UX优化。
- 新增桌面图标拖拽特性。
设置：
- 新增Wlan设置功能。
SystemUI：
- 新增卡信号图标显示功能。
图库：
- 新增图片、视频资源的查看、移动、复制、删除、重命名等功能。 | NA | +| 全球化子系统 | - 完善时间日期格式化能力。
- 支持时间段的格式化。
- 新增数字格式化能力。 | - 新增构建自定义数据编译能力。
- 新增构建星期、单复数、数字开关国际化能力。
- 新增构建应用资源解析和加载机制。
- 新增构建资源回溯机制。 | +| Sample应用 | - 计算器中新增分布式功能，组网后支持拉起另一台组网设备上的计算器，两台设备可协同计算，计算数据实时同步。
- 新增音频播放器应用，支持本地音频播放，组网后可将音乐播放接续至其他组网设备上。 | NA | +| 分布式设备管理 | 新增设备管理系统服务，提供分布式设备账号无关的认证组网能力。 | NA | +| DFX | NA | - 提供LiteOS内核系统信息dump工具。
- 提供LiteOS内核死机重启维测框架。
- 新增数字格式化能力。
- HiLog功能增强。
- HiEvent功能增强。 | +| 内核 | NA | - 支持轻量级Linux版本。
- proc文件系统增强。
- 新增mksh命令解析器。
- 文件系统维测增强。
- LiteOS-A內核模块支持可配置。
- 支持LiteOS-A小系统三方芯片适配。
- LiteOS-M支持三方组件Mbedtls编译。
- LiteOS-M支持三方组件curl编译。
- 支持轻量级shell框架和常用调测命令。
- LiteOS-M支持ARM9架构。
- 支持基于NOR Flash的littlefs文件系统。
- LiteOS-M对外提供统一的文件系统操作接口。
- 新增Namecache模块、Vnode管理、Lookup模块。 | +| 图形图像 | NA | - 支持A4\A8、LUT8、TSC图片格式作为输入。
- 支持多语言字体对齐。
- UIKit支持显示控件轮廓。
- ScrollView/List支持通过弧形进度条展示滑动进度。
- 支持开关按钮/复选框/单选按钮动效。
- UIKit支持点阵字体产品化解耦。
- UI框架提供统一多后端框架支持多芯片平台。
- UIKit组件支持margin/padding。
- 圆形/胶囊按钮支持缩放和白色蒙层动效。 | +| 编译构建 | NA | 支持开源软件的通用patch框架。 | +| 启动恢复 | NA | 支持恢复出厂设置支持多语言字体对齐。 | +| 分布式调度 | NA | 支持轻量设备启动富设备上的Ability。 | +| AI | NA | - AI子系统添加Linux内核适配，编译选项支持。
- AI引擎支持基于共享内存的数据传输。 | + ### API变更 @@ -275,113 +108,30 @@ API变更请参考： [Native API 差异报告](api-change/v2.2-beta2/native-apidiff-v2.2-beta2.md) -## 修复缺陷列表 +## 修复缺陷列表 **表 4** **解决的缺陷ISSUE列表** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

ISSUE单号

-

问题描述

-

I3I31W

-

ActsNFSTest.bin会引起内核crash

-

I3D49E

-

uboot的路径不对

-

I3D71U

-

【驱动子系统】反复reset，启动到hmac_main_init SUCCESSULLY后，高概率出现系统挂死

-

I3DGZW

-

【应用程序框架子系统】HI3516开源板进入屏保后 ，点击触摸屏，出现蓝屏问题

-

I3DHIL

-

【系统问题】HI3518开源板剩余空间不足，导致ACTS用例大量失败

-

I3DU36

-

【应用程序框架子系统】ipcamera bm 查询命令失效

-

I3EALU

-

【媒体子系统】cameraActs 用例执行时，找不到相机配置文件，初始失败

-

I3EGUX

-

【可靠性问题】反复reset，出现一次KIdle进程crash，系统挂死无法启动

-

I3EH4E

-

【流水线问题】高概率出现：uname无响应，然后执行reset也无响应

-

I3EQJA

-

【文件系统】cat /proc/mounts功能不可用

-

I3EQRC

-

磁盘文件映射延迟测试：并发3个测试进程，系统crash

-

I3HVL0

-

3861编译失败，报错[OHOS ERROR] Fatal error: invalid -march= option:rv32imac

-

I3TS1Y

-

压力场景下文件相关Vnode资源耗尽

-

I3TXT8

-

孤儿进程无法回收，压力场景下TCB资源耗尽

-

I3UWXI

-

libwap.so 存在已知一般漏洞： CVE-2021-30004，CVSS：5.3；漏洞发布日期：2021-04-02，不符合产品发布要求，需要解决。

-

I3SWY2

-

高概率出现KProcess进程挂死，质量不达标

-

I3YJRO

-

liteos-a內核模块可配置编译失败

-

I3YNWM

-

文件系统维测增强功能在该版本有问题

-

I3VEOG

-

bin目录下没有mksh和toybox，导致已转测的toybox命令集无法测试

-
+| ISSUE单号 | 问题描述 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [I3I31W](https://gitee.com/openharmony/kernel_liteos_a/issues/I3I31W) | ActsNFSTest.bin会引起内核crash | +| [I3D49E](https://gitee.com/openharmony/docs/issues/I3D49E) | uboot的路径不对 | +| [I3D71U](https://gitee.com/openharmony-retired/drivers_adapter_khdf_liteos/issues/I3D71U) | 【驱动子系统】反复reset，启动到hmac_main_init SUCCESSULLY后，高概率出现系统挂死 | +| I3DGZW | 【应用程序框架子系统】HI3516开源板进入屏保后 ，点击触摸屏，出现蓝屏问题 | +| [I3DHIL](https://gitee.com/openharmony/community/issues/I3DHIL) | 【系统问题】HI3518开源板剩余空间不足，导致ACTS用例大量失败 | +| I3DU36 | 【应用程序框架子系统】ipcamera bm 查询命令失效 | +| [I3EALU](https://gitee.com/openharmony/multimedia_camera_lite/issues/I3EALU) | 【媒体子系统】cameraActs 用例执行时，找不到相机配置文件，初始失败 | +| [I3EGUX](https://gitee.com/openharmony/release-management/issues/I3EGUX) | 【可靠性问题】反复reset，出现一次KIdle进程crash，系统挂死无法启动 | +| [I3EH4E](https://gitee.com/openharmony/community/issues/I3EH4E) | 【流水线问题】高概率出现：uname无响应，然后执行reset也无响应 | +| [I3EQJA](https://gitee.com/openharmony/kernel_liteos_a/issues/I3EQJA) | 【文件系统】cat /proc/mounts功能不可用 | +| [I3EQRC](https://gitee.com/openharmony/kernel_liteos_a/issues/I3EQRC) | 磁盘文件映射延迟测试：并发3个测试进程，系统crash | +| [I3HVL0](https://gitee.com/openharmony/docs/issues/I3HVL0) | 3861编译失败，报错[OHOS ERROR] Fatal error: invalid -march= option:rv32imac | +| [I3TS1Y](https://gitee.com/openharmony/kernel_liteos_a/issues/I3TS1Y) | 压力场景下文件相关Vnode资源耗尽 | +| [I3TXT8](https://gitee.com/openharmony/startup_init_lite/issues/I3TXT8) | 孤儿进程无法回收，压力场景下TCB资源耗尽 | +| [I3UWXI](https://gitee.com/openharmony/applications_sample_wifi_iot/issues/I3UWXI) | libwap.so 存在已知一般漏洞： CVE-2021-30004，CVSS：5.3；漏洞发布日期：2021-04-02，不符合产品发布要求，需要解决。 | +| [I3SWY2](https://gitee.com/openharmony/kernel_liteos_a/issues/I3SWY2) | 高概率出现KProcess进程挂死，质量不达标 | +| [I3YJRO](https://gitee.com/openharmony/kernel_liteos_m/issues/I3YJRO) | liteos-a內核模块可配置编译失败 | +| [I3YNWM](https://gitee.com/openharmony/kernel_liteos_a/issues/I3YNWM) | 文件系统维测增强功能在该版本有问题 | +| [I3VEOG](https://gitee.com/openharmony/kernel_liteos_a/issues/I3VEOG) | bin目录下没有mksh和toybox，导致已转测的toybox命令集无法测试 | + diff --git a/zh-cn/release-notes/OpenHarmony-v3.0-LTS.md b/zh-cn/release-notes/OpenHarmony-v3.0-LTS.md index 93ef817b5c2807a456720fc43d8d897a49f6fd51..144e6e9552c8acf164912d7cdcd9268873f7f238 100644 --- a/zh-cn/release-notes/OpenHarmony-v3.0-LTS.md +++ b/zh-cn/release-notes/OpenHarmony-v3.0-LTS.md @@ -1,15 +1,5 @@ # OpenHarmony 3.0 LTS -- [版本概述](#版本概述) -- [配套关系](#配套关系) -- [源码获取](#源码获取) -- [更新说明](#更新说明) - - [特性变更](#特性变更) - - [API变更](#api变更) - - [芯片及开发板适配](#芯片及开发板适配) -- [修复缺陷列表](#修复缺陷列表) -- [遗留缺陷列表](#遗留缺陷列表) - ## 版本概述 当前版本在OpenHarmony 2.2 Beta2的基础上，针对标准系统、轻量系统和小型系统更新内容： @@ -71,7 +61,7 @@ 通过repo + ssh 下载（需注册公钥，请参考[码云帮助中心](https://gitee.com/help/articles/4191)）。 -``` +```shell repo init -u git@gitee.com:openharmony/manifest.git -b refs/tags/OpenHarmony-v3.0-LTS --no-repo-verify repo sync -c repo forall -c 'git lfs pull' @@ -81,7 +71,7 @@ repo forall -c 'git lfs pull' 通过repo + https 下载。 -``` +```shell repo init -u https://gitee.com/openharmony/manifest.git -b refs/tags/OpenHarmony-v3.0-LTS --no-repo-verify repo sync -c repo forall -c 'git lfs pull' @@ -152,12 +142,12 @@ API变更请参考：[JS API 差异报告](api-change/v3.0-LTS/js-apidiff-v3.0-l | ISSUE单号 | 问题描述 | | -------- | -------- | | [I45AVP](https://gitee.com/openharmony/hiviewdfx_hilog/issues/I45AVP) | 执行hilog落盘之后hilog命令执行失败 | -| [I47EPA](https://gitee.com/openharmony/appexecfwk_appexecfwk_lite/issues/I47EPA?from=project-issue) | 入参为空或无效时，GetBundleSize接口返回错误 | +| I47EPA | 入参为空或无效时，GetBundleSize接口返回错误 | | [I434AD](https://gitee.com/openharmony/multimedia_camera_lite/issues/I434AD) | Hi3516DV300轻量级系统常驻内存超基线 | | [I434P1](https://gitee.com/openharmony/multimedia_camera_lite/issues/I434P1) | Hi3518EV300轻量级系统常驻内存超基线 | | [I46I6K](https://gitee.com/openharmony/multimedia_media_lite/issues/I46I6K?from=project-issue) | 多媒体子系统相关代码存在安全编码问题 | | [I46E6S](https://gitee.com/openharmony/kernel_liteos_m/issues/I46E6S?from=project-issue) | 轻量级内核模块编译添加-Werror编译选项 | -| [I47ETO](https://gitee.com/openharmony/appexecfwk_appexecfwk_lite/issues/I47ETO?from=project-issue -) | 权限校验没有生效，使用测试 bin 直接调用无权限 hap，期望查询失败返回 0，结果查询成功 | +| I47ETO | 权限校验没有生效，使用测试 bin 直接调用无权限 hap，期望查询失败返回 0，结果查询成功 | | [I48A2I](https://gitee.com/openharmony/drivers_peripheral/issues/I48A2I) | Hi3516DV300轻量级版本调用AllocMem接口测试，单板挂死 | | [I42LCU](https://gitee.com/openharmony/kernel_liteos_m/issues/I42LCU) | 集成测试开发板移植指导中需增加线程不足的确认方法和配置线程个数的方法 | | [I3IPD7](https://gitee.com/openharmony/kernel_liteos_m/issues/I3IPD7) | 不支持osThreadExit/join函数需要在头文件中说明 | @@ -171,7 +161,7 @@ API变更请参考：[JS API 差异报告](api-change/v3.0-LTS/js-apidiff-v3.0-l | ISSUE单号 | 问题描述 | | -------- | -------- | -| [I46A6H](https://gitee.com/openharmony/ace_ace_engine/issues/I46A6H) | XTS子系统压力测试过程中libace.z.so异常导致ohos.samples.flashlight出现cppcrash异常 | +| I46A6H | XTS子系统压力测试过程中libace.z.so异常导致ohos.samples.flashlight出现cppcrash异常 | | [I48HLN](https://gitee.com/openharmony/app_samples/issues/I48HLN) | Demo&应用子系统- [ JsCanvas] 清除的button功能未生效 | | [I46HH7](https://gitee.com/openharmony/drivers_peripheral/issues/I46HH7) | 驱动子系统-标准系统单板WLAN测试用例失败 | | [I4312A](https://gitee.com/openharmony/communication_dsoftbus/issues/I4312A) | 【2.2 Beta2】【软总线】已组网，断1端网络后，自组网失败(GetAllNodeDeviceInfo返回null) | @@ -187,7 +177,7 @@ API变更请参考：[JS API 差异报告](api-change/v3.0-LTS/js-apidiff-v3.0-l | ISSUE | 问题描述 | 影响 | 计划解决日期 | | -------- | -------- | -------- | -------- | | [I48IM7](https://gitee.com/openharmony/hiviewdfx_hilog/issues/I48IM7) | 运行hilog压力测试，hilogd异常重启，且hilog命令一直无法使用 | 压力测试下，低概率出现日志输出异常，调测场景可正常使用。 | 10月30日 | -| [I48YPH](https://gitee.com/openharmony/security_deviceauth/issues/I48YPH) | 【软总线-组网】测试发现和组网性能(循环离网-发现-组网)110次组网失败3次 | 低概率3/110，失败后重新发起组网即可。 | 10月30日 | +| I48YPH | 【软总线-组网】测试发现和组网性能(循环离网-发现-组网)110次组网失败3次 | 低概率3/110，失败后重新发起组网即可。 | 10月30日 | | [I4BVVW](https://gitee.com/openharmony/communication_dsoftbus/issues/I4BVVW) | 【软总线-组网】标准系统与手机开关网络自组网成功率97%失败3次需分析失败原因 | 低概率出现组网失败。 | 10月30日 | | [I4BXWY](https://gitee.com/openharmony/multimedia_media_standard/issues/I4BXWY) | Hi3516音频录制后播放有杂音 | 仅在使用此开发板时，影响录制音频的播放体验效果。 | 10月30日 | | [I4BXY1](https://gitee.com/openharmony/multimedia_camera_standard/issues/I4BXY1) | 视频录制后前几秒没声音，播放声画不同步，在板子播放会卡顿，音源较远时，有杂音 | 仅在使用此开发板时，影响录制视频的播放体验效果。 | 10月30日 | diff --git a/zh-cn/website.md b/zh-cn/website.md index 1edc4cf36f5c38ac154fac3af0336e2c89ab9a03..7e1cabba1fa1d0e67d0593d45f1e4bc87e5a0e29 100644 --- a/zh-cn/website.md +++ b/zh-cn/website.md @@ -10,18 +10,19 @@ - [OpenHarmony v3.1.1 Release (2022-05-31)](release-notes/OpenHarmony-v3.1.1-release.md) - [OpenHarmony v3.1 Release (2022-03-30)](release-notes/OpenHarmony-v3.1-release.md) - [OpenHarmony v3.1 Beta (2021-12-31)](release-notes/OpenHarmony-v3.1-beta.md) + - [OpenHarmony v3.0.5 LTS (2022-07-01)](release-notes/OpenHarmony-v3.0.5-LTS.md) - [OpenHarmony v3.0.3 LTS (2022-04-08)](release-notes/OpenHarmony-v3.0.3-LTS.md) - [OpenHarmony v3.0.2 LTS (2022-03-18)](release-notes/OpenHarmony-v3.0.2-LTS.md) - [OpenHarmony v3.0.1 LTS (2022-01-12)](release-notes/OpenHarmony-v3.0.1-LTS.md) - [OpenHarmony v3.0 LTS (2021-09-30)](release-notes/OpenHarmony-v3.0-LTS.md) - - - OpenHarmony 2.x Releases - + +- OpenHarmony 2.x Releases + - [OpenHarmony v2.2 beta2 (2021-08-04)](release-notes/OpenHarmony-v2.2-beta2.md) - [OpenHarmony 2.0 Canary (2021-06-01)](release-notes/OpenHarmony-2-0-Canary.md) - - - OpenHarmony 1.x Releases - + +- OpenHarmony 1.x Releases + - [OpenHarmony v1.1.4 LTS (2022-02-11)](release-notes/OpenHarmony-v1-1-4-LTS.md) - [OpenHarmony v1.1.3 LTS (2021-09-30)](release-notes/OpenHarmony-v1-1-3-LTS.md) - [OpenHarmony v1.1.2 LTS (2021-08-04)](release-notes/OpenHarmony-v1.1.2-LTS.md) @@ -60,7 +61,6 @@ - [用户身份认证](release-notes/api-change/v3.2-beta2/js-apidiff-user-authentication.md) - [Web](release-notes/api-change/v3.2-beta2/js-apidiff-web.md) - [窗口管理](release-notes/api-change/v3.2-beta2/js-apidiff-window.md) - - OpenHarmony 3.2 Beta1 - JS API差异报告 - [元能力](release-notes/api-change/v3.2-beta1/js-apidiff-ability.md) @@ -93,7 +93,7 @@ - [包管理](release-notes/api-change/v3.1-Release/js-apidiff-bundle.md) - [基础通信](release-notes/api-change/v3.1-Release/js-apidiff-communicate.md) - [语言编译器运行时](release-notes/api-change/v3.1-Release/js-apidiff-compiler-and-runtime.md) - - [DFX](release-notes/api-change/v3.1-Release/js-apidiff-dfx.md) + - [DFX](release-notes/api-change/v3.1-Release/js-apidiff-dfx.md) - [分布式数据管理](release-notes/api-change/v3.1-Release/js-apidiff-distributed-data.md) - [分布式硬件](release-notes/api-change/v3.1-Release/js-apidiff-distributed-hardware.md) - [事件通知](release-notes/api-change/v3.1-Release/js-apidiff-event-and-notification.md) @@ -125,10 +125,20 @@ - [资源调度](release-notes/api-change/v3.1-Release/js-apidiff-resource-scheduler_api-9-canary.md) - [窗口管理](release-notes/api-change/v3.1-Release/js-apidiff-window_api-9-canary.md) - [Native API差异报告](release-notes/api-change/v3.1-Release/native-apidiff-v3.1-release.md) + - OpenHarmony 3.1 Beta + - [JS API差异报告](release-notes/api-change/v3.1-beta/js-apidiff-v3.1-beta.md) + - [Native API差异报告](release-notes/api-change/v3.1-beta/native-apidiff-v3.1-beta.md) + - OpenHarmony 3.0 LTS + - [JS API差异报告](release-notes/api-change/v3.0-LTS/js-apidiff-v3.0-lts.md) + - OpenHarmony v2.2 Beta2 + - [JS API差异报告](release-notes/api-change/v2.2-beta2/js-apidiff-v2.2-beta2.md) + - [Native API差异报告](release-notes/api-change/v2.2-beta2/native-apidiff-v2.2-beta2.md) - 变更说明 - OpenHamrony 3.2 Beta2 - - [3.2 beta2相对3.2 beta1变更详细说明](release-notes\changelog\v3.2-beta2\changelog-v3.2-beta2.md) - - [OpenHarmony启用应用沙箱机制-适配指导](release-notes\changelog\v3.2-beta2\application-sandbox-adaptation-guide.md) + - [3.2 beta2相对3.2 beta1变更详细说明](release-notes/changelog/v3.2-beta2/changelog-v3.2-beta2.md) + - [OpenHarmony启用应用沙箱机制-适配指导](release-notes/changelog/v3.2-beta2/application-sandbox-adaptation-guide.md) + - OpenHarmony 3.1 Beta + - [3.1 beta相对于3.0变更详细说明](release-notes/api-change/v3.1-beta/changelog-v3.1-beta.md) - OpenHarmony三方组件 - [OpenHarmony三方组件简介](third-party-components/third-party-components-introduction.md) - [OpenHarmony JS/TS三方组件使用指导](third-party-components/npm-third-party-guide.md)