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/docker/LICENSE b/docker/LICENSE deleted file mode 100755 index 261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64..0000000000000000000000000000000000000000 --- a/docker/LICENSE +++ /dev/null @@ -1,201 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/docker/build.sh b/docker/build.sh deleted file mode 100755 index e1a7618251929cd060b0e33c4763e4bb5e5f9057..0000000000000000000000000000000000000000 --- a/docker/build.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash - -# Copyright (c) 2020 Huawei Device Co., Ltd. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -docker build -t openharmony-docker:1.0.0 . diff --git a/en/application-dev/IDL/idl-guidelines.md b/en/application-dev/IDL/idl-guidelines.md index cb075f42cf7ef08d02f78ec1d0377c84d5a0bbf6..661b2532c49d36c79855c3e0530326ef590c7cd2 100644 --- a/en/application-dev/IDL/idl-guidelines.md +++ b/en/application-dev/IDL/idl-guidelines.md @@ -590,7 +590,7 @@ export default class IdlTestServiceProxy implements IIdlTestService { testIntTransaction(data: number, callback: testIntTransactionCallback): void { - let _option = new rpc.MessageOption(rpc.MessageOption.TF_SYNC); + let _option = new rpc.MessageOption(); let _data = new rpc.MessageParcel(); let _reply = new rpc.MessageParcel(); _data.writeInt(data); @@ -612,7 +612,7 @@ export default class IdlTestServiceProxy implements IIdlTestService { testStringTransaction(data: string, callback: testStringTransactionCallback): void { - let _option = new rpc.MessageOption(rpc.MessageOption.TF_SYNC); + let _option = new rpc.MessageOption(); let _data = new rpc.MessageParcel(); let _reply = new rpc.MessageParcel(); _data.writeString(data); diff --git a/en/application-dev/ability/figures/page-ability-lifecycle.png b/en/application-dev/ability/figures/page-ability-lifecycle.png index edb49acd0647f3af7355ceda987c5ca812866128..b35954967bb9c733725da2f0700481932619ae45 100644 Binary files a/en/application-dev/ability/figures/page-ability-lifecycle.png and b/en/application-dev/ability/figures/page-ability-lifecycle.png differ 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/ability/stage-serviceextension.md b/en/application-dev/ability/stage-serviceextension.md index 0bda2156cdaa3b79c694f399453208ed9a0d13cf..5154a97d6a65bc787596f54466e7983a60a8bb11 100644 --- a/en/application-dev/ability/stage-serviceextension.md +++ b/en/application-dev/ability/stage-serviceextension.md @@ -39,33 +39,36 @@ OpenHarmony does not support creation of a Service Extension ability for third-p ``` -2. Customize a class that inherits from **ServiceExtensionAbility** in the .ts file in the directory where the Service Extension ability is defined and override the lifecycle callbacks of the base class. The code sample is as follows: +2. Customize a class that inherits from **ServiceExtensionAbility** in the .ts file in the directory where the Service Extension ability is defined (**entry\src\main\ets\ServiceExtAbility\ServiceExtAbility.ts** by default) and override the lifecycle callbacks of the base class. The code sample is as follows: ```js + import ServiceExtensionAbility from '@ohos.application.ServiceExtensionAbility' import rpc from '@ohos.rpc' + class StubTest extends rpc.RemoteObject { - constructor(des) { + constructor(des) { super(des); - } - onRemoteRequest(code, data, reply, option) { - } + } + onRemoteRequest(code, data, reply, option) { + } } - - class ServiceExt extends ServiceExtensionAbility { - console.log('onCreate, want:' + want.abilityName); - } - onRequest(want, startId) { - console.log('onRequest, want:' + want.abilityName); - } - onConnect(want) { - console.log('onConnect , want:' + want.abilityName); - return new StubTest("test"); - } - onDisconnect(want) { - console.log('onDisconnect, want:' + want.abilityName); - } - onDestroy() { - console.log('onDestroy'); - } + + class ServiceExtAbility extends ServiceExtensionAbility { + onCreate(want) { + console.log('onCreate, want:' + want.abilityName); + } + onRequest(want, startId) { + console.log('onRequest, want:' + want.abilityName); + } + onConnect(want) { + console.log('onConnect , want:' + want.abilityName); + return new StubTest("test"); + } + onDisconnect(want) { + console.log('onDisconnect, want:' + want.abilityName); + } + onDestroy() { + console.log('onDestroy'); + } } - ``` + ``` \ No newline at end of file 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/device/vibrator-guidelines.md b/en/application-dev/device/vibrator-guidelines.md index ab4c8234ba4147008ea9515d20e23506eddd3f13..4f49e7996188a7bc668e23fc2a21a1a29ec6e562 100644 --- a/en/application-dev/device/vibrator-guidelines.md +++ b/en/application-dev/device/vibrator-guidelines.md @@ -65,9 +65,9 @@ For details about the APIs, see [Vibrator](../reference/apis/js-apis-vibrator.md import vibrator from "@ohos.vibrator" vibrator.vibrate(1000).then((error) => { if (error) { // The call fails, and error.code and error.message are printed. - Console.log("Promise return failed.error.code " + error.code + "error.message " + error.message); + console.log("Promise return failed.error.code " + error.code + "error.message " + error.message); } else { // The call is successful, and the device starts to vibrate. - Console.log("Promise returned to indicate a successful vibration.") + console.log("Promise returned to indicate a successful vibration.") } }) ``` @@ -78,9 +78,9 @@ For details about the APIs, see [Vibrator](../reference/apis/js-apis-vibrator.md import vibrator from "@ohos.vibrator" vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then((error) => { if (error) { // The call fails, and error.code and error.message are printed. - Console.log("Promise return failed.error.code " + error.code + "error.message " + error.message); + console.log("Promise return failed.error.code " + error.code + "error.message " + error.message); } else { // The call is successful, and the device stops vibrating. - Console.log("Promise returned to indicate a successful stop."); + console.log("Promise returned to indicate successful."); } }) ``` 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/media/image.md b/en/application-dev/media/image.md index a262b3e219970b107ee5debdbc1254907f9d3e22..5be7a47cf20f0269c670593bf412bee5dd92162f 100644 --- a/en/application-dev/media/image.md +++ b/en/application-dev/media/image.md @@ -267,7 +267,7 @@ imageSourceApi.getImageInfo(imageInfo => { }) // Update incremental data. -imageSourceIncrementalSApi.updateData(array, false, 0, 10,(error,data )=> {}) +imageSourceIncrementalSApi.updateData(array, false, 0, 10,(error, data)=> {}) ``` diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 6b5bbc8aa3d671c4cf0b01316db441d33c0f189f..97c99233c3ded3f9eddbaadb68496ce9b3e55e48 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) @@ -37,6 +38,7 @@ - [@ohos.application.Configuration](js-apis-configuration.md) - [@ohos.application.ConfigurationConstant](js-apis-configurationconstant.md) - [@ohos.application.EnvironmentCallback](js-apis-application-EnvironmentCallback.md) + - [@ohos.application.errorManager](js-apis-errorManager.md) - [@ohos.application.formBindingData](js-apis-formbindingdata.md) - [@ohos.application.formError](js-apis-formerror.md) - [@ohos.application.formHost](js-apis-formhost.md) @@ -68,18 +70,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 +99,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) @@ -115,6 +125,7 @@ - Resource Scheduling - [@ohos.backgroundTaskManager](js-apis-backgroundTaskManager.md) + - [@ohos.distributedMissionManager](js-apis-distributedMissionManager.md) - [@ohos.workScheduler ](js-apis-workScheduler.md) - [@ohos.WorkSchedulerExtensionAbility](js-apis-WorkSchedulerExtensionAbility.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..cd4e27214b3617970071bcfb8e4e5b1c76bc2a2c 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** @@ -618,7 +888,7 @@ Disconnects a connection. This API uses an asynchronous callback to return the r startAbilityByCall(want: Want): Promise<Caller>; -Obtains the caller interface of the specified ability, and if the specified ability is not started, starts the ability in the background. +Starts an ability in the foreground or background and obtains the caller interface for communication with the ability. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -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 ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| **Return value** @@ -637,22 +907,40 @@ Obtains the caller interface of the specified ability, and if the specified abil **Example** ```js - import Ability from '@ohos.application.Ability'; - var caller; - export default class MainAbility extends Ability { - onWindowStageCreate(windowStage) { - this.context.startAbilityByCall({ - bundleName: "com.example.myservice", - abilityName: "MainAbility", - deviceId: "" - }).then((obj) => { - caller = obj; - console.log('Caller GetCaller Get ' + caller); - }).catch((e) => { - console.log('Caller GetCaller error ' + e); - }); + let caller = undefined; + + // Start an ability in the background without passing parameters. + var wantBackground = { + bundleName: "com.example.myservice", + moduleName: "entry", + abilityName: "MainAbility", + deviceId: "" + }; + this.context.startAbilityByCall(wantBackground) + .then((obj) => { + caller = obj; + console.log('GetCaller success'); + }).catch((error) => { + console.log(`GetCaller failed with ${error}`); + }); + + // Start an ability in the foreground with ohos.aafwk.param.callAbilityToForeground in parameters set to true. + var wantForeground = { + bundleName: "com.example.myservice", + moduleName: "entry", + abilityName: "MainAbility", + deviceId: "", + parameters: { + "ohos.aafwk.param.callAbilityToForeground": true } - } + }; + this.context.startAbilityByCall(wantForeground) + .then((obj) => { + caller = obj; + console.log('GetCaller success'); + }).catch((error) => { + console.log(`GetCaller failed with ${error}`); + }); ``` ## AbilityContext.startAbilityWithAccount @@ -671,8 +959,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 +994,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 +1033,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 +1062,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 +1071,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 +1088,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 +1102,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 +1294,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..79ad744268f719cf6c9c24310e27e91c00ae9630 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 8+ | number | No | Account ID. This is a system API. | +| videoState 8+ | [VideoStateType](#videostatetype7) | No | Video state type. This is a system API. | +| dialScene 8+ | [DialScene](#dialscene8) | No | Dialup scenario. This is a system API. | +| dialType 8+ | [DialType](#dialtype8) | No | Dialup type. This 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-camera.md b/en/application-dev/reference/apis/js-apis-camera.md index fac4104f5cb135b5c5afa45127cdbd488a9a6225..410bfd51d89defc480e3d4dde2da2a351b1fbd24 100644 --- a/en/application-dev/reference/apis/js-apis-camera.md +++ b/en/application-dev/reference/apis/js-apis-camera.md @@ -30,7 +30,7 @@ Obtains a **CameraManager** instance. This API uses an asynchronous callback to ```js camera.getCameraManager(context, (err, cameraManager) => { if (err) { - console.error('Failed to get the CameraManager instance ${err.message}'); + console.error(`Failed to get the CameraManager instance ${err.message}`); return; } console.log('Callback returned with the CameraManager instance'); @@ -146,10 +146,10 @@ Obtains supported cameras. This API uses an asynchronous callback to return the ```js cameraManager.getSupportedCameras((err, cameras) => { if (err) { - console.error('Failed to get the cameras. ${err.message}'); + console.error(`Failed to get the cameras. ${err.message}`); return; } - console.log('Callback returned with an array of supported cameras: ' + cameras.length); + console.log(`Callback returned with an array of supported cameras: ${cameras.length}`); }) ``` @@ -172,7 +172,7 @@ Obtains supported cameras. This API uses a promise to return the result. ```js cameraManager.getSupportedCameras().then((cameraArray) => { - console.log('Promise returned with an array of supported cameras: ' + cameraArray.length); + console.log(`Promise returned with an array of supported cameras: ${cameraArray.length}`); }) ``` @@ -188,7 +188,7 @@ Obtains the output capability supported by a camera. This API uses an asynchrono | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | ---------------------------------- | -| camera | [CameraDevice](#cameraDevice) | Yes | **CameraDevice** object. | +| camera | [CameraDevice](#cameradevice) | Yes | **CameraDevice** object. | | callback | AsyncCallback<[CameraOutputCapability](#cameraoutputcapability)\> | Yes | Callback used to return the output capability.| **Example** @@ -196,7 +196,7 @@ Obtains the output capability supported by a camera. This API uses an asynchrono ```js cameraManager.getSupportedOutputCapability(cameraDevice, (err, cameras) => { if (err) { - console.error('Failed to get the cameras. ${err.message}'); + console.error(`Failed to get the cameras. ${err.message}`); return; } console.log('Callback returned with an array of supported outputCapability'); @@ -215,7 +215,7 @@ Obtains the output capability supported by a camera. This API uses a promise to | Name | Type | Mandatory| Description | | ------ | ----------------------------- | ---- | ------------------ | -| camera | [CameraDevice](#cameraDevice) | Yes | **CameraDevice** object.| +| camera | [CameraDevice](#cameradevice) | Yes | **CameraDevice** object.| **Return value** @@ -251,7 +251,7 @@ Obtains the metadata information supported by this camera. This API uses an asyn ```js cameraManager.getSupportedMetadataObjectType((err, metadataobject) => { if (err) { - console.error('Failed to get the supported metadataObjectType. ${err.message}'); + console.error(`Failed to get the supported metadataObjectType. ${err.message}`); return; } console.log('Callback returned with an array of supported metadataObjectType.' ); @@ -300,7 +300,7 @@ Checks whether this camera is muted. This API uses an asynchronous callback to r ```js cameraManager.isCameraMuted((err, status) => { if (err) { - console.error('Failed to get the cameraMuted status. ${err.message}'); + console.error(`Failed to get the cameraMuted status. ${err.message}`); return; } console.log('Callback returned with cameraMuted status'); @@ -353,7 +353,7 @@ This is a system API. ```js cameraManager.isCameraMuteSupported((err, status) => { if (err) { - console.error('Failed to get the cameraMuteSupported. ${err.message}'); + console.error(`Failed to get the cameraMuteSupported. ${err.message}`); return; } console.log('Callback returned with the status whether cameraMuteSupported.'); @@ -411,7 +411,7 @@ This is a system API. ```js cameraManager.muteCamera(isMuted, (err) => { if (err) { - console.error('Failed to mute the camera. ${err.message}'); + console.error(`Failed to mute the camera. ${err.message}`); return; } console.log('Callback returned with the muteCamera.'); @@ -467,7 +467,7 @@ This is a system API. | Name | Type | Mandatory| Description | | -------- | ------------------------------------------- | ---- | ----------------------------------- | -| camera | [CameraDevice](#cameraDevice) | Yes | **CameraDevice** object. | +| camera | [CameraDevice](#cameradevice) | Yes | **CameraDevice** object. | | callback | AsyncCallback<[CameraInput](#camerainput)\> | Yes | Callback used to return the **CameraInput** instance.| **Example** @@ -475,7 +475,7 @@ This is a system API. ```js cameraManager.createCameraInput(camera, (err, cameraInput) => { if (err) { - console.error('Failed to create the CameraInput instance. ${err.message}'); + console.error(`Failed to create the CameraInput instance. ${err.message}`); return; } console.log('Callback returned with the CameraInput instance.'); @@ -498,7 +498,7 @@ This is a system API. | Name | Type | Mandatory| Description | | ------ | ----------------------------- | ---- | ------------------ | -| camera | [CameraDevice](#cameraDevice) | Yes | **CameraDevice** object.| +| camera | [CameraDevice](#cameradevice) | Yes | **CameraDevice** object.| **Return value** @@ -539,7 +539,7 @@ This is a system API. ```js cameraManager.createCameraInput(camera.CameraPosition.CAMERA_POSITION_BACK, camera.CameraType.CAMERA_TYPE_UNSPECIFIED, (err, cameraInput) => { if (err) { - console.error('Failed to create the CameraInput instance. ${err.message}'); + console.error(`Failed to create the CameraInput instance. ${err.message}`); return; } console.log('Callback returned with the CameraInput instance'); @@ -600,7 +600,7 @@ Creates a **PreviewOutput** instance. This API uses an asynchronous callback to ```js cameraManager.createPreviewOutput(profile, surfaceId, (err, previewoutput) => { if (err) { - console.error('Failed to gcreate previewOutput. ${err.message}'); + console.error(`Failed to gcreate previewOutput. ${err.message}`); return; } console.log('Callback returned with previewOutput created.'); @@ -656,7 +656,7 @@ Creates a **PreviewOutput** instance without a surface ID. This API uses an asyn ```js cameraManager.createDeferredPreviewOutput(profile, (err, previewoutput) => { if (err) { - console.error('Failed to create deferredPreviewOutput. ${err.message}'); + console.error(`Failed to create deferredPreviewOutput. ${err.message}`); return; } console.log('Callback returned with deferredPreviewOutput created.'); @@ -712,7 +712,7 @@ Creates a **PhotoOutput** instance. This API uses an asynchronous callback to re ```js cameraManager.createPhotoOutput(profile, surfaceId, (err, photooutput) => { if (err) { - console.error('Failed to create photoOutput. ${err.message}'); + console.error(`Failed to create photoOutput. ${err.message}`); return; } console.log('Callback returned with photoOutput created.'); @@ -769,7 +769,7 @@ Creates a **VideoOutput** instance. This API uses an asynchronous callback to re ```js cameraManager.createVideoOutput(profile, surfaceId, (err, videooutput) => { if (err) { - console.error('Failed to create videoOutput. ${err.message}'); + console.error(`Failed to create videoOutput. ${err.message}`); return; } console.log('Callback returned with an array of supported outputCapability' ); @@ -825,7 +825,7 @@ Creates a **MetadataOutput** instance. This API uses an asynchronous callback to ```js cameraManager.createMetadataOutput(metadataObjectTypes, (err, metadataoutput) => { if (err) { - console.error('Failed to create metadataOutput. ${err.message}'); + console.error(`Failed to create metadataOutput. ${err.message}`); return; } console.log('Callback returned with metadataOutput created.'); @@ -879,7 +879,7 @@ Creates a **CaptureSession** instance. This API uses an asynchronous callback to ```js cameraManager.createCaptureSession((err, capturesession) => { if (err) { - console.error('Failed to create captureSession. ${err.message}'); + console.error(`Failed to create captureSession. ${err.message}`); return; } console.log('Callback returned with captureSession created.'); @@ -928,11 +928,11 @@ Listens for camera status changes. This API uses an asynchronous callback to ret ```js cameraManager.on('cameraStatus', (err, cameraStatusInfo) => { if (err) { - console.error('Failed to get cameraStatus callback. ${err.message}'); + console.error(`Failed to get cameraStatus callback. ${err.message}`); return; } - console.log('camera : ' + cameraStatusInfo.camera.cameraId); - console.log('status: ' + cameraStatusInfo.status); + console.log(`camera : ${cameraStatusInfo.camera.cameraId}`); + console.log(`status: ${cameraStatusInfo.status}`); }) ``` @@ -960,10 +960,10 @@ This is a system API. ```js cameraManager.on('cameraMute', (err, status) => { if (err) { - console.error('Failed to get cameraMute callback. ${err.message}'); + console.error(`Failed to get cameraMute callback. ${err.message}`); return; } - console.log('status: ' + status); + console.log(`status: ${status}`); }) ``` @@ -975,7 +975,7 @@ Describes the camera status information. | Name | Type | Description | | ------ | ----------------------------- | ---------- | -| camera | [CameraDevice](#cameraDevice) | Camera object.| +| camera | [CameraDevice](#cameradevice) | Camera object.| | status | [CameraStatus](#camerastatus) | Camera status.| ## CameraPosition @@ -1033,13 +1033,13 @@ Defines the camera device information. ```js async function getCameraInfo("cameraId") { - var cameraManager = await camera.getCameraManager(context); - var cameras = await cameraManager.getSupportedCameras(); - var cameraObj = cameras[0]; - var cameraId = cameraObj.cameraId; - var cameraPosition = cameraObj.cameraPosition; - var cameraType = cameraObj.cameraType; - var connectionType = cameraObj.connectionType; + let cameraManager = await camera.getCameraManager(context); + let cameras = await cameraManager.getSupportedCameras(); + let cameraObj = cameras[0]; + let cameraId = cameraObj.cameraId; + let cameraPosition = cameraObj.cameraPosition; + let cameraType = cameraObj.cameraType; + let connectionType = cameraObj.connectionType; } ``` @@ -1099,7 +1099,7 @@ Opens this camera. This API uses an asynchronous callback to return the result. ```js cameraInput.open((err) => { if (err) { - console.error('Failed to open the camera. ${err.message}'); + console.error(`Failed to open the camera. ${err.message}`); return; } console.log('Callback returned with camera opened.'); @@ -1147,7 +1147,7 @@ Closes this camera. This API uses an asynchronous callback to return the result. ```js cameraInput.close((err) => { if (err) { - console.error('Failed to close the cameras. ${err.message}'); + console.error(`Failed to close the cameras. ${err.message}`); return; } console.log('Callback returned with camera closed.'); @@ -1195,7 +1195,7 @@ Releases this camera. This API uses an asynchronous callback to return the resul ```js cameraInput.release((err) => { if (err) { - console.error('Failed to release the CameraInput instance ${err.message}'); + console.error(`Failed to release the CameraInput instance ${err.message}`); return; } console.log('Callback invoked to indicate that the CameraInput instance is released successfully.'); @@ -1243,7 +1243,7 @@ Listens for **CameraInput** errors. This API uses a callback to return the resul ```js cameraInput.on('error', (cameraInputError) => { - console.log('Camera input error code: ' + cameraInputError.code); + console.log(`Camera input error code: ${cameraInputError.code}`); }) ``` @@ -1371,7 +1371,7 @@ Starts configuration for this **CaptureSession** instance. This API uses an asyn ```js captureSession.beginConfig((err) => { if (err) { - console.error('Failed to start the configuration. ${err.message}'); + console.error(`Failed to start the configuration. ${err.message}`); return; } console.log('Callback invoked to indicate the begin config success.'); @@ -1420,7 +1420,7 @@ Commits the configuration for this **CaptureSession** instance. This API uses an ```js captureSession.commitConfig((err) => { if (err) { - console.error('Failed to commit the configuration. ${err.message}'); + console.error(`Failed to commit the configuration. ${err.message}`); return; } console.log('Callback invoked to indicate the commit config success.'); @@ -1469,7 +1469,7 @@ Checks whether a **[CameraInput](#camerainput)** instance can be added to this * ```js captureSession.canAddInput(cameraInput, (err, status) => { if (err) { - console.error('Can not add cameraInput. ${err.message}'); + console.error(`Can not add cameraInput. ${err.message}`); return; } console.log('Callback returned with cameraInput can added.'); @@ -1524,7 +1524,7 @@ Adds a **[CameraInput](#camerainput)** instance to this **CaptureSession**. This ```js captureSession.addInput(cameraInput, (err) => { if (err) { - console.error('Failed to add the CameraInput instance. ${err.message}'); + console.error(`Failed to add the CameraInput instance. ${err.message}`); return; } console.log('Callback invoked to indicate that the CameraInput instance is added.'); @@ -1579,7 +1579,7 @@ Removes a **[CameraInput](#camerainput)** instance from this **CaptureSession**. ```js captureSession.removeInput(cameraInput, (err) => { if (err) { - console.error('Failed to remove the CameraInput instance. ${err.message}'); + console.error(`Failed to remove the CameraInput instance. ${err.message}`); return; } console.log('Callback invoked to indicate that the cameraInput instance is removed.'); @@ -1626,7 +1626,7 @@ Checks whether a **[CameraOutput](#cameraoutput)** instance can be added to this | Name | Type | Mandatory| Description | | ------------ | ----------------------------- | ---- | ---------------------------- | -| cameraOutput | [CameraOutput](#cameraOutput) | Yes | **CameraOutput** instance to add.| +| cameraOutput | [CameraOutput](#cameraoutput) | Yes | **CameraOutput** instance to add.| | callback | AsyncCallback | Yes | Callback used to return the result. | **Example** @@ -1634,7 +1634,7 @@ Checks whether a **[CameraOutput](#cameraoutput)** instance can be added to this ```js captureSession.canAddOutput(cameraOutput, (err, status) => { if (err) { - console.error('Can not add cameraOutput. ${err.message}'); + console.error(`Can not add cameraOutput. ${err.message}`); return; } console.log('Callback returned with cameraOutput can added.'); @@ -1653,7 +1653,7 @@ Checks whether a **[CameraOutput](#cameraoutput)** instance can be added to this | Name | Type | Mandatory| Description | | ------------ | ----------------------------- | ---- | ---------------------------- | -| cameraOutput | [CameraOutput](#cameraOutput) | Yes | **CameraOutput** instance to add.| +| cameraOutput | [CameraOutput](#cameraoutput) | Yes | **CameraOutput** instance to add.| **Return value** @@ -1683,7 +1683,7 @@ Adds a **[CameraOutput](#cameraoutput)** instance to this **CaptureSession**. Th | Name | Type | Mandatory| Description | | ------------ | ----------------------------- | ---- | ---------------------------- | -| cameraOutput | [CameraOutput](#cameraOutput) | Yes | **CameraOutput** instance to add.| +| cameraOutput | [CameraOutput](#cameraoutput) | Yes | **CameraOutput** instance to add.| | callback | AsyncCallback | Yes | Callback used to return the result. | **Example** @@ -1691,7 +1691,7 @@ Adds a **[CameraOutput](#cameraoutput)** instance to this **CaptureSession**. Th ```js captureSession.addOutput(cameraOutput, (err) => { if (err) { - console.error('Failed to add output. ${err.message}'); + console.error(`Failed to add output. ${err.message}`); return; } console.log('Callback returned with output added.'); @@ -1710,7 +1710,7 @@ Adds a **[CameraOutput](#cameraoutput)** instance to this **CaptureSession**. Th | Name | Type | Mandatory| Description | | ------------ | ----------------------------- | ---- | ---------------------------- | -| cameraOutput | [CameraOutput](#cameraOutput) | Yes | **CameraOutput** instance to add.| +| cameraOutput | [CameraOutput](#cameraoutput) | Yes | **CameraOutput** instance to add.| **Return value** @@ -1738,7 +1738,7 @@ Removes a **[CameraOutput](#cameraoutput)** instance from this **CaptureSession* | Name | Type | Mandatory| Description | | ------------ | ----------------------------- | ---- | ---------------------------- | -| cameraOutput | [CameraOutput](#cameraOutput) | Yes | **CameraOutput** instance to remove.| +| cameraOutput | [CameraOutput](#cameraoutput) | Yes | **CameraOutput** instance to remove.| | callback | AsyncCallback | Yes | Callback used to return the result. | **Example** @@ -1746,7 +1746,7 @@ Removes a **[CameraOutput](#cameraoutput)** instance from this **CaptureSession* ```js captureSession.removeOutput(cameraOutput, (err) => { if (err) { - console.error('Failed to remove the CameraOutput instance. ${err.message}'); + console.error(`Failed to remove the CameraOutput instance. ${err.message}`); return; } console.log('Callback invoked to indicate that the CameraOutput instance is removed.'); @@ -1765,7 +1765,7 @@ Removes a **[CameraOutput](#cameraoutput)** instance from this **CaptureSession* | Name | Type | Mandatory| Description | | ------------ | ----------------------------- | ---- | ---------------------------- | -| cameraOutput | [CameraOutput](#cameraOutput) | Yes | **CameraOutput** instance to remove.| +| cameraOutput | [CameraOutput](#cameraoutput) | Yes | **CameraOutput** instance to remove.| **Return value** @@ -1802,7 +1802,7 @@ Starts this **CaptureSession**. This API uses an asynchronous callback to return ```js captureSession.start((err) => { if (err) { - console.error('Failed to start the session ${err.message}'); + console.error(`Failed to start the session ${err.message}`); return; } console.log('Callback invoked to indicate the session start success.'); @@ -1850,7 +1850,7 @@ Stops this **CaptureSession**. This API uses an asynchronous callback to return ```js captureSession.stop((err) => { if (err) { - console.error('Failed to stop the session ${err.message}'); + console.error(`Failed to stop the session ${err.message}`); return; } console.log('Callback invoked to indicate the session stop success.'); @@ -1898,7 +1898,7 @@ Requests to exclusively control the hardware attributes **[CameraInput](#camerai ```js captureSession.lockForControl((err) => { if (err) { - console.error('Failed to lock. ${err.message}'); + console.error(`Failed to lock. ${err.message}`); return; } console.log('Locked.'); @@ -1946,7 +1946,7 @@ Releases the exclusive control on the device configuration. This API uses an asy ```js captureSession.unlockForControl((err) => { if (err) { - console.error('Failed to unlock. ${err.message}'); + console.error(`Failed to unlock. ${err.message}`); return; } console.log('Unlocked.'); @@ -1994,7 +1994,7 @@ Releases this **CaptureSession**. This API uses an asynchronous callback to retu ```js captureSession.release((err) => { if (err) { - console.error('Failed to release the CaptureSession instance ${err.message}'); + console.error(`Failed to release the CaptureSession instance ${err.message}`); return; } console.log('Callback invoked to indicate that the CaptureSession instance is released successfully.'); @@ -2042,10 +2042,10 @@ Checks whether the device has flash light. This API uses an asynchronous callbac ```js cameraInput.hasFlash((err, status) => { if (err) { - console.error('Failed to check whether the device has flash light. ${err.message}'); + console.error(`Failed to check whether the device has flash light. ${err.message}`); return; } - console.log('Callback returned with flash light support status: ' + status); + console.log(`Callback returned with flash light support status: ${status}`); }) ``` @@ -2067,7 +2067,7 @@ Checks whether the device has flash light. This API uses a promise to return the ```js cameraInput.hasFlash().then((status) => { - console.log('Promise returned with the flash light support status:' + status); + console.log(`Promise returned with the flash light support status: ${status}`); }) ``` @@ -2091,10 +2091,10 @@ Checks whether a specified flash mode is supported. This API uses an asynchronou ```js cameraInput.isFlashModeSupported(camera.FlashMode.FLASH_MODE_AUTO, (err, status) => { if (err) { - console.error('Failed to check whether the flash mode is supported. ${err.message}'); + console.error(`Failed to check whether the flash mode is supported. ${err.message}`); return; } - console.log('Callback returned with the flash mode support status: ' + status); + console.log(`Callback returned with the flash mode support status: ${status}`); }) ``` @@ -2122,7 +2122,7 @@ Checks whether a specified flash mode is supported. This API uses a promise to r ```js cameraInput.isFlashModeSupported(camera.FlashMode.FLASH_MODE_AUTO).then((status) => { - console.log('Promise returned with flash mode support status.' + status); + console.log(`Promise returned with flash mode support status.${status}`); }) ``` @@ -2151,7 +2151,7 @@ Before the setting, do the following checks: ```js cameraInput.setFlashMode(camera.FlashMode.FLASH_MODE_AUTO, (err) => { if (err) { - console.error('Failed to set the flash mode ${err.message}'); + console.error(`Failed to set the flash mode ${err.message}`); return; } console.log('Callback returned with the successful execution of setFlashMode.'); @@ -2210,10 +2210,10 @@ Obtains the flash mode in use. This API uses an asynchronous callback to return ```js cameraInput.getFlashMode((err, flashMode) => { if (err) { - console.error('Failed to get the flash mode ${err.message}'); + console.error(`Failed to get the flash mode ${err.message}`); return; } - console.log('Callback returned with current flash mode: ' + flashMode); + console.log(`Callback returned with current flash mode: ${flashMode}`); }) ``` @@ -2235,7 +2235,7 @@ Obtains the flash mode in use. This API uses a promise to return the result. ```js cameraInput.getFlashMode().then((flashMode) => { - console.log('Promise returned with current flash mode : ' + flashMode); + console.log(`Promise returned with current flash mode : ${flashMode}`); }) ``` @@ -2259,7 +2259,7 @@ Checks whether a specified exposure mode is supported. This API uses an asynchro ```js cameraInput.isExposureModeSupported(camera.ExposureMode.EXPOSURE_MODE_LOCKEN,(err) => { if (err) { - console.log('Failed to check exposure mode supported ${err.message}'); + console.log(`Failed to check exposure mode supported ${err.message}`); return ; } console.log('Callback returned with the successful excution of isExposureModeSupported'); @@ -2290,7 +2290,7 @@ Checks whether a specified exposure mode is supported. This API uses a promise t ```js cameraInput.isExposureModeSupported(camera.ExposureMode.EXPOSURE_MODE_LOCKED).then((isSupported) => { - console.log('Promise returned with exposure mode supported : ' + isSupported); + console.log(`Promise returned with exposure mode supported : ${isSupported}`); }) ``` @@ -2313,10 +2313,10 @@ Obtains the exposure mode in use. This API uses an asynchronous callback to retu ```js cameraInput.getExposureMode((err, exposureMode) => { if (err) { - console.log('Failed to get the exposure mode ${err.message}'); + console.log(`Failed to get the exposure mode ${err.message}`); return ; } - console.log('Callback returned with current exposure mode:' + exposureMode); + console.log(`Callback returned with current exposure mode: ${exposureMode}`); }) ``` @@ -2338,7 +2338,7 @@ Obtains the exposure mode in use. This API uses a promise to return the result. ```js cameraInput.getExposureMode().then((exposureMode) => { - console.log('Promise returned with current exposure mode : ' + exposureMode); + console.log(`Promise returned with current exposure mode : ${exposureMode}`); }) ``` @@ -2362,7 +2362,7 @@ Sets an exposure mode. This API uses an asynchronous callback to return the resu ```js cameraInput.setExposureMode(camera.ExposureMode.EXPOSURE_MODE_LOCKEN,(err) => { if (err) { - console.log('Failed to set the exposure mode ${err.message}'); + console.log(`Failed to set the exposure mode ${err.message}`); return ; } console.log('Callback returned with the successful excution of setExposureMode'); @@ -2410,10 +2410,10 @@ Obtains the center of the metering area. This API uses an asynchronous callback ```js cameraInput.getMeteringPoint((err, exposurePoint) => { if (err) { - console.log('Failed to get the current exposure point ${err.message}'); + console.log(`Failed to get the current exposure point ${err.message}`); return ; } - console.log('Callback returned with current exposure point:' + exposurePoint); + console.log(`Callback returned with current exposure point: ${exposurePoint}`); }) ``` @@ -2435,7 +2435,7 @@ Obtains the center of the metering area. This API uses a promise to return the r ```js cameraInput.getMeteringPoint().then((exposurePoint) => { - console.log('Promise returned with current exposure point : ' + exposurePoint); + console.log(`Promise returned with current exposure point : ${exposurePoint}`); }) ``` @@ -2457,11 +2457,11 @@ Sets the center of the metering area. This API uses an asynchronous callback to **Example** ```js -var Point1 = {x: 1, y: 1}; +const Point1 = {x: 1, y: 1}; cameraInput.setMeteringPoint(Point1,(err) => { if (err) { - console.log('Failed to set the exposure point ${err.message}'); + console.log(`Failed to set the exposure point ${err.message}`); return ; } console.log('Callback returned with the successful excution of setMeteringPoint'); @@ -2491,7 +2491,7 @@ Sets the center of the metering area. This API uses a promise to return the resu **Example** ```js -var Point2 = {x: 2, y: 2}; +const Point2 = {x: 2, y: 2}; cameraInput.setMeteringPoint(Point2).then(() => { console.log('Promise returned with the successful execution of setMeteringPoint'); @@ -2517,7 +2517,7 @@ Obtains the exposure compensation values. This API uses an asynchronous callback ```js cameraInput.getExposureBiasRange((err, biasRangeArray) => { if (err) { - console.log('Failed to get the array of compenstation range ${err.message}'); + console.log(`Failed to get the array of compenstation range ${err.message}`); return ; } console.log('Callback returned with the array of compenstation range: ' + JSON.stringify(biasRangeArray)); @@ -2542,7 +2542,7 @@ Obtains the exposure compensation values. This API uses a promise to return the ```js cameraInput.isExposureModeSupported(camera.ExposureMode.EXPOSURE_MODE_LOCKED).then((isSupported) => { - console.log('Promise returned with exposure mode supported : ' + isSupported); + console.log(`Promise returned with exposure mode supported : ${isSupported}`); }) ``` @@ -2568,7 +2568,7 @@ Before the setting, you are advised to use **[getExposureBiasRange](#getexposure ```js cameraInput.setExposureBias(-4,(err) => { if (err) { - console.log('Failed to set the exposure bias ${err.message}'); + console.log(`Failed to set the exposure bias ${err.message}`); return ; } console.log('Callback returned with the successful excution of setExposureBias'); @@ -2624,10 +2624,10 @@ Obtains the exposure value in use. This API uses an asynchronous callback to ret ```js cameraInput.getExposureValue((err, exposureValue) => { if (err) { - console.log('Failed to get the exposure value ${err.message}'); + console.log(`Failed to get the exposure value ${err.message}`); return ; } - console.log('Callback returned with the exposure value: ' + exposureValue); + console.log(`Callback returned with the exposure value: ${exposureValue}`); }) ``` @@ -2649,7 +2649,7 @@ Obtains the exposure value in use. This API uses a promise to return the result. ```js cameraInput.getExposureValue().then((exposureValue) => { - console.log('Promise returned with exposure value: ' + exposureValue); + console.log(`Promise returned with exposure value: ${exposureValude}`); }) ``` @@ -2673,10 +2673,10 @@ Checks whether a specified focus mode is supported. This API uses an asynchronou ```js cameraInput.isFocusModeSupported(camera.FocusMode.FOCUS_MODE_AUTO, (err, status) => { if (err) { - console.error('Failed to check whether the focus mode is supported. ${err.message}'); + console.error(`Failed to check whether the focus mode is supported. ${err.message}`); return; } - console.log('Callback returned with the focus mode support status: ' + status); + console.log(`Callback returned with the focus mode support status: ${status}`); }) ``` @@ -2704,7 +2704,7 @@ Checks whether a specified focus mode is supported. This API uses a promise to r ```js cameraInput.isFocusModeSupported(camera.FocusMode.FOCUS_MODE_AUTO).then((status) => { - console.log('Promise returned with focus mode support status.' + status); + console.log(`Promise returned with focus mode support status ${status}.`); }) ``` @@ -2730,7 +2730,7 @@ Before the setting, use **[isFocusModeSupported](#isfocusmodesupported)** to che ```js cameraInput.setFocusMode(camera.FocusMode.FOCUS_MODE_AUTO, (err) => { if (err) { - console.error('Failed to set the focus mode ${err.message}'); + console.error(`Failed to set the focus mode ${err.message}`); return; } console.log('Callback returned with the successful execution of setFocusMode.'); @@ -2786,10 +2786,10 @@ Obtains the focus mode in use. This API uses an asynchronous callback to return ```js cameraInput.getFocusMode((err, afMode) => { if (err) { - console.error('Failed to get the focus mode ${err.message}'); + console.error(`Failed to get the focus mode ${err.message}`); return; } - console.log('Callback returned with current focus mode: ' + afMode); + console.log(`Callback returned with current focus mode: ${afMode}`); }) ``` @@ -2811,7 +2811,7 @@ Obtains the focus mode in use. This API uses a promise to return the result. ```js cameraInput.getFocusMode().then((afMode) => { - console.log('Promise returned with current focus mode : ' + afMode); + console.log(`Promise returned with current focus mode : ${afMode}`); }) ``` @@ -2827,17 +2827,17 @@ Sets a focus point. This API uses an asynchronous callback to return the result. | Name | Type | Mandatory| Description | | -------- | -------------------- | ---- | ------------------------ | -| point | [Point](#Point) | Yes | Focus point. | +| point | [Point](#point) | Yes | Focus point. | | callback | AsyncCallback | Yes | Callback used to return the result.| **Example** ```js -var Point1 = {x: 1, y: 1}; +const Point1 = {x: 1, y: 1}; cameraInput.setFocusPoint(Point1, (err) => { if (err) { - console.error('Failed to set the focus point ${err.message}'); + console.error(`Failed to set the focus point ${err.message}`); return; } console.log('Callback returned with the successful execution of setFocusPoint.'); @@ -2856,7 +2856,7 @@ Sets a focus point. This API uses a promise to return the result. | Name | Type | Mandatory| Description | | ----- | --------------- | ---- | ------ | -| point | [Point](#Point) | Yes | Focus point.| +| point | [Point](#point) | Yes | Focus point.| **Return value** @@ -2867,7 +2867,7 @@ Sets a focus point. This API uses a promise to return the result. **Example** ```js -var Point2 = {x: 2, y: 2}; +const Point2 = {x: 2, y: 2}; cameraInput.setFocusPoint(Point2).then(() => { console.log('Promise returned with the successful execution of setFocusPoint.'); @@ -2893,7 +2893,7 @@ Obtains the focus point. This API uses an asynchronous callback to return the re ```js cameraInput.getFocusPoint((err, point) => { if (err) { - console.error('Failed to get the current focus point ${err.message}'); + console.error(`Failed to get the current focus point ${err.message}`); return; } console.log('Callback returned with the current focus point: ' + JSON.stringify(point)); @@ -2941,10 +2941,10 @@ Obtains the focal length. This API uses an asynchronous callback to return the r ```js cameraInput.getFocalLength((err, focalLength) => { if (err) { - console.error('Failed to get the current focal length ${err.message}'); + console.error(`Failed to get the current focal length ${err.message}`); return; } - console.log('Callback returned with the current focal length: ' + focalLength); + console.log(`Callback returned with the current focal length: ${focalLength}`); }) ``` @@ -2966,7 +2966,7 @@ Obtains the focal length. This API uses a promise to return the result. ```js cameraInput.getFocalLength().then((focalLength) => { - console.log('Promise returned with the current focal length: ' + focalLength); + console.log(`Promise returned with the current focal length: ${focalLength}`); }) ``` @@ -2989,10 +2989,10 @@ Obtains the zoom range. This API uses an asynchronous callback to return the res ```js cameraInput.getZoomRatioRange((err, zoomRatioRange) => { if (err) { - console.error('Failed to get the zoom ratio range. ${err.message}'); + console.error(`Failed to get the zoom ratio range. ${err.message}`); return; } - console.log('Callback returned with zoom ratio range: ' + zoomRatioRange.length); + console.log(`Callback returned with zoom ratio range: ${zoomRatioRange.length}`); }) ``` @@ -3014,7 +3014,7 @@ Obtains the zoom range. This API uses a promise to return the result. ```js cameraInput.getZoomRatioRange().then((zoomRatioRange) => { - console.log('Promise returned with zoom ratio range: ' + zoomRatioRange.length); + console.log(`Promise returned with zoom ratio range: ${zoomRatioRange.length}`); }) ``` @@ -3038,7 +3038,7 @@ Sets a zoom ratio. This API uses an asynchronous callback to return the result. ```js cameraInput.setZoomRatio(1, (err) => { if (err) { - console.error('Failed to set the zoom ratio value ${err.message}'); + console.error(`Failed to set the zoom ratio value ${err.message}`); return; } console.log('Callback returned with the successful execution of setZoomRatio.'); @@ -3092,10 +3092,10 @@ Obtains the zoom ratio in use. This API uses an asynchronous callback to return ```js cameraInput.getZoomRatio((err, zoomRatio) => { if (err) { - console.error('Failed to get the zoom ratio ${err.message}'); + console.error(`Failed to get the zoom ratio ${err.message}`); return; } - console.log('Callback returned with current zoom ratio: ' + zoomRatio); + console.log(`Callback returned with current zoom ratio: ${zoomRatio}`); }) ``` @@ -3117,7 +3117,7 @@ Obtains the zoom ratio in use. This API uses a promise to return the result. ```js cameraInput.getZoomRatio().then((zoomRatio) => { - console.log('Promise returned with current zoom ratio : ' + zoomRatio); + console.log(`Promise returned with current zoom ratio : ${zoomRatio}`); }) ``` @@ -3133,7 +3133,7 @@ Checks whether a specified video stabilization mode is supported. This API uses | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------- | ---- | ------------------------------------ | -| vsMode | [VideoStabilizationMode](#videostabilizationMode) | Yes | Video stabilization mode. | +| vsMode | [VideoStabilizationMode](#videostabilizationmode) | Yes | Video stabilization mode. | | callback | AsyncCallback | Yes | Callback used to return whether the video stabilization mode is supported. The value **true** means that the video stabilization mode is supported, and **false** means the opposite.| **Example** @@ -3141,10 +3141,10 @@ Checks whether a specified video stabilization mode is supported. This API uses ```js captureSession.isVideoStablizationModeSupported(camera.VideoStabilizationMode.OFF, (err, isSupported) => { if (err) { - console.error('Failed to check whether video stabilization mode supported. ${err.message}'); + console.error(`Failed to check whether video stabilization mode supported. ${err.message}`); return; } - console.log('Callback returned with the successful execution of isVideoStabilizationModeSupported: ' + status); + console.log(`Callback returned with the successful execution of isVideoStabilizationModeSupported: ${status}`); }) ``` @@ -3166,7 +3166,7 @@ Checks whether a specified video stabilization mode is supported. This API uses ```js captureSession.isVideoStablizationModeSupported(camera.VideoStabilizationMode.OFF).then((isSupported) => { - console.log('Promise returned with video stabilization mode supported: ' + isSupported); + console.log(`Promise returned with video stabilization mode supported: ${isSupported}`); }) ``` @@ -3189,7 +3189,7 @@ Obtains the video stabilization mode in use. This API uses an asynchronous callb ```js captureSession.getActiveVideoStabilizationMode((err, vsMode) => { if (err) { - console.error('Failed to get active video stabilization mode ${err.message}'); + console.error(`Failed to get active video stabilization mode ${err.message}`); return; } console.log('Callback returned with the successful execution of getActiveVideoStabilizationMode.'); @@ -3214,7 +3214,7 @@ Obtains the video stabilization mode in use. This API uses a promise to return t ```js captureSession.getActiveVideoStabilizationMode().then((vsMode) => { - console.log('Promise returned with the current video stabilization mode: ' + vsMode); + console.log(`Promise returned with the current video stabilization mode: ${vsMode}`); }) ``` @@ -3238,7 +3238,7 @@ Sets a video stabilization mode. This API uses an asynchronous callback to retur ```js captureSession.setVideoStabilizationMode(camera.VideoStabilizationMode.OFF, (err) => { if (err) { - console.error('Failed to set the video stabilization mode ${err.message}'); + console.error(`Failed to set the video stabilization mode ${err.message}`); return; } console.log('Callback returned with the successful execution of setVideoStabilizationMode.'); @@ -3292,7 +3292,7 @@ Listens for focus state changes. This API uses an asynchronous callback to retur ```js cameraInput.on('focusStateChange', (focusState) => { - console.log('Focus state : ' + focusState); + console.log(`Focus state : ${focusState}`); }) ``` @@ -3309,13 +3309,13 @@ Listens for exposure state changes. This API uses an asynchronous callback to re | Name | Type | Mandatory| Description | | -------- | ----------------------------------------------- | ---- | ----------------------------------------------------------- | | type | string | Yes | Event type. The value is fixed at **'exposureStateChange'**, indicating the exposure state change event.| -| callback | AsyncCallback<[ExposureState](#exposureState)\> | Yes | Callback used to return the exposure state change. | +| callback | AsyncCallback<[ExposureState](#exposurestate)\> | Yes | Callback used to return the exposure state change. | **Example** ```js cameraInput.on('exposureStateChange', (exposureState) => { - console.log('Exposuer state : ' + exposureState); + console.log(`Exposuer state : ${exposureState}`); }) ``` @@ -3338,7 +3338,7 @@ Listens for **CaptureSession** errors. This API uses a callback to return the er ```js captureSession.on('error', (captureSessionError) => { - console.log('Capture session error code: ' + captureSessionError.code); + console.log(`Capture session error code: ${captureSessionError.code}`); }) ``` @@ -3387,7 +3387,7 @@ Releases output resources. This API uses an asynchronous callback to return the ```js previewOutput.release((err) => { if (err) { - console.error('Failed to release the PreviewOutput instance ${err.message}'); + console.error(`Failed to release the PreviewOutput instance ${err.message}`); return; } console.log('Callback invoked to indicate that the PreviewOutput instance is released successfully.'); @@ -3440,7 +3440,7 @@ Adds a surface after a **PreviewOutput** instance is created. This API uses an a ```js previewOutput.addDeferredSurface('surfaceId', (err) => { if (err) { - console.error('Failed to add deferredSurface. ${err.message}'); + console.error(`Failed to add deferredSurface. ${err.message}`); return; } console.log('Callback returned with deferredSurface added.'); @@ -3494,7 +3494,7 @@ Starts to output preview streams. This API uses an asynchronous callback to retu ```js previewOutput.start((err) => { if (err) { - console.error('Failed to start the previewOutput. ${err.message}'); + console.error(`Failed to start the previewOutput. ${err.message}`); return; } console.log('Callback returned with previewOutput started.'); @@ -3542,7 +3542,7 @@ Stops outputting preview streams. This API uses an asynchronous callback to retu ```js previewOutput.stop((err) => { if (err) { - console.error('Failed to stop the previewOutput. ${err.message}'); + console.error(`Failed to stop the previewOutput. ${err.message}`); return; } console.log('Callback returned with previewOutput stoped.'); @@ -3636,7 +3636,7 @@ Listens for **PreviewOutput** errors. This API uses a callback to return the err ```js previewOutput.on('error', (previewOutputError) => { - console.log('Preview output error code: ' + previewOutputError.code); + console.log(`Preview output error code: ${previewOutputError.code}`); }) ``` @@ -3734,7 +3734,7 @@ Obtains the default shooting parameters. This API uses an asynchronous callback ```js photoOutput.getDefaultCaptureSetting((err, photocapturesetting) => { if (err) { - console.error('Failed to get the defaultCaptureSetting. ${err.message}'); + console.error(`Failed to get the defaultCaptureSetting. ${err.message}`); return; } console.log('Callback returned with an array of defaultCaptureSetting.'); @@ -3782,7 +3782,7 @@ Captures a photo with the default shooting parameters. This API uses an asynchro ```js photoOutput.capture((err) => { if (err) { - console.error('Failed to capture the photo ${err.message}'); + console.error(`Failed to capture the photo ${err.message}`); return; } console.log('Callback invoked to indicate the photo capture request success.'); @@ -3813,7 +3813,7 @@ let settings:PhotoCaptureSetting = { } photoOutput.capture(settings, (err) => { if (err) { - console.error('Failed to capture the photo ${err.message}'); + console.error(`Failed to capture the photo ${err.message}`); return; } console.log('Callback invoked to indicate the photo capture request success.'); @@ -3868,7 +3868,7 @@ Checks whether mirroring is supported. This API uses an asynchronous callback to ```js captureSession.isMirrorSupported((err, isSupported) => { if (err) { - console.error('Failed to check mirror is supported ${err.message}'); + console.error(`Failed to check mirror is supported ${err.message}`); return; } console.log('Callback returned with the successful execution of isMirrorSupported.'); @@ -3893,7 +3893,7 @@ Checks whether mirroring is supported. This API uses a promise to return the res ```js captureSession.isMirrorSupported().then((isSupported) => { - console.log('Promise returned with mirror supported: ' + isSupported); + console.log(`Promise returned with mirror supported: ${isSupported}`); }) ``` @@ -3916,7 +3916,7 @@ Listens for shooting start events. This API uses an asynchronous callback to ret ```js photoOutput.on('captureStart', (err, captureId) => { - console.log('photo capture stated, captureId : ' + captureId); + console.log(`photo capture stated, captureId : ${captureId}`); }) ``` @@ -3939,8 +3939,8 @@ Listens for frame shutter events. This API uses an asynchronous callback to retu ```js photoOutput.on('frameShutter', (err, frameShutterInfo) => { - console.log('photo capture end, captureId : ' + frameShutterInfo.captureId); - console.log('Timestamp for frame : ' + frameShutterInfo.timestamp); + console.log(`photo capture end, captureId : ${frameShutterInfo.captureId}`); + console.log(`Timestamp for frame : ${frameShutterInfo.timestamp}`); }) ``` @@ -3963,8 +3963,8 @@ Listens for shooting end events. This API uses an asynchronous callback to retur ```js photoOutput.on('captureEnd', (err, captureEndInfo) => { - console.log('photo capture end, captureId : ' + captureEndInfo.captureId); - console.log('frameCount : ' + captureEndInfo.frameCount); + console.log(`photo capture end, captureId : ${captureEndInfo.captureId}`); + console.log(`frameCount : ${captureEndInfo.frameCount}`); }) ``` @@ -3987,7 +3987,7 @@ Listens for **PhotoOutput** errors. This API uses a callback to return the error ```js photoOutput.on('error', (err, photoOutputError) => { - console.log('Photo output error code: ' + photoOutputError.code); + console.log(`Photo output error code: ${photoOutputError.code}`); }) ``` @@ -4059,7 +4059,7 @@ Starts video recording. This API uses an asynchronous callback to return the res ```js videoOutput.start((err) => { if (err) { - console.error('Failed to start the video output ${err.message}'); + console.error(`Failed to start the video output ${err.message}`); return; } console.log('Callback invoked to indicate the video output start success.'); @@ -4108,7 +4108,7 @@ Stops video recording. This API uses an asynchronous callback to return the resu ```js videoOutput.stop((err) => { if (err) { - console.error('Failed to stop the video output ${err.message}'); + console.error(`Failed to stop the video output ${err.message}`); return; } console.log('Callback invoked to indicate the video output stop success.'); @@ -4202,7 +4202,7 @@ Listens for errors that occur during video recording. This API uses a callback t ```js videoOutput.on('error', (VideoOutputError) => { - console.log('Video output error code: ' + VideoOutputError.code); + console.log(`Video output error code: ${VideoOutputError.code}`); }) ``` @@ -4266,14 +4266,14 @@ Obtains the metadata object type. This API uses an asynchronous callback to retu | Name | Type | Mandatory| Description | | -------- | --------------------------------------------------------- | ---- | ------------------------ | -| callback | AsyncCallback<[MetadataObjectType](#metadataObjectType)\> | Yes | Callback used to return the result.| +| callback | AsyncCallback<[MetadataObjectType](#metadataobjecttype)\> | Yes | Callback used to return the result.| **Example** ```js metadataObject.getType((err, metadataObjectType) => { if (err) { - console.error('Failed to get type. ${err.message}'); + console.error(`Failed to get type. ${err.message}`); return; } console.log('Callback returned with an array of metadataObjectType.'); @@ -4292,7 +4292,7 @@ Obtains the metadata object type. This API uses a promise to return the result. | Type | Description | | --------------------------------------------------- | --------------------------- | -| Promise<[MetadataObjectType](#metadataObjectType)\> | Promise used to return the result.| +| Promise<[MetadataObjectType](#metadataobjecttype)\> | Promise used to return the result.| **Example** @@ -4321,7 +4321,7 @@ Obtains the metadata timestamp. This API uses an asynchronous callback to return ```js metadataObject.getTimestamp((err) => { if (err) { - console.error('Failed to get timestamp. ${err.message}'); + console.error(`Failed to get timestamp. ${err.message}`); return; } console.log('Callback returned with timestamp getted.'); @@ -4369,7 +4369,7 @@ Obtains the bounding box of metadata. This API uses an asynchronous callback to ```js metadataObject.getBoundingBox((err, rect) => { if (err) { - console.error('Failed to get boundingBox. ${err.message}'); + console.error(`Failed to get boundingBox. ${err.message}`); return; } console.log('Callback returned with boundingBox getted.'); @@ -4425,7 +4425,7 @@ Starts to output metadata. This API uses an asynchronous callback to return the ```js metadataOutput.start((err) => { if (err) { - console.error('Failed to start metadataOutput. ${err.message}'); + console.error(`Failed to start metadataOutput. ${err.message}`); return; } console.log('Callback returned with metadataOutput started.'); @@ -4473,7 +4473,7 @@ Stops outputting metadata. This API uses an asynchronous callback to return the ```js metadataOutput.stop((err) => { if (err) { - console.error('Failed to stop the metadataOutput. ${err.message}'); + console.error(`Failed to stop the metadataOutput. ${err.message}`); return; } console.log('Callback returned with metadataOutput stoped.'); @@ -4515,13 +4515,13 @@ Listens for metadata objects. This API uses an asynchronous callback to return t | Name | Type | Mandatory| Description | | -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | Yes | Event type. The value is fixed at **'metadataObjectsAvailable'**, that is, the metadata object.| -| callback | Callback\> | Yes | Callback used to return the error information. | +| callback | Callback\> | Yes | Callback used to return the error information. | **Example** ```js metadataOutput.on('metadataObjectsAvailable', (metadataObject) => { - console.log('metadata output error code: ' + metadataObject.code); + console.log(`metadata output error code: ${metadataObject.code}`); }) ``` @@ -4538,13 +4538,13 @@ Listens for metadata errors. This API uses an asynchronous callback to return th | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------ | ---- | --------------------------------------------- | | type | string | Yes | Event type. The value is fixed at **'error'**, that is, the metadata error.| -| callback | Callback<[MetadataOutputError](#metadataOutputError)\> | Yes | Callback used to return the error information. | +| callback | Callback<[MetadataOutputError](#metadataoutputerror)\> | Yes | Callback used to return the error information. | **Example** ```js metadataOutput.on('error', (metadataOutputError) => { - console.log('Metadata output error code: ' + metadataOutputError.code); + console.log(`Metadata output error code: ${metadataOutputError.code}`); }) ``` @@ -4567,4 +4567,4 @@ Defines a metadata output error. | Name| Type | Description | | ---- | --------------------------------------------------- | -------------------------- | -| code | [MetadataOutputErrorCode](#MetadataOutputErrorCode) | **MetadataOutput** error code.| +| code | [MetadataOutputErrorCode](#metadataoutputerrorcode) | **MetadataOutput** error code.| diff --git a/en/application-dev/reference/apis/js-apis-cardEmulation.md b/en/application-dev/reference/apis/js-apis-cardEmulation.md index 7c65ecbd616c0bd3ea8fb0c7f7b12a06b67533d4..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 8. 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-device-manager.md b/en/application-dev/reference/apis/js-apis-device-manager.md index 8c27495f208ad620ed6e104fb19c958350805c1e..659a6b126357cb32865e9bc1d21eecd5228bdfd5 100644 --- a/en/application-dev/reference/apis/js-apis-device-manager.md +++ b/en/application-dev/reference/apis/js-apis-device-manager.md @@ -9,7 +9,7 @@ System applications can call the APIs to do the following: - Authenticate or deauthenticate a device. - Query the trusted device list. - Query local device information, including the device name, type, and ID. - +- Publish device information for discovery purposes. > **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. @@ -31,23 +31,24 @@ Creates a **DeviceManager** instance. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | ---------- | ---------------------------------------- | ---- | ------------------------------------ | - | bundleName | string | Yes | Bundle name of an application. | - | callback | AsyncCallback<[DeviceManager](#devicemanager)> | Yes | Callback used to return the **DeviceManager** instance created.| +**Parameters** +| Name | Type | Mandatory | Description | +| ---------- | ---------------------------------------- | ---- | ------------------------------------ | +| bundleName | string | Yes | Bundle name of an application. | +| callback | AsyncCallback<[DeviceManager](#devicemanager)> | Yes | Callback used to return the **DeviceManager** instance created.| -- Example - ``` - deviceManager.createDeviceManager("ohos.samples.jshelloworld", (err, data) => { - if (err) { - console.info("createDeviceManager err:" + JSON.stringify(err)); - return; - } - console.info("createDeviceManager success"); - let dmInstance = data; - }); - ``` +**Example** + +``` +deviceManager.createDeviceManager("ohos.samples.jshelloworld", (err, data) => { + if (err) { + console.info("createDeviceManager err:" + JSON.stringify(err)); + return; + } + console.info("createDeviceManager success"); + let dmInstance = data; +}); +``` ## DeviceInfo @@ -61,7 +62,7 @@ Defines device information. | deviceName | string | Yes | Device name. | | deviceType | [DeviceType](#devicetype) | Yes | Device type. | | networkId8+ | string | Yes | Network ID of the device. | - +| range9+ | number | Yes | Distance between the device (discovered device) and the device that initiates device discovery. | ## DeviceType @@ -184,6 +185,18 @@ Defines authentication information. | token | number | Yes | Authentication token. | | extraInfo | {[key:string] : any} | No | Extended field.| +## PublishInfo + +Defines published device information. + +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +| Name | Type | Mandatory | Description | +| ------------- | --------------------------------- | ---- | ----------------- | +| publishId | number | Yes | ID used to identify a publication period.| +| mode | [DiscoverMode ](#discovermode) | Yes | Device discovery mode. | +| freq | [ExchangeFreq](#exchangefreq) | Yes | Frequency of device discovery. | +| ranging | boolean | Yes | Whether the device supports distance reporting. | ## DeviceManager @@ -198,10 +211,11 @@ Releases this **DeviceManager** instance when it is no longer used. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- Example - ```js - dmInstance.release(); - ``` +**Example** + +```js +dmInstance.release(); +``` ### getTrustedDeviceListSync @@ -212,15 +226,17 @@ Obtains all trusted devices synchronously. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- Return value - | Name | Description | - | -------------------------------------- | --------- | - | Array<[DeviceInfo](#deviceinfo)> | List of trusted devices obtained.| +**Return value** -- Example - ```js - var deviceInfoList = dmInstance.getTrustedDeviceListSync(); - ``` +| Name | Description | +| -------------------------------------- | --------- | +| Array<[DeviceInfo](#deviceinfo)> | List of trusted devices obtained.| + +**Example** + +```js +var deviceInfoList = dmInstance.getTrustedDeviceListSync(); +``` ### getTrustedDeviceList8+ @@ -231,12 +247,12 @@ Obtains all trusted devices. This API uses an asynchronous callback to return th **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | --------------------- | - | callback | AsyncCallback<Array<[DeviceInfo](#deviceinfo)>> | Yes | Callback used to return the list of trusted devices.| +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------------------- | +| callback | AsyncCallback<Array<[DeviceInfo](#deviceinfo)>> | Yes | Callback used to return the list of trusted devices.| -- Example +**Example** ```js dmInstance.getTrustedDeviceList((err, data) => { console.log("getTrustedDeviceList err: " + JSON.stringify(err)); @@ -253,12 +269,12 @@ Obtains all trusted devices. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- Return value - | Type | Description | - | ---------------------------------------- | --------------------- | - | Promise<Array<[DeviceInfo](#deviceinfo)>> | Promise used to return the list of trusted devices.| +**Return value** +| Type | Description | +| ---------------------------------------- | --------------------- | +| Promise<Array<[DeviceInfo](#deviceinfo)>> | Promise used to return the list of trusted devices.| -- Example +**Example** ```js dmInstance.getTrustedDeviceList().then((data) => { console.log('get trusted device info: ' + JSON.stringify(data)); @@ -275,12 +291,12 @@ Obtains local device information synchronously. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- Return value - | Name | Description | - | -------------------------------------- | --------- | - | Array<[DeviceInfo](#deviceinfo)> | List of local devices obtained.| +**Return value** +| Name | Description | +| -------------------------------------- | --------- | +| Array<[DeviceInfo](#deviceinfo)> | List of local devices obtained.| -- Example +**Example** ```js var deviceInfo = dmInstance.getLocalDeviceInfoSync(); ``` @@ -294,12 +310,12 @@ Obtains local device information. This API uses an asynchronous callback to retu **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | --------- | - | callback | AsyncCallback<[DeviceInfo](#deviceinfo)> | Yes | Callback used to return the local device information.| +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| callback | AsyncCallback<[DeviceInfo](#deviceinfo)> | Yes | Callback used to return the local device information.| -- Example +**Example** ```js dmInstance.getLocalDeviceInfo((err, data) => { console.log("getLocalDeviceInfo err: " + JSON.stringify(err)); @@ -316,12 +332,12 @@ Obtains local device information. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- Return value - | Type | Description | - | ---------------------------------------- | --------------------- | - | Promise<[DeviceInfo](#deviceinfo)> | Promise used to return the local device information.| +**Return value** +| Type | Description | +| ---------------------------------------- | --------------------- | +| Promise<[DeviceInfo](#deviceinfo)> | Promise used to return the local device information.| -- Example +**Example** ```js dmInstance.getLocalDeviceInfo().then((data) => { console.log('get local device info: ' + JSON.stringify(data)); @@ -338,12 +354,12 @@ Starts to discover peripheral devices. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | ------------- | ------------------------------- | ---- | ----- | - | subscribeInfo | [SubscribeInfo](#subscribeinfo) | Yes | Subscription information.| +**Parameters** +| Name | Type | Mandatory | Description | +| ------------- | ------------------------------- | ---- | ----- | +| subscribeInfo | [SubscribeInfo](#subscribeinfo) | Yes | Subscription information.| -- Example +**Example** ```js // Automatically generate a unique subscription ID. var subscribeId = Math.floor(Math.random() * 10000 + 1000); @@ -359,6 +375,45 @@ Starts to discover peripheral devices. dmInstance.startDeviceDiscovery(subscribeInfo); // The deviceFound callback is invoked to notify the application when a device is discovered. ``` +### startDeviceDiscovery9+ + +startDeviceDiscovery(subscribeInfo: SubscribeInfo, filterOptions: string): void + +Starts to discover peripheral devices and filters discovered devices. + +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +**Parameters** +| Name | Type | Mandatory | Description | +| ------------- | ------------------------------- | ---- | ----- | +| subscribeInfo | [SubscribeInfo](#subscribeinfo) | Yes | Subscription information.| +| filterOptions | string | No | Options for filtering discovered devices.| + +**Example** + ```js + // Automatically generate a unique subscription ID. + var subscribeId = Math.floor(Math.random() * 10000 + 1000); + var subscribeInfo = { + "subscribeId": subscribeId, + "mode": 0xAA, // Active discovery + "medium": 0, // Automatic. Multiple media can be used for device discovery. + "freq": 2, // High frequency + "isSameAccount": false, + "isWakeRemote": false, + "capability": 1 + }; + var filterOptions = { + "filter_op": "OR", // Optional. The default value is OR. + "filters": [ + { + "type": "range", + "value": 50 // Filter discovered devices based on the distance (in cm). + } + ] + }; + dmInstance.startDeviceDiscovery(subscribeInfo, JSON.stringify(filterOptions)); // The deviceFound callback is invoked to notify the application when a device is discovered. + ``` + ### stopDeviceDiscovery stopDeviceDiscovery(subscribeId: number): void @@ -367,17 +422,63 @@ Stops device discovery. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | ----------- | ------ | ---- | ----- | - | subscribeId | number | Yes | Subscription ID.| +**Parameters** +| Name | Type | Mandatory | Description | +| ----------- | ------ | ---- | ----- | +| subscribeId | number | Yes | Subscription ID.| -- Example +**Example** ```js // The subscribeId input must be the same as that automatically generated in startDeviceDiscovery. dmInstance.stopDeviceDiscovery(subscribeId); ``` +### publishDeviceDiscovery9+ + +publishDeviceDiscovery(publishInfo: PublishInfo): void + +Publishes device information for discovery purposes. + +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +**Parameters** +| Name | Type | Mandatory| Description | +| ------------- | ------------------------------- | ---- | ----- | +| publishInfo | [PublishInfo](#publishinfo) | Yes | Device information to publish.| + +**Example** + ```js + // Automatically generate a unique subscription ID. + var publishId = Math.floor(Math.random() * 10000 + 1000); + var publishInfo = { + "publishId": publishId, + "mode": 0xAA, // Active discovery + "freq": 2, // High frequency + "ranging": 1 // The device supports reporting the distance to the discovery initiator. + }; + dmInstance.publishDeviceDiscovery(publishInfo); // A callback is invoked to notify the application when the device information is published. + ``` + +### unPublishDeviceDiscovery + +unPublishDeviceDiscovery(publishId: number): void + +Stops publishing device information. + +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +**Parameters** + +| Name | Type| Mandatory| Description | +| ----------- | -------- | ---- | ----- | +| publishId | number | Yes | Publish ID.| + +**Example** + ```js + // The publishId input must be the same as that automatically generated in publishDeviceDiscovery. + dmInstance.unPublishDeviceDiscovery(publishId); + ``` + ### authenticateDevice authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: AsyncCallback<{deviceId: string, pinToken ?: number}>): void @@ -386,14 +487,14 @@ Authenticates a device. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | ---------- | ---------------------------------------- | ---- | ------- | - | deviceInfo | [DeviceInfo](#deviceinfo) | Yes | Device information. | - | authParam | [AuthParam](#authparam) | Yes | Authentication parameter. | - | callback | AsyncCallback<{ deviceId: string, pinToken ?: number }> | Yes | Callback used to return the authentication result.| +**Parameters** +| Name | Type | Mandatory | Description | +| ---------- | ---------------------------------------- | ---- | ------- | +| deviceInfo | [DeviceInfo](#deviceinfo) | Yes | Device information. | +| authParam | [AuthParam](#authparam) | Yes | Authentication parameter. | +| callback | AsyncCallback<{ deviceId: string, pinToken ?: number }> | Yes | Callback used to return the authentication result.| -- Example +**Example** ```js // Information about the device to authenticate. The information can be obtained from the device discovery result. var deviceInfo ={ @@ -423,12 +524,13 @@ Deauthenticates a device. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | ---------- | ------------------------- | ---- | ----- | - | deviceInfo | [DeviceInfo](#deviceinfo) | Yes | Device information.| +**Parameters** + +| Name | Type | Mandatory | Description | +| ---------- | ------------------------- | ---- | ----- | +| deviceInfo | [DeviceInfo](#deviceinfo) | Yes | Device information.| -- Example +**Example** ```js dmInstance.unAuthenticateDevice(deviceInfo); ``` @@ -442,13 +544,13 @@ Verifies authentication information. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | ------- | - | authInfo | [AuthInfo](#authinfo) | Yes | Authentication information. | - | authInfo | AsyncCallback<{ deviceId: string, level: number }> | Yes | Callback used to return the verification result.| +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------- | +| authInfo | [AuthInfo](#authinfo) | Yes | Authentication information. | +| authInfo | AsyncCallback<{ deviceId: string, level: number }> | Yes | Callback used to return the verification result.| -- Example +**Example** ```js let authInfo = { "authType": 1, @@ -473,13 +575,13 @@ Subscribes to changes in the device state. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | ------------------------------ | - | type | string | Yes | Event type. The value **'deviceStateChange'** indicates a device state change event.| - | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | Yes | Callback invoked to return the device information and state. | +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------------------------ | +| type | string | Yes | Event type. The value **'deviceStateChange'** indicates a device state change event.| +| callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | Yes | Callback invoked to return the device information and state. | -- Example +**Example** ```js dmInstance.on('deviceStateChange', (data) => { console.info("deviceStateChange on:" + JSON.stringify(data)); @@ -496,19 +598,20 @@ Unsubscribes from changes in the device state. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | --------------------------- | - | type | string | Yes | Event type. The value **'deviceStateChange'** indicates a device state change event. | - | callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | Yes | Callback invoked to return the device information and state.| +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------------------------- | +| type | string | Yes | Event type. The value **'deviceStateChange'** indicates a device state change event. | +| callback | Callback<{ action: [DeviceStateChangeAction](#devicestatechangeaction), device: [DeviceInfo](#deviceinfo) }> | Yes | Callback invoked to return the device information and state.| -- Example - ```js - dmInstance.off('deviceStateChange', (data) => { - console.info('deviceStateChange' + JSON.stringify(data)); - } - ); - ``` +**Example** + +```js +dmInstance.off('deviceStateChange', (data) => { + console.info('deviceStateChange' + JSON.stringify(data)); + } +); +``` ### on('deviceFound') @@ -519,13 +622,13 @@ Subscribes to device discovery events. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | -------------------------- | - | type | string | Yes | Event type. The value **'deviceFound'** indicates an event reported when a device is discovered.| - | callback | Callback<{ subscribeId: number, device: DeviceInfo }> | Yes | Callback used for device discovery. | +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | -------------------------- | +| type | string | Yes | Event type. The value **'deviceFound'** indicates an event reported when a device is discovered.| +| callback | Callback<{ subscribeId: number, device: DeviceInfo }> | Yes | Callback used for device discovery. | -- Example +**Example** ```js dmInstance.on('deviceFound', (data) => { console.info("deviceFound:" + JSON.stringify(data)); @@ -541,13 +644,13 @@ Unsubscribes from device discovery events. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | --------------------------- | - | type | string | Yes | Event type. The value **'deviceFound'** indicates an event reported when a device is discovered. | - | callback | Callback<{ subscribeId: number, device: [DeviceInfo](#deviceinfo) }> | Yes | Callback used for device discovery, which is invoked to return the device information and state.| +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------------------------- | +| type | string | Yes | Event type. The value **'deviceFound'** indicates an event reported when a device is discovered. | +| callback | Callback<{ subscribeId: number, device: [DeviceInfo](#deviceinfo) }> | Yes | Callback invoked to return the device information and state.| -- Example +**Example** ```js dmInstance.off('deviceFound', (data) => { console.info('deviceFound' + JSON.stringify(data)); @@ -563,13 +666,13 @@ Subscribes to device discovery failures. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | ------------------------------ | - | type | string | Yes | Event type. The event **'discoverFail'** indicates an event reported when device discovery fails.| - | callback | Callback<{ subscribeId: number, reason: number }> | Yes | Callback used for the device discovery failure. | +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------------------------ | +| type | string | Yes | Event type. The event **'discoverFail'** indicates an event reported when device discovery fails.| +| callback | Callback<{ subscribeId: number, reason: number }> | Yes | Callback used for the device discovery failure. | -- Example +**Example** ```js dmInstance.on('discoverFail', (data) => { this.log("discoverFail on:" + JSON.stringify(data)); @@ -585,13 +688,13 @@ Unsubscribes from device discovery failures. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | ----------------- | - | type | string | Yes | Event type. The event **'discoverFail'** indicates an event reported when device discovery fails. | - | callback | Callback<{ subscribeId: number, reason: number }> | Yes | Callback used for the device discovery failure.| +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ----------------- | +| type | string | Yes | Event type. The event **'discoverFail'** indicates an event reported when device discovery fails. | +| callback | Callback<{ subscribeId: number, reason: number }> | Yes | Callback used for the device discovery failure.| -- Example +**Example** ```js dmInstance.off('deviceFound', (data) => { console.info('deviceFound' + JSON.stringify(data)); @@ -599,6 +702,93 @@ Unsubscribes from device discovery failures. ); ``` +### on('publishSuccess') + +on(type: 'publishSuccess', callback: Callback<{ publishId: number }>): void + +Subscribes to device information publication success events. + +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +**Parameters** +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------- | ---- | -------------------------- | +| type | string | Yes | Event type. The value **'publishSuccess'** indicates an event reported when device information is published.| +| callback | Callback<{ publishId: number }> | Yes | Callback invoked to return the publish ID. | + +**Example** +```js +dmInstance.on('publishSuccess', (data) => { + console.info("publishSuccess:" + JSON.stringify(data)); + } +); +``` + +### off('publishSuccess') + +off(type: 'publishSuccess', callback?: Callback<{ publishId: number }>): void + +Unsubscribes from device information publication success events. + +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +**Parameters** +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------- | ---- | --------------------------- | +| type | string | Yes | Event type. The value **'publishSuccess'** indicates an event reported when device information is published. | +| callback | Callback<{ publishId: number }> | Yes | Callback used to return the publish ID.| + +**Example** + ```js + dmInstance.off('publishSuccess', (data) => { + console.info('publishSuccess' + JSON.stringify(data)); + } + ); + ``` + +### on('publishFail') + +on(type: 'publishFail', callback: Callback<{ publishId: number, reason: number }>): void + +Subscribes to device information publication failures. + +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +**Parameters** +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------------- | ---- | ------------------------------ | +| type | string | Yes | Event type. The event **'publishFail'** indicates an event reported when publishing device information fails.| +| callback | Callback<{ publishId: number, reason: number }> | Yes | Callback used for the publication failure. | + +**Example** + ```js + dmInstance.on('publishFail', (data) => { + this.log("publishFail on:" + JSON.stringify(data)); + } + ); + ``` + +### off('publishFail') + +off(type: 'publishFail', callback?: Callback<{ publishId: number, reason: number }>): void + +Unsubscribes from device information publication failures. + +**System capability**: SystemCapability.DistributedHardware.DeviceManager + +**Parameters** +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------------- | ---- | ----------------- | +| type | string | Yes | Event type. The event **'publishFail'** indicates an event reported when publishing device information fails. | +| callback | Callback<{ publishId: number, reason: number }> | Yes | Callback used for the device discovery failure.| + +**Example** + ```js + dmInstance.off('publishFail', (data) => { + console.info('publishFail' + JSON.stringify(data)); + } + ); + ``` ### on('serviceDie') @@ -608,13 +798,13 @@ Subscribes to dead events of the **DeviceManager** service. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ----------------------- | ---- | ---------------------------------------- | - | type | string | Yes | Event type. The value **'serviceDie'** indicates an event reported when the **DeviceManager** service is terminated unexpectedly.| - | callback | () => void | Yes | Callback invoked when a dead event of the **DeviceManager** service occurs. | +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ----------------------- | ---- | ---------------------------------------- | +| type | string | Yes | Event type. The value **'serviceDie'** indicates an event reported when the **DeviceManager** service is terminated unexpectedly.| +| callback | () => void | Yes | Callback invoked when a dead event of the **DeviceManager** service occurs. | -- Example +**Example** ```js dmInstance.on("serviceDie", () => { console.info("serviceDie on"); @@ -631,13 +821,13 @@ Unsubscribes from dead events of the **DeviceManager** service. **System capability**: SystemCapability.DistributedHardware.DeviceManager -- **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ----------------------- | ---- | ---------------------------------------- | - | type | string | Yes | Event type. The value **'serviceDie'** indicates an event reported when the **DeviceManager** service is terminated unexpectedly.| - | callback | () => void | No | Callback used to return the dead event of the **DeviceManager** service. | +**Parameters** +| Name | Type | Mandatory | Description | +| -------- | ----------------------- | ---- | ---------------------------------------- | +| type | string | Yes | Event type. The value **'serviceDie'** indicates an event reported when the **DeviceManager** service is terminated unexpectedly.| +| callback | () => void | No | Callback used to return the dead event of the **DeviceManager** service. | -- Example +**Example** ```js dmInstance.off("serviceDie", () => { console.info("serviceDie off"); 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-distributedMissionManager.md b/en/application-dev/reference/apis/js-apis-distributedMissionManager.md new file mode 100644 index 0000000000000000000000000000000000000000..4c7d2ea1d3d66e5d65118f376ed2a9300dd06cd3 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-distributedMissionManager.md @@ -0,0 +1,345 @@ +# Distributed Mission Management + +The **distributedMissionManager** module implements system mission management across devices. You can use the APIs provided by this module to register or deregister a mission status listener, and start or stop synchronizing the remote mission list. + +> **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 provided by this module are system APIs. + +## Modules to Import + +```js +import distributedMissionManager from '@ohos.distributedMissionManager' +``` + + +## distributedMissionManager.registerMissionListener + +registerMissionListener(parameter: MissionDeviceInfo, options: MissionCallback, callback: AsyncCallback<void>): void; + +Registers a mission status listener. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | --------------------------------------- | ---- | --------- | +| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes | Information about the device to listen for.| +| options | [MissionCallback](#missioncallback) | Yes | Callback to register. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + + ```ts + function NotifyMissionsChanged(deviceId) { + console.log('NotifyMissionsChanged deviceId ' + JSON.stringify(deviceId)); + } + function NotifySnapshot(deviceId, missionId) { + console.log('NotifySnapshot deviceId ' + JSON.stringify(deviceId)); + console.log('NotifySnapshot missionId ' + JSON.stringify(missionId)); + } + function NotifyNetDisconnect(deviceId, state) { + console.log('NotifyNetDisconnect deviceId ' + JSON.stringify(deviceId)); + console.log('NotifyNetDisconnect state ' + JSON.stringify(state)); + } + var parameter = { + deviceId: remoteDeviceId + }; + var options = { + notifyMissionsChanged: NotifyMissionsChanged, + notifySnapshot: NotifySnapshot, + notifyNetDisconnect: NotifyNetDisconnect + } + distributedMissionManager.registerMissionListener(parameter, options, (error) => { + console.log("error.code = " + error.code) + }) + ``` +## distributedMissionManager.registerMissionListener + +registerMissionListener(parameter: MissionDeviceInfo, options: MissionCallback): Promise<void> + +Registers a mission status listener. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------- | +| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes | Information about the device to listen for. | +| options | MissionCallback | Yes | Callback to register.| + +**Return value** + +| Type | Description | +| ------------------- | ---------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + function NotifyMissionsChanged(deviceId) { + console.log('NotifyMissionsChanged deviceId ' + JSON.stringify(deviceId)); + } + function NotifySnapshot(deviceId, missionId) { + console.log('NotifySnapshot deviceId ' + JSON.stringify(deviceId)); + console.log('NotifySnapshot missionId ' + JSON.stringify(missionId)); + } + function NotifyNetDisconnect(deviceId, state) { + console.log('NotifyNetDisconnect deviceId ' + JSON.stringify(deviceId)); + console.log('NotifyNetDisconnect state ' + JSON.stringify(state)); + } + var parameter = { + deviceId: remoteDeviceId + }; + var options = { + notifyMissionsChanged: NotifyMissionsChanged, + notifySnapshot: NotifySnapshot, + notifyNetDisconnect: NotifyNetDisconnect + } + distributedMissionManager.registerMissionListener(parameter, options) + .then(data => { + console.info('success data is ' + data); + }).catch(error => { + console.info('error error is ' + error); + }) + ``` + + +## distributedMissionManager.unregisterMissionListener + +unregisterMissionListener(parameter: MissionDeviceInfo, callback: AsyncCallback<void>): void; + +Deregisters a mission status listener. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | --------------------------------------- | ---- | --------- | +| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes | Information about the device to listen for. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + + ```ts + var parameter = { + deviceId: remoteDeviceId + }; + distributedMissionManager.unregisterMissionListener(parameter, (error) => { + console.log("error.code = " + error.code) + }) + ``` + + +## distributedMissionManager.unregisterMissionListener + +unregisterMissionListener(parameter: MissionDeviceInfo): Promise<void> + +Deregisters a mission status listener. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | --------------------------------------- | ---- | ----- | +| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes | Information about the device to listen for.| + +**Return value** + +| Type | Description | +| ------------------- | ---------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + var parameter = { + deviceId: remoteDeviceId + }; + distributedMissionManager.unregisterMissionListener(parameter) + .then(data => { + console.info('success data is ' + data); + }).catch(error => { + console.info('error error is ' + error); + }) + ``` + +## distributedMissionManager.startSyncRemoteMissions + +startSyncRemoteMissions(parameter: MissionParameter, callback: AsyncCallback<void>): void; + +Starts to synchronize the remote mission list. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ------------------------------------- | ---- | --------- | +| parameter | [MissionParameter](#missionparameter) | Yes | Parameters required for synchronization. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + + ```ts + var parameter = { + deviceId: remoteDeviceId, + fixConflict: false, + tag: 0 + }; + distributedMissionManager.startSyncRemoteMissions(parameter, (error) => { + console.log("error.code = " + error.code) + }) + ``` + +## distributedMissionManager.startSyncRemoteMissions + +startSyncRemoteMissions(parameter: MissionParameter): Promise<void> + +Starts to synchronize the remote mission list. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ------------------------------------- | ---- | ----- | +| parameter | [MissionParameter](#missionparameter) | Yes | Parameters required for synchronization.| + +**Return value** + +| Type | Description | +| ------------------- | ---------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + var parameter = { + deviceId: remoteDeviceId, + fixConflict: false, + tag: 0 + }; + distributedMissionManager.startSyncRemoteMissions(parameter) + .then(data => { + console.info('success data is ' + data); + }).catch(error => { + console.info('error error is ' + error); + }) + ``` + +## distributedMissionManager.stopSyncRemoteMissions + +stopSyncRemoteMissions(parameter: MissionDeviceInfo, callback: AsyncCallback<void>): void; + +Stops synchronizing the remote mission list. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | --------------------------------------- | ---- | --------- | +| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes | Parameters required for synchronization. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Example** + + ```ts + var parameter = { + deviceId: remoteDeviceId + }; + distributedMissionManager.stopSyncRemoteMissions(parameter, (error) => { + console.log("error.code = " + error.code) + }) + ``` + +## distributedMissionManager.stopSyncRemoteMissions + +stopSyncRemoteMissions(parameter: MissionDeviceInfo): Promise<void> + +Stops synchronizing the remote mission list. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | --------------------------------------- | ---- | ----- | +| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes | Parameters required for synchronization.| + +**Return value** + +| Type | Description | +| ------------------- | ---------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + var parameter = { + deviceId: remoteDeviceId + }; + distributedMissionManager.stopSyncRemoteMissions(parameter) + .then(data => { + console.info('success data is ' + data); + }).catch(error => { + console.info('error error is ' + error); + }) + ``` + +## MissionCallback + +Defines the callbacks that can be registered as a mission status listener. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name | Type | Readable | Writable | Description | +| --------------------- | -------- | ---- | ---- | ------------------ | +| notifyMissionsChanged | function | Yes | No | Callback used to notify the mission change event and return the device ID. | +| notifySnapshot | function | Yes | No | Callback used to notify the snapshot change event and return the device ID and mission ID.| +| notifyNetDisconnect | function | Yes | No | Callback used to notify the disconnection event and return the device ID and network status.| + +## MissionParameter + +Defines the parameters required for mission synchronization. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name | Type | Readable | Writable | Description | +| ----------- | ------- | ---- | ---- | ----------- | +| deviceId | string | Yes | Yes | Device ID. | +| fixConflict | boolean | Yes | Yes | Whether a version conflict occurs.| +| tag | number | Yes | Yes | Tag of the mission. | + +## MissionDeviceInfo + +Defines the parameters required for registering a listener. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name | Type | Readable | Writable | Description | +| -------- | ------ | ---- | ---- | ------- | +| deviceId | string | Yes | Yes | Device ID.| 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 0abc724302fcf89b86421b90c0bb507f1894b312..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). @@ -34,7 +35,7 @@ Obtains the localized script for the specified language. | string | Localized script for the specified language.| **Example** - ``` + ```js i18n.getDisplayLanguage("zh", "en-GB", true); i18n.getDisplayLanguage("zh", "en-GB"); ``` @@ -61,7 +62,7 @@ Obtains the localized script for the specified country. | string | Localized script for the specified country.| **Example** - ``` + ```js i18n.getDisplayCountry("zh-CN", "en-GB", true); i18n.getDisplayCountry("zh-CN", "en-GB"); ``` @@ -86,7 +87,7 @@ Checks whether the localized script for the specified language is displayed from | boolean | Returns **true** if the localized script is displayed from right to left; returns **false** otherwise.| **Example** - ``` + ```js i18n.isRTL("zh-CN");// Since Chinese is not written from right to left, false is returned. i18n.isRTL("ar-EG");// Since Arabic is written from right to left, true is returned. ``` @@ -106,7 +107,7 @@ Obtains the system language. | string | System language ID.| **Example** - ``` + ```js i18n.getSystemLanguage(); ``` @@ -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. @@ -134,7 +135,7 @@ This is a system API. | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** - ``` + ```js i18n.setSystemLanguage('zh'); ``` @@ -155,7 +156,7 @@ Obtains the list of system languages. | Array<string> | List of the IDs of system languages.| **Example** - ``` + ```js i18n.getSystemLanguages(); ``` @@ -181,7 +182,7 @@ Obtains the list of countries and regions supported for the specified language. | Array<string> | List of the IDs of the countries and regions supported for the specified language.| **Example** - ``` + ```js i18n.getSystemCountries('zh'); ``` @@ -200,7 +201,7 @@ Obtains the system region. | string | System region ID.| **Example** - ``` + ```js i18n.getSystemRegion(); ``` @@ -228,7 +229,7 @@ This is a system API. | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** - ``` + ```js i18n.setSystemRegion('CN'); ``` @@ -247,7 +248,7 @@ Obtains the system locale. | string | System locale ID.| **Example** - ``` + ```js i18n.getSystemLocale(); ``` @@ -275,7 +276,7 @@ This is a system API. | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** - ``` + ```js i18n.setSystemLocale('zh-CN'); ``` @@ -302,7 +303,7 @@ Checks whether the system language matches the specified region. | boolean | Returns **true** if the system language matches the specified region; returns **false** otherwise.| **Example** - ``` + ```js i18n.isSuggested('zh', 'CN'); ``` @@ -327,7 +328,7 @@ Obtains a **Calendar** object. | [Calendar](#calendar8) | **Calendar** object.| **Example** - ``` + ```js i18n.getCalendar("zh-Hans", "gregory"); ``` @@ -349,7 +350,7 @@ Sets the date for this **Calendar** object. | date | Date | Yes | Date to be set for the **Calendar** object.| **Example** - ``` + ```js var calendar = i18n.getCalendar("en-US", "gregory"); var date = new Date(2021, 10, 7, 8, 0, 0, 0); calendar.setTime(date); @@ -370,7 +371,7 @@ Sets the date and time for this **Calendar** object. The value is represented by | time | number | Yes | Number of milliseconds that have elapsed since the Unix epoch.| **Example** - ``` + ```js var calendar = i18n.getCalendar("en-US", "gregory"); calendar.setTime(10540800000); ``` @@ -395,7 +396,7 @@ Sets the year, month, day, hour, minute, and second for this **Calendar** object | second | number | No | Second to set. | **Example** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00 ``` @@ -415,7 +416,7 @@ Sets the time zone of this **Calendar** object. | timezone | string | Yes | Time zone, for example, **Asia/Shanghai**.| **Example** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.setTimeZone("Asia/Shanghai"); ``` @@ -435,7 +436,7 @@ Obtains the time zone of this **Calendar** object. | string | Time zone of the **Calendar** object.| **Example** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.setTimeZone("Asia/Shanghai"); calendar.getTimeZone(); // Asia/Shanghai" @@ -456,7 +457,7 @@ Obtains the start day of a week for this **Calendar** object. | number | Start day of a week. The value **1** indicates Sunday, and the value **7** indicates Saturday.| **Example** - ``` + ```js var calendar = i18n.getCalendar("en-US", "gregory"); calendar.getFirstDayOfWeek(); ``` @@ -476,7 +477,7 @@ Sets the start day of a week for this **Calendar** object. | value | number | No | Start day of a week. The value **1** indicates Sunday, and the value **7** indicates Saturday.| **Example** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.setFirstDayOfWeek(0); ``` @@ -496,7 +497,7 @@ Obtains the minimum number of days in the first week of a year. | number | Minimum number of days in the first week of a year.| **Example** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.getMinimalDaysInFirstWeek(); ``` @@ -516,7 +517,7 @@ Sets the minimum number of days in the first week of a year. | value | number | No | Minimum number of days in the first week of a year.| **Example** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.setMinimalDaysInFirstWeek(3); ``` @@ -541,7 +542,7 @@ Obtains the value of the specified field in the **Calendar** object. | number | Value of the specified field. For example, if the year in the internal date of this **Calendar** object is **1990**, the **get("year")** function will return **1990**.| **Example** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00 calendar.get("hour_of_day"); // 8 @@ -567,7 +568,7 @@ Obtains the name of the **Calendar** object displayed for the specified locale. | string | Name of the **Calendar** object displayed for the specified locale.| **Example** - ``` + ```js var calendar = i18n.getCalendar("en-US", "buddhist"); calendar.getDisplayName("zh"); // Obtain the name of the Buddhist calendar in zh. ``` @@ -592,7 +593,7 @@ Checks whether the specified date in this **Calendar** object is a weekend. | boolean | Returns **true** if the date is a weekend; returns **false** if the date is a weekday.| **Example** - ``` + ```js var calendar = i18n.getCalendar("zh-Hans"); calendar.set(2021, 11, 11, 8, 0, 0); // set time to 2021.11.11 08:00:00 calendar.isWeekend(); // false @@ -619,7 +620,7 @@ Parameters | options | [PhoneNumberFormatOptions](#phonenumberformatoptions8) | No | Options of the **PhoneNumberFormat** object. | **Example** - ``` + ```js var phoneNumberFormat= new i18n.PhoneNumberFormat("CN", {"type": "E164"}); ``` @@ -643,7 +644,7 @@ Checks whether the format of the specified phone number is valid. | boolean | Returns **true** if the phone number format is valid; returns **false** otherwise.| **Example** - ``` + ```js var phonenumberfmt = new i18n.PhoneNumberFormat("CN"); phonenumberfmt.isValidNumber("15812312312"); ``` @@ -668,12 +669,12 @@ Formats a phone number. | string | Formatted phone number.| **Example** - ``` + ```js var phonenumberfmt = new i18n.PhoneNumberFormat("CN"); - phonenumberfmt.format("15812312312"); + phonenumberfmt.isValidNumber("15812312312"); ``` -### getLocationName8+ +### getLocationName9+ static getLocationName(number: string, locale: string): string @@ -693,11 +694,10 @@ Obtains the home location of a phone number. | string | Home location of the phone number.| **Example** + ```js + var phonenumberfmt = new i18n.PhoneNumberFormat("CN"); + phonenumberfmt.isValidNumber("15812312312"); ``` - var location = i18n.PhoneNumberFormat.getLocationName('15812312345', 'zh-CN'); - ``` - - ## PhoneNumberFormatOptions8+ @@ -749,10 +749,33 @@ Converts one measurement unit into another and formats the unit based on the spe | string | Character string obtained after formatting based on the measurement unit specified by **toUnit**.| **Example** - ``` + ```js 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+ @@ -773,7 +796,7 @@ Creates an **IndexUtil** object. | [IndexUtil](#indexutil8) | **IndexUtil** object mapping to the specified locale.| **Example** - ``` + ```js var indexUtil= i18n.getInstance("zh-CN"); ``` @@ -795,7 +818,7 @@ Obtains the index list for this **locale** object. | Array<string> | Index list for this **locale** object.| **Example** - ``` + ```js var indexUtil = i18n.getInstance("zh-CN"); var indexList = indexUtil.getIndexList(); ``` @@ -815,7 +838,7 @@ Adds the index of the new **locale** object to the index list. | locale | string | Yes | A string containing locale information, including the language, optional script, and region.| **Example** - ``` + ```js var indexUtil = i18n.getInstance("zh-CN"); indexUtil.addLocale("en-US"); ``` @@ -840,7 +863,7 @@ Obtains the index of a text object. | string | Index of the **text** object.| **Example** - ``` + ```js var indexUtil= i18n.getInstance("zh-CN"); indexUtil.getIndex("hi"); // Return h. ``` @@ -868,7 +891,7 @@ Checks whether the input character string is composed of digits. | boolean | Returns **true** if the input character is a digit; returns **false** otherwise.| **Example** - ``` + ```js var isdigit = i18n.Character.isDigit("1"); // Return true. ``` @@ -892,7 +915,7 @@ Checks whether the input character is a space. | boolean | Returns **true** if the input character is a space; returns **false** otherwise.| **Example** - ``` + ```js var isspacechar = i18n.Character.isSpaceChar("a"); // Return false. ``` @@ -916,7 +939,7 @@ Checks whether the input character is a white space. | boolean | Returns **true** if the input character is a white space; returns **false** otherwise.| **Example** - ``` + ```js var isspacechar = i18n.Character.isSpaceChar("a"); // Return false. ``` @@ -940,7 +963,7 @@ Checks whether the input character is of the right to left (RTL) language. | boolean | Returns **true** if the input character is of the RTL language; returns **false** otherwise.| **Example** - ``` + ```js var isrtl = i18n.Character.isRTL("a"); // Return false. ``` @@ -964,7 +987,7 @@ Checks whether the input character is an ideographic character. | boolean | Returns **true** if the input character is an ideographic character; returns **false** otherwise.| **Example** - ``` + ```js var isideograph = i18n.Character.isIdeograph("a"); // Return false. ``` @@ -988,7 +1011,7 @@ Checks whether the input character is a letter. | boolean | Returns **true** if the input character is a letter; returns **false** otherwise.| **Example** - ``` + ```js var isletter = i18n.Character.isLetter("a"); // Return true. ``` @@ -1012,7 +1035,7 @@ Checks whether the input character is a lowercase letter. | boolean | Returns **true** if the input character is a lowercase letter; returns **false** otherwise.| **Example** - ``` + ```js var islowercase = i18n.Character.isLowerCase("a"); // Return true. ``` @@ -1036,7 +1059,7 @@ Checks whether the input character is an uppercase letter. | boolean | Returns **true** if the input character is an uppercase letter; returns **false** otherwise.| **Example** - ``` + ```js var isuppercase = i18n.Character.isUpperCase("a"); // Return false. ``` @@ -1060,7 +1083,7 @@ Obtains the type of the input character string. | string | Type of the input character.| **Example** - ``` + ```js var type = i18n.Character.getType("a"); ``` @@ -1084,7 +1107,7 @@ Obtains a [BreakIterator](#breakiterator8) object for text segmentation. | [BreakIterator](#breakiterator8) | [BreakIterator](#breakiterator8) object used for text segmentation.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); ``` @@ -1106,7 +1129,7 @@ Sets the text to be processed by the [BreakIterator](#breakiterator8) object. | text | string | Yes | Text to be processed by the **BreakIterator** object.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); ``` @@ -1126,7 +1149,7 @@ Obtains the text being processed by the [BreakIterator](#breakiterator8) object. | string | Text being processed by the **BreakIterator** object.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.getLineBreakText(); // Apple is my favorite fruit. @@ -1147,7 +1170,7 @@ Obtains the position of the [BreakIterator](#breakiterator8) object in the text | number | Position of the **BreakIterator** object in the text being processed.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.current(); // 0 @@ -1168,7 +1191,7 @@ Puts the [BreakIterator](#breakiterator8) object to the first text boundary, whi | number | Offset to the first text boundary of the processed text.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.first(); // 0 @@ -1189,7 +1212,7 @@ Puts the [BreakIterator](#breakiterator8) object to the last text boundary, whic | number | Offset of the last text boundary of the processed text.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.last(); // 27 @@ -1215,7 +1238,7 @@ Moves the [BreakIterator](#breakiterator8) object backward by the specified numb | number | Position of the [BreakIterator](#breakiterator8) object in the text after it is moved by the specified number of text boundaries. The value **-1** is returned if the position of the [BreakIterator](#breakiterator8) object is outside of the processed text after it is moved by the specified number of text boundaries.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.first(); // 0 @@ -1238,7 +1261,7 @@ Moves the [BreakIterator](#breakiterator8) object to the previous text boundary. | number | Position of the [BreakIterator](#breakiterator8) object in the text after it is moved to the previous text boundary. The value **-1** is returned if the position of the [BreakIterator](#breakiterator8) object is outside of the processed text after it is moved by the specified number of text boundaries.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.first(); // 0 @@ -1266,7 +1289,7 @@ Moves the [BreakIterator](#breakiterator8) object to the text boundary after the | number | The value **-1** is returned if the text boundary to which the [BreakIterator](#breakiterator8) object is moved is outside of the processed text.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.following(0); // 6 @@ -1294,7 +1317,7 @@ Checks whether the position specified by the offset is a text boundary. If **tru | boolean | Returns **true** if the position specified by the offset is a text boundary; returns **false** otherwise.| **Example** - ``` + ```js var iterator = i18n.getLineInstance("en"); iterator.setLineBreakText("Apple is my favorite fruit."); iterator.isBoundary(0); // true; @@ -1316,7 +1339,7 @@ Checks whether the 24-hour clock is used. | boolean | Returns **true** if the 24-hour clock is used; returns **false** otherwise.| **Example** - ``` + ```js var is24HourClock = i18n.is24HourClock(); ``` @@ -1342,7 +1365,7 @@ Sets the 24-hour clock. | boolean | Returns **true** if the 24-hour clock is enabled; returns **false** otherwise.| **Example** - ``` + ```js // Set the system time to the 24-hour clock. var success = i18n.set24HourClock(true); ``` @@ -1370,7 +1393,7 @@ Adds a preferred language to the specified position on the preferred language li | boolean | Returns **true** if the preferred language is successfully added; returns **false** otherwise.| **Example** - ``` + ```js // Add zh-CN to the preferred language list. var language = 'zh-CN'; var index = 0; @@ -1399,7 +1422,7 @@ Deletes a preferred language from the specified position on the preferred langua | boolean | Returns **true** if the preferred language is deleted; returns **false** otherwise.| **Example** - ``` + ```js // Delete the first preferred language from the preferred language list. var index = 0; var success = i18n.removePreferredLanguage(index); @@ -1420,7 +1443,7 @@ Obtains the list of preferred languages. | Array<string> | List of preferred languages.| **Example** - ``` + ```js var preferredLanguageList = i18n.getPreferredLanguageList(); ``` @@ -1439,7 +1462,7 @@ Obtains the first language in the preferred language list. | string | First language in the preferred language list.| **Example** - ``` + ```js var firstPreferredLanguage = i18n.getFirstPreferredLanguage(); ``` @@ -1458,7 +1481,7 @@ Obtains the preferred language of an application. | string | Preferred language of the application.| **Example** - ``` + ```js var appPreferredLanguage = i18n.getAppPreferredLanguage(); ``` @@ -1482,15 +1505,15 @@ Obtains the **TimeZone** object corresponding to the specified time zone ID. | TimeZone | **TimeZone** object corresponding to the time zone ID.| **Example** - ``` + ```js var timezone = i18n.getTimeZone(); ``` -## TimeZone8+ +## TimeZone -### getID8+ +### getID getID(): string @@ -1504,13 +1527,13 @@ Obtains the ID of the specified **TimeZone** object. | string | Time zone ID corresponding to the **TimeZone** object.| **Example** - ``` + ```js var timezone = i18n.getTimeZone(); timezone.getID(); ``` -### getDisplayName8+ +### getDisplayName getDisplayName(locale?: string, isDST?: boolean): string @@ -1530,13 +1553,13 @@ Obtains the representation of a **TimeZone** object in the specified locale. | string | Representation of the **TimeZone** object in the specified locale.| **Example** - ``` + ```js var timezone = i18n.getTimeZone(); timezone.getDisplayName("zh-CN", false); ``` -### getRawOffset8+ +### getRawOffset getRawOffset(): number @@ -1550,13 +1573,13 @@ Obtains the offset between the time zone represented by a **TimeZone** object an | number | Offset between the time zone represented by the **TimeZone** object and the UTC time zone.| **Example** - ``` + ```js var timezone = i18n.getTimeZone(); timezone.getRawOffset(); ``` -### getOffset8+ +### getOffset getOffset(date?: number): number @@ -1570,7 +1593,7 @@ Obtains the offset between the time zone represented by a **TimeZone** object an | number | Offset between the time zone represented by the **TimeZone** object and the UTC time zone at a certain time point.| **Example** - ``` + ```js var timezone = i18n.getTimeZone(); timezone.getOffset(1234567890); ``` @@ -1589,7 +1612,7 @@ Obtains the list of time zone IDs supported by the system. | Array<string> | List of time zone IDs supported by the system.| **Example** - ``` + ```js var ids = i18n.TimeZone.getAvailableIDs(); ``` @@ -1608,7 +1631,7 @@ Obtains the list of time zone city IDs supported by the system. | Array<string> | List of time zone city IDs supported by the system.| **Example** - ``` + ```js var cityIDs = i18n.TimeZone.getAvailableZoneCityIDs(); ``` @@ -1633,7 +1656,7 @@ Obtains the localized display of a time zone city in the specified locale. | string | Localized display of the time zone city in the specified locale.| **Example** - ``` + ```js var displayName = i18n.TimeZone.getCityDisplayName("Shanghai", "zh-CN"); ``` @@ -1657,7 +1680,7 @@ Obtains the **TimeZone** object corresponding to the specified time zone city ID | TimeZone | **TimeZone** object corresponding to the specified time zone city ID.| **Example** - ``` + ```js var timezone = i18n.TimeZone.getTimezoneFromCity("Shanghai"); ``` @@ -1684,7 +1707,7 @@ This is a system API. | boolean | Result indicating whether the local digit switch is successfully set. The value **true** indicates that the local digit switch is successfully set, and the value **false** indicates the opposite.| **Example** - ``` + ```js var status = i18n.setUsingLocalDigit(true); ``` @@ -1703,6 +1726,76 @@ Checks whether the local digit switch is turned on. | boolean | Result indicating whether the local digit switch is turned on. The value **true** indicates that the local digit switch is turned on, and the value **false** indicates the opposite.| **Example** - ``` + ```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 dbb47a0d3ad9ee20ee500bc1d51d61ff380f63a5..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. > @@ -32,7 +32,7 @@ This is a system API. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | type | string | Yes| Type of the key input event to listen for. Only **key** is supported.| -| keyOptions | [keyOptions](#keyOptions) | Yes| Key option, which specifies the condition for combination key input.| +| keyOptions | [keyOptions](#keyoptions) | Yes| Key option, which specifies the condition for combination key input.| | callback | Callback<KeyOptions> | Yes| Callback used to return the result.
When a key input event that meets the specified options occurs, **keyOptions** will be passed as an input parameter to **callback**.| **Example** @@ -62,7 +62,7 @@ This is a system API. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | type | string | Yes| Type of the key input event to listen for. Only **key** is supported.| -| keyOptions | [keyOptions](#keyOptions) | Yes| Key options passed to the key input event when listening starts.| +| keyOptions | [keyOptions](#keyoptions) | Yes| Key options passed to the key input event when listening starts.| | callback | Callback<KeyOptions> | Yes| Callback function passed to the key input event with **keyOptions** when listening starts.| **Example** diff --git a/en/application-dev/reference/apis/js-apis-inputdevice.md b/en/application-dev/reference/apis/js-apis-inputdevice.md index 178313a1ff1a83a905895656793ff5977a486d0d..2f4986f90f431852a7b2e76d8f58e24ba8469ed9 100644 --- a/en/application-dev/reference/apis/js-apis-inputdevice.md +++ b/en/application-dev/reference/apis/js-apis-inputdevice.md @@ -4,7 +4,8 @@ The Input Device module implements listening for connection, disconnection, and update events of input devices and displays information about input devices. For example, it can be used to listen for mouse insertion and removal and obtain information such as the ID, name, and pointer speed of the mouse. -> **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. @@ -28,7 +29,7 @@ Enables listening for hot swap events of an input device. | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ----------- | | type | string | Yes | Event type of the input device. | -| listener | Callback<[DeviceListener](#devicelistener9+)> | Yes | Listener for events of the input device.| +| listener | Callback<[DeviceListener](#devicelistener9)> | Yes | Listener for events of the input device.| **Example** @@ -63,7 +64,7 @@ Disables listening for hot swap events of an input device. | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ----------- | | type | string | Yes | Event type of the input device. | -| listener | Callback<[DeviceListener](#devicelistener9+)> | No | Listener for events of the input device.| +| listener | Callback<[DeviceListener](#devicelistener9)> | No | Listener for events of the input device.| **Example** @@ -245,7 +246,7 @@ Obtains the keyboard type of an input device. This API uses an asynchronous call | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | --------------------------------- | | deviceId | number | Yes | Unique ID of the input device. If the same physical device is repeatedly inserted and removed, its ID changes.| -| callback | AsyncCallback<[KeyboardType](#keyboardtype)> | Yes | Callback used to return the result. | +| callback | AsyncCallback<[KeyboardType](#keyboardtype9)> | Yes | Callback used to return the result. | **Example** @@ -268,7 +269,7 @@ Obtains the keyboard type of an input device. This API uses a promise to return | Parameter | Description | | ---------------------------------------- | ------------------- | -| Promise<[KeyboardType](#keyboardtype)> | Promise used to return the result.| +| Promise<[KeyboardType](#keyboardtype9)> | Promise used to return the result.| **Example** @@ -336,7 +337,7 @@ Defines the axis range of an input device. | Name | Type | Description | | ----------------------- | ------------------------- | -------- | | source | [SourceType](#sourcetype) | Input source type of the axis.| -| axis | [AxisType](#axistype) | Axis type. | +| axis | [AxisType](#axistype9) | Axis type. | | max | number | Maximum value of the axis. | | min | number | Minimum value of the axis. | | fuzz9+ | number | Fuzzy value of the axis. | @@ -358,7 +359,7 @@ Enumerates the input source types. For example, if a mouse reports an x-axis eve | touchpad | string | The input device is a touchpad.| | joystick | string | The input device is a joystick.| -## ChangeType +## ChangedType Defines the change type for the hot swap event of an input device. diff --git a/en/application-dev/reference/apis/js-apis-inputmethod.md b/en/application-dev/reference/apis/js-apis-inputmethod.md index ed980e7f4eafc6ee00808ac3030b51a9490b2412..47f0d3429179406f598940f977baab87ef7b3482 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethod.md +++ b/en/application-dev/reference/apis/js-apis-inputmethod.md @@ -126,7 +126,7 @@ Switches to another input method. This API uses a promise to return the result. ``` ## InputMethodController -In the following API examples, you must first use **[getInputMethodController](#inputmethodgetinputmethodcontroller)** to obtain an **InputMethodController** instance, and then call the APIs using the obtained instance. +In the following API examples, you must first use [getInputMethodController](#inputmethodgetinputmethodcontroller) to obtain an **InputMethodController** instance, and then call the APIs using the obtained instance. ### stopInput @@ -174,7 +174,7 @@ Hides the keyboard. This API uses an asynchronous callback to return the result. ## InputMethodSetting8+ -In the following API examples, you must first use **[getInputMethodSetting](#inputmethodgetinputmethodcontroller)** to obtain an **InputMethodSetting** instance, and then call the APIs using the obtained instance. +In the following API examples, you must first use [getInputMethodSetting](#inputmethodgetinputmethodcontroller) to obtain an **InputMethodSetting** instance, and then call the APIs using the obtained instance. ### listInputMethod @@ -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-intl.md b/en/application-dev/reference/apis/js-apis-intl.md index d9be9b9a2cbc59fb48e2beae81da77d05be9c84f..3060af2da4bd047461f0cce0d866753bd8caf36a 100644 --- a/en/application-dev/reference/apis/js-apis-intl.md +++ b/en/application-dev/reference/apis/js-apis-intl.md @@ -536,7 +536,7 @@ Parameters **Example** ``` - var pluralRules= new Intl.PluraRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"}); + var pluralRules= new Intl.PluralRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"}); ``` 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..66af65d60b482342733fcc149c8b7b4078eeb851 100644 --- a/en/application-dev/reference/apis/js-apis-media.md +++ b/en/application-dev/reference/apis/js-apis-media.md @@ -61,7 +61,7 @@ Creates a **VideoPlayer** instance in asynchronous mode. This API uses a callbac let videoPlayer media.createVideoPlayer((error, video) => { - if (typeof(video) != 'undefined') { + if (video != null) { videoPlayer = video; console.info('video createVideoPlayer success'); } else { @@ -90,7 +90,7 @@ Creates a **VideoPlayer** instance in asynchronous mode. This API uses a promise let videoPlayer media.createVideoPlayer().then((video) => { - if (typeof(video) != 'undefined') { + if (video != null) { videoPlayer = video; console.info('video createVideoPlayer success'); } else { @@ -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 @@ -141,7 +143,7 @@ Creates a **VideoRecorder** instance in asynchronous mode. This API uses a callb let videoRecorder media.createVideoRecorder((error, video) => { - if (typeof(video) != 'undefined') { + if (video != null) { videoRecorder = video; console.info('video createVideoRecorder success'); } else { @@ -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 @@ -170,7 +173,7 @@ Creates a **VideoRecorder** instance in asynchronous mode. This API uses a promi let videoRecorder media.createVideoRecorder().then((video) => { - if (typeof(video) != 'undefined') { + if (video != null) { videoRecorder = video; console.info('video createVideoRecorder success'); } else { @@ -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 @@ -366,7 +370,7 @@ Seeks to the specified playback position. ```js audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback. - if (typeof (seekDoneTime) == 'undefined') { + if (seekDoneTime == null) { console.info('audio seek fail'); return; } @@ -439,7 +443,7 @@ function printfDescription(obj) { } audioPlayer.getTrackDescription((error, arrlist) => { - if (typeof (arrlist) != 'undefined') { + if (arrlist != null) { for (let i = 0; i < arrlist.length; i++) { printfDescription(arrlist[i]); } @@ -475,7 +479,7 @@ function printfDescription(obj) { } audioPlayer.getTrackDescription().then((arrlist) => { - if (typeof (arrlist) != 'undefined') { + if (arrlist != null) { arrayDescription = arrlist; } else { console.log('audio getTrackDescription fail'); @@ -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** @@ -550,7 +554,7 @@ audioPlayer.on('reset', () => { // Set the 'reset' event callback. audioPlayer = undefined; }); audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback. - if (typeof(seekDoneTime) == "undefined") { + if (seekDoneTime == null) { console.info('audio seek fail'); return; } @@ -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,14 +602,14 @@ 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** ```js audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback. - if (typeof (seekDoneTime) == 'undefined') { + if (seekDoneTime == null) { console.info('audio seek fail'); return; } @@ -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+ @@ -695,7 +727,7 @@ Sets **SurfaceId**. This API uses a callback to return the result. ```js videoPlayer.setDisplaySurface(surfaceId, (err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('setDisplaySurface success!'); } else { console.info('setDisplaySurface fail!'); @@ -753,7 +785,7 @@ Prepares for video playback. This API uses a callback to return the result. ```js videoPlayer.prepare((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('prepare success!'); } else { console.info('prepare fail!'); @@ -803,7 +835,7 @@ Starts to play video resources. This API uses a callback to return the result. ```js videoPlayer.play((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('play success!'); } else { console.info('play fail!'); @@ -853,7 +885,7 @@ Pauses video playback. This API uses a callback to return the result. ```js videoPlayer.pause((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('pause success!'); } else { console.info('pause fail!'); @@ -903,7 +935,7 @@ Stops video playback. This API uses a callback to return the result. ```js videoPlayer.stop((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('stop success!'); } else { console.info('stop fail!'); @@ -953,7 +985,7 @@ Switches the video resource to be played. This API uses a callback to return the ```js videoPlayer.reset((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('reset success!'); } else { console.info('reset fail!'); @@ -1005,7 +1037,7 @@ Seeks to the specified playback position. The next key frame at the specified po ```js let seekTime = 5000; videoPlayer.seek(seekTime, (err, result) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('seek success!'); } else { console.info('seek fail!'); @@ -1036,7 +1068,7 @@ import media from '@ohos.multimedia.media' let seekTime = 5000; let seekMode = media.SeekMode.SEEK_NEXT_SYNC; videoPlayer.seek(seekTime, seekMode, (err, result) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('seek success!'); } else { console.info('seek fail!'); @@ -1102,7 +1134,7 @@ Sets the volume. This API uses a callback to return the result. ```js let vol = 0.5; videoPlayer.setVolume(vol, (err, result) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('setVolume success!'); } else { console.info('setVolume fail!'); @@ -1159,7 +1191,7 @@ Releases the video playback resource. This API uses a callback to return the res ```js videoPlayer.release((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('release success!'); } else { console.info('release fail!'); @@ -1217,7 +1249,7 @@ function printfDescription(obj) { } videoPlayer.getTrackDescription((error, arrlist) => { - if (typeof (arrlist) != 'undefined') { + if (arrlist) != null) { for (let i = 0; i < arrlist.length; i++) { printfDescription(arrlist[i]); } @@ -1254,7 +1286,7 @@ function printfDescription(obj) { let arrayDescription; videoPlayer.getTrackDescription().then((arrlist) => { - if (typeof (arrlist) != 'undefined') { + if (arrlist != null) { arrayDescription = arrlist; } else { console.log('video getTrackDescription fail'); @@ -1289,7 +1321,7 @@ import media from '@ohos.multimedia.media' let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X; videoPlayer.setSpeed(speed, (err, result) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('setSpeed success!'); } else { console.info('setSpeed fail!'); @@ -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 @@ -1350,7 +1382,7 @@ Selects a bit rate from available bit rates. This API uses a callback to return ```js let bitrate = 1024000; videoPlayer.selectBitrate(bitrate, (err, result) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('selectBitrate success!'); } else { console.info('selectBitrate fail!'); @@ -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 @@ -1597,7 +1640,7 @@ function printfItemDescription(obj, key) { } audioPlayer.getTrackDescription((error, arrlist) => { - if (typeof (arrlist) != 'undefined') { + if (arrlist != null) { for (let i = 0; i < arrlist.length; i++) { printfItemDescription(arrlist[i], MD_KEY_TRACK_TYPE); // Print the MD_KEY_TRACK_TYPE value of each track. } @@ -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 @@ -1953,7 +1996,7 @@ let eventEmitter = new events.EventEmitter(); eventEmitter.on('prepare', () => { videoRecorder.prepare(videoConfig, (err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('prepare success'); } else { console.info('prepare failed and error is ' + err.message); @@ -1962,7 +2005,7 @@ eventEmitter.on('prepare', () => { }); media.createVideoRecorder((err, recorder) => { - if (typeof (err) == 'undefined' && typeof (recorder) != 'undefined') { + if (err == null && recorder != null) { videoRecorder = recorder; console.info('createVideoRecorder success'); eventEmitter.emit('prepare'); // Trigger the 'prepare' event. @@ -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 @@ -2022,7 +2065,7 @@ let videoConfig = { // promise let videoRecorder = null; media.createVideoRecorder().then((recorder) => { - if (typeof (recorder) != 'undefined') { + if (recorder != null) { videoRecorder = recorder; console.info('createVideoRecorder success'); } else { @@ -2063,7 +2106,7 @@ This API can be called only after [prepare()](#videorecorder_prepare1) is called // asyncallback let surfaceID = null; // Surface ID passed to the external system. videoRecorder.getInputSurface((err, surfaceId) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('getInputSurface success'); surfaceID = surfaceId; } else { @@ -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 @@ -2124,7 +2167,7 @@ This API can be called only after [prepare()](#videorecorder_prepare1) and [getI ```js // asyncallback videoRecorder.start((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('start videorecorder success'); } else { console.info('start videorecorder failed and error is ' + err.message); @@ -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 @@ -2180,7 +2223,7 @@ This API can be called only after [start()](#videorecorder_start1) is called. Yo ```js // asyncallback videoRecorder.pause((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('pause videorecorder success'); } else { console.info('pause videorecorder failed and error is ' + err.message); @@ -2234,7 +2277,7 @@ Resumes video recording in asynchronous mode. This API uses a callback to return ```js // asyncallback videoRecorder.resume((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('resume videorecorder success'); } else { console.info('resume videorecorder failed and error is ' + err.message); @@ -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 @@ -2288,7 +2331,7 @@ To start another recording, you must call [prepare()](#videorecorder_prepare1) a ```js // asyncallback videoRecorder.stop((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('stop videorecorder success'); } else { console.info('stop videorecorder failed and error is ' + err.message); @@ -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 @@ -2342,7 +2385,7 @@ Releases the video recording resource in asynchronous mode. This API uses a call ```js // asyncallback videoRecorder.release((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('release videorecorder success'); } else { console.info('release videorecorder failed and error is ' + err.message); @@ -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 @@ -2396,7 +2439,7 @@ To start another recording, you must call [prepare()](#videorecorder_prepare1) a ```js // asyncallback videoRecorder.reset((err) => { - if (typeof (err) == 'undefined') { + if (err == null) { console.info('reset videorecorder success'); } else { console.info('reset videorecorder failed and error is ' + err.message); @@ -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-medialibrary.md b/en/application-dev/reference/apis/js-apis-medialibrary.md index b59e88a401cebca64a2be96b29de92dd375e893d..b66eeec85c124ac083b27859849a86e1a5f1d4c2 100644 --- a/en/application-dev/reference/apis/js-apis-medialibrary.md +++ b/en/application-dev/reference/apis/js-apis-medialibrary.md @@ -2280,7 +2280,7 @@ Describes options for fetching media files. | ----------------------- | ------------------- | ---- | ---- | ---- | ------------------------------------------------------------ | | selections | string | Yes | Yes | Yes | Conditions for fetching files. The enumerated values in [FileKey](#filekey8) are used as the column names of the conditions. Example:
selections: mediaLibrary.FileKey.MEDIA_TYPE + '= ? OR ' +mediaLibrary.FileKey.MEDIA_TYPE + '= ?', | | selectionArgs | Array<string> | Yes | Yes | Yes | Value of the condition, which corresponds to the value of the condition column in **selections**.
Example:
selectionArgs: [mediaLibrary.MediaType.IMAGE.toString(), mediaLibrary.MediaType.VIDEO.toString()], | -| order | string | Yes | Yes | No | Sorting mode of the search results, which can be ascending or descending. The enumerated values in [FileKey](#filekey8) are used as the columns for sorting the search results. Example:
Ascending: order: mediaLibrary.FileKey.DATE_ADDED + " AESC"
Descending: order: mediaLibrary.FileKey.DATE_ADDED + " DESC"| +| order | string | Yes | Yes | No | Sorting mode of the search results, which can be ascending or descending. The enumerated values in [FileKey](#filekey8) are used as the columns for sorting the search results. Example:
Ascending: order: mediaLibrary.FileKey.DATE_ADDED + " ASC"
Descending: order: mediaLibrary.FileKey.DATE_ADDED + " DESC" | | uri8+ | string | Yes | Yes | No | File URI. | | networkId8+ | string | Yes | Yes | No | Network ID of the registered device. | | extendArgs8+ | string | Yes | Yes | No | Extended parameters for fetching the files. Currently, no extended parameters are available. | 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 d4c99452483b63a9893905329d4fd1aae0be4505..c8a9d7cf699963e494c5f04c1d5e887e8795eb0f 100644 --- a/en/application-dev/reference/apis/js-apis-nfcController.md +++ b/en/application-dev/reference/apis/js-apis-nfcController.md @@ -1,9 +1,9 @@ # 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 8. 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 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## **Modules to Import** @@ -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 51731e95e192713e71add3304331475c11dd6629..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 8. 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 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-pointer.md b/en/application-dev/reference/apis/js-apis-pointer.md new file mode 100644 index 0000000000000000000000000000000000000000..97429f0dee1df4f12487cce5d361182ba660fe87 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-pointer.md @@ -0,0 +1,114 @@ +# Mouse Pointer + +The mouse pointer module provides APIs related to pointer attribute management. + +> **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 + +```js +import pointer from '@ohos.multimodalInput.pointer'; +``` + +## pointer.setPointerVisibele + +setPointerVisible(visible: boolean, callback: AsyncCallback<void>): void + +Sets the visible status of the mouse pointer. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MultimodalInput.Input.Pointer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ------------------------------------------------------------------- | +| visible | boolean | Yes | Whether the mouse pointer is visible. The value **true** indicates that the mouse pointer is visible, and the value **false** indicates the opposite.| +| callback | AysncCallback<void> | Yes | Callback used to return the result. | + +**Example** + +```js +pointer.setPointerVisible(true, (err, data) => { + if (err) { + console.log(`set pointer visible failed. err=${JSON.stringify(err)}`); + return; + } + console.log(`set pointer visible success.`); +); +``` + +## pointer.setPointerVisible + +setPointerVisible(visible: boolean): Promise<void> + +Sets the visible status of the mouse pointer. This API uses a promise to return the result. + +**System capability**: SystemCapability.MultimodalInput.Input.Pointer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | ------------------------------------------------------------------- | +| visible | boolean | Yes | Whether the mouse pointer is visible. The value **true** indicates that the mouse pointer is visible, and the value **false** indicates the opposite.| + +**Return value** + +| Parameter | Description | +| ------------------- | ------------------------------- | +| Promise<void> | Promise used to return the result.| + +**Example** + +```js +pointer.setPointerVisible(false).then( data => { + console.log(`set mouse pointer visible success`); + }, data => { + console.log(`set mouse pointer visible failed err=${JSON.stringify(data)}`); +}); +``` + +## pointer.isPointerVisible + +isPointerVisible(callback: AsyncCallback<boolean>): void + +Checks the visible status of the mouse pointer. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MultimodalInput.Input.Pointer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ---------------------------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.| + +**Example** + +```js +pointer.isPointerVisible((visible)=>{ + console.log("The mouse pointer visible attributes is " + visible); +}); +``` + +## pointer.isPointerVisible + +isPointerVisible(): Promise<boolean> + +Checks the visible status of the mouse pointer. This API uses a promise to return the result. + +**System capability**: SystemCapability.MultimodalInput.Input.Pointer + +**Return value** + +| Parameter | Description | +| ---------------------- | ------------------------------- | +| Promise<boolean> | Promise used to return the result.| + +**Example** + +```js +pointer.isPointerVisible().then( data => { + console.log(`isPointerThen success data=${JSON.stringify(data)}`); +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-radio.md b/en/application-dev/reference/apis/js-apis-radio.md index 5b371ea07267732eb69de7676cab7f6057954275..6e3ee3ab521fd77e73a8085002296cd6b5883430 100644 --- a/en/application-dev/reference/apis/js-apis-radio.md +++ b/en/application-dev/reference/apis/js-apis-radio.md @@ -899,9 +899,820 @@ 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)}`); +}); +``` + +## radio.getImsRegInfo9+ + +getImsRegInfo(slotId: number, imsType: ImsServiceType, callback: AsyncCallback): void + +Obtains the IMS registration status of the specified IMS service type. 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| +| imsType | [ImsServiceType](#imsservicetype9) | Yes | IMS service type. | +| callback | AsyncCallback<[ImsRegInfo](#imsreginfo9)\> | Yes | Callback used to return the result. | + +**Example** + +```js +radio.getImsRegInfo(0, 1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## radio.getImsRegInfo9+ + +getImsRegInfo(slotId: number, imsType: ImsServiceType): Promise + +Obtains the IMS registration status of the specified IMS service type. 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| +| imsType | [ImsServiceType](#imsservicetype9) | Yes | IMS service type. | + +**Return value** + +| Type | Description | +| ------------------------------------- | ----------------------- | +| Promise\<[ImsRegInfo](#imsreginfo9)\> | Promise used to return the result.| + +**Example** + +```js +let promise = radio.getImsRegInfo(0, 1); +promise.then(data => { + console.log(`getImsRegInfo success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getImsRegInfo fail, promise: err->${JSON.stringify(err)}`); +}); +``` + +## radio.on('imsRegStateChange')9+ + +on(type: 'imsRegStateChange', slotId: number, imsType: ImsServiceType, callback: Callback): void + +Enables listening for **imsRegStateChange** events. 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 | +| -------- | ------------------------------------ | ---- | -------------------------------------- | +| type | string | Yes | IMS registration status changes. | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| imsType | [ImsServiceType](#imsservicetype9) | Yes | IMS service type. | +| callback | Callback<[ImsRegInfo](#imsreginfo9)> | Yes | Callback used to return the result. | + +**Example** + +```js +radio.on('imsRegStateChange', 0, 1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + +## radio.off('imsRegStateChange')9+ + +off(type: 'imsRegStateChange', slotId: number, imsType: ImsServiceType, callback?: Callback): void + +Disables listening for **imsRegStateChange** events. 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 | +| -------- | ------------------------------------ | ---- | -------------------------------------- | +| type | string | Yes | IMS registration status changes. | +| slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| +| imsType | [ImsServiceType](#imsservicetype9) | Yes | IMS service type. | +| callback | Callback<[ImsRegInfo](#imsreginfo9)> | No | Callback used to return the result. | + +**Example** + +```js +radio.off('imsRegStateChange', 0, 1, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + ## RadioTechnology -Enumerates the RAT. +Enumerates radio access technologies. **System capability**: SystemCapability.Telephony.CoreService @@ -1010,3 +1821,296 @@ 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](#cdmacellinformation8) \| [GsmCellInformation](#gsmcellinformation8) \| [LteCellInformation](#ltecellinformation8) \| [NrCellInformation](#nrcellinformation8) \| [TdscdmaCellInformation](#tdscdmacellinformation8) | 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. + +This is a system API. + +**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. | + +## ImsRegState9+ + +Enumerates IMS registration states. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| ---------------- | ---- | -------- | +| IMS_UNREGISTERED | 0 | Not registered.| +| IMS_REGISTERED | 1 | Registered.| + +## ImsRegTech9+ + +Enumerates IMS registration technologies. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| ----------------------- | ---- | --------------- | +| REGISTRATION_TECH_NONE | 0 | None. | +| REGISTRATION_TECH_LTE | 1 | LTE. | +| REGISTRATION_TECH_IWLAN | 2 | I-WLAN.| +| REGISTRATION_TECH_NR | 3 | NR. | + +## ImsRegInfo9+ + +Defines the IMS registration information. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Type | Description | +| ----------- | ---------------------------- | ------------- | +| imsRegState | [ImsRegState](#imsregstate9) | IMS registration state.| +| imsRegTech | [ImsRegTech](#imsregtech9) | IMS registration technology.| + +## ImsServiceType9+ + +Enumerates IMS service types. + +This is a system API. + +**System capability**: SystemCapability.Telephony.CoreService + +| Name | Value | Description | +| ---------- | ---- | ---------- | +| TYPE_VOICE | 0 | Voice service.| +| TYPE_VIDEO | 1 | Video service.| +| TYPE_UT | 2 | UT service. | +| TYPE_SMS | 3 | SMS service.| diff --git a/en/application-dev/reference/apis/js-apis-request.md b/en/application-dev/reference/apis/js-apis-request.md index 4f6da3208d7bef31f14e626a8fc09c57b5cb0423..272b2f8e21fe21adf0fac3fea2e1ea02c6581e96 100644 --- a/en/application-dev/reference/apis/js-apis-request.md +++ b/en/application-dev/reference/apis/js-apis-request.md @@ -465,6 +465,7 @@ Removes this upload task. This API uses an asynchronous callback to return the r **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | name | string | Yes| Name of a form element.| diff --git a/en/application-dev/reference/apis/js-apis-router.md b/en/application-dev/reference/apis/js-apis-router.md index ac9435450c7e47d70deb11ed0a5b7249eea8f368..5fd946a50a96ae6ba4086934c749d05f89e5362e 100644 --- a/en/application-dev/reference/apis/js-apis-router.md +++ b/en/application-dev/reference/apis/js-apis-router.md @@ -5,7 +5,7 @@ The **Router** module provides APIs to access pages through URLs. You can use th > **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. -> +> > - Page routing APIs can be invoked only after page rendering is complete. Do not call these APIs in **onInit** and **onReady** when the page is still in the rendering phase. ## Modules to Import @@ -23,9 +23,9 @@ Navigates to a specified page in the application. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** -| Name | Type | Mandatory| Description | -| ------- | ------------------------------- | ---- | ------------------ | -| options | [RouterOptions](#routeroptions) | Yes | Page routing parameters.| +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | --------- | +| options | [RouterOptions](#routeroptions) | Yes | Page routing parameters.| **Example** @@ -49,10 +49,10 @@ Navigates to a specified page in the application. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** -| Name | Type | Mandatory| Description | -| ----------------- | ------------------------------- | ---- | -------------------- | -| options | [RouterOptions](#routeroptions) | Yes | Page routing parameters. | -| mode9+ | [RouterMode](#routermode9) | Yes | Routing mode.| +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [RouterOptions](#routeroptions) | Yes | Page routing parameters. | +| mode | [RouterMode](#routermode9) | Yes | Routing mode.| **Example** @@ -77,6 +77,7 @@ Replaces the current page with another one in the application and destroys the c **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** + | Name | Type | Mandatory| Description | | ------- | ------------------------------- | ---- | ------------------ | | options | [RouterOptions](#routeroptions) | Yes | Description of the new page.| @@ -101,10 +102,10 @@ Replaces the current page with another one in the application and destroys the c **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** -| Name | Type | Mandatory| Description | -| ----------------- | ------------------------------- | ---- | -------------------- | -| options | [RouterOptions](#routeroptions) | Yes | Description of the new page. | -| mode9+ | [RouterMode](#routermode9) | Yes | Routing mode.| +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [RouterOptions](#routeroptions) | Yes | Description of the new page. | +| mode | [RouterMode](#routermode9) | Yes | Routing mode.| **Example** @@ -128,7 +129,7 @@ Returns to the previous page or a specified page. **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------------------- | ---- | ------------------------------------------------------------ | -| options | [RouterOptions](#routeroptions) | No | Description of the page. The **url** parameter indicates the URL of the page to return to. If the specified page does not exist in the page stack, the application does not respond. If this parameter is not set, the application returns to the previous page.| +| options | [RouterOptions](#routeroptions) | No | Description of the page. The **url** parameter indicates the URL of the page to return to. If the specified page does not exist in the page stack, the application does not respond. If no URL is set, the previous page is returned, and the page in the page stack is not reclaimed. It will be reclaimed after being popped up.| **Example** @@ -159,8 +160,8 @@ Obtains the number of pages in the current stack. **System capability**: SystemCapability.ArkUI.ArkUI.Full **Return value** -| Type | Description | -| ------ | ---------------------------------- | +| Type | Description | +| ------ | ------------------ | | string | Number of pages in the stack. The maximum value is **32**.| **Example** @@ -179,8 +180,8 @@ Obtains state information about the current page. **Return value** -| Type | Description | -| --------------------------- | -------------- | +| Type | Description | +| --------------------------- | ------- | | [RouterState](#routerstate) | Page routing state.| **Example** @@ -197,11 +198,11 @@ Describes the page routing state. **System capability**: SystemCapability.ArkUI.ArkUI.Full -| Name | Type | Description | -| ----- | ------ | ------------------------------------------------------------ | +| Name | Type | Description | +| ----- | ------ | ---------------------------------- | | index | number | Index of the current page in the stack. The index starts from 1 from the bottom to the top of the stack.| -| name | string | Name of the current page, that is, the file name. | -| path | string | Path of the current page. | +| name | string | Name of the current page, that is, the file name. | +| path | string | Path of the current page. | ## router.enableAlertBeforeBackPage @@ -212,9 +213,9 @@ Enables the display of a confirm dialog box before returning to the previous pag **System capability**: SystemCapability.ArkUI.ArkUI.Full **Parameters** -| Name | Type | Mandatory| Description | -| ------- | ----------------------------------------- | ---- | ------------------ | -| options | [EnableAlertOptions](#enablealertoptions) | Yes | Description of the dialog box.| +| Name | Type | Mandatory | Description | +| ------- | ---------------------------------------- | ---- | --------- | +| options | [EnableAlertOptions](#enablealertoptions) | Yes | Description of the dialog box.| **Example** @@ -229,9 +230,9 @@ Describes the confirm dialog box. **System capability**: SystemCapability.ArkUI.ArkUI.Full -| Name | Type | Mandatory| Description | -| ------- | ------ | ---- | ---------------- | -| message | string | Yes | Content displayed in the confirm dialog box.| +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | -------- | +| message | string | Yes | Content displayed in the confirm dialog box.| ## router.disableAlertBeforeBackPage @@ -256,8 +257,8 @@ Obtains the parameters passed from the page that initiates redirection to the cu **Return value** -| Type | Description | -| ------ | ---------------------------------- | +| Type | Description | +| ------ | ----------------- | | Object | Parameters passed from the page that initiates redirection to the current page.| **Example** @@ -272,14 +273,13 @@ Describes the page routing options. **System capability**: SystemCapability.ArkUI.ArkUI.Lite -| Name | Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------------------------------------------------ | -| url | string | Yes | URI of the destination page, in either of the following formats:
- Absolute path of the page. The value is available in the pages list in the **config.json** file, for example:
- pages/index/index
- pages/detail/detail
- Particular path. If the URI is a slash (/), the home page is displayed. | -| params | Object | No | Data that needs to be passed to the destination page during redirection. After the destination page is displayed, it can use the passed data, for example, **this.data1** (**data1** is a key in **params**). If there is the same key (for example, **data1**) on the destination page, the passed **data1** value will replace the original value on the destination page.| +| Name | Type | Mandatory | Description | +| ------ | ------ | ---- | ---------------------------------------- | +| url | string | Yes | URI of the destination page, in either of the following formats:
- Absolute path of the page. The value is available in the pages list in the **config.json** file, for example:
- pages/index/index
- pages/detail/detail
- Particular path. If the URI is a slash (/), the home page is displayed.| +| params | Object | No | Data that needs to be passed to the destination page during redirection. After the destination page is displayed, it can use the passed data, for example, **this.data1** (**data1** is a key in **params**). If there is the same key (for example, **data1**) on the destination page, the passed **data1** value will replace the original value on the destination page.| > **NOTE** - > > The page routing stack supports a maximum of 32 pages. ## RouterMode9+ @@ -288,9 +288,9 @@ Enumerates the routing modes. **System capability**: SystemCapability.ArkUI.ArkUI.Full -| Name | Description | -| -------- | ------------------------------------------------------------ | -| Standard | Standard mode. | +| Name | Description | +| -------- | ---------------------------------------- | +| Standard | Standard mode. | | Single | Singleton mode.
If the URL of the target page already exists in the page stack, the page closest to the top of the stack is moved as a new page to the top of the stack.
If the URL of the target page does not exist in the page stack, the page is redirected to in standard mode.| ## Examples 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..681e5cdc6ac3dea7924feb25752e017052bef23e 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 => { @@ -1478,7 +1482,7 @@ promise.then(data => { ## sim.**unlockPin**28+ -****unlockPin2****(slotId: number,pin2: string ,callback: AsyncCallback): void +unlockPin2(slotId: number,pin2: string ,callback: AsyncCallback): void Unlocks PIN 2 of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. @@ -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** @@ -1545,7 +1549,7 @@ promise.then(data => { ## sim.**unlockPuk**28+ -unlockPuk2(slotId: number,newPin2: string,puk2: string ,callback: AsyncCallback): void +unlockPuk2(slotId: number, newPin2: string, puk2: string, callback: AsyncCallback): void Unlocks PUK 2 of the SIM card in the specified slot. This API uses an asynchronous callback to return the result. @@ -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)}`); }); ``` @@ -1577,7 +1581,7 @@ sim.unlockPuk2(0, newPin2,puk2,(err, data) => { ## sim.**unlockPuk2**8+ -unlockPuk2slotId: number,newPin2: string,puk2: string): Promise<LockStatusResponse\> +unlockPuk2(slotId: number, newPin2: string, puk2: string): Promise<LockStatusResponse\> Unlocks PUK 2 of the SIM card in the specified slot. This API uses a promise to return the result. @@ -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..9039fb774527e9ed6bbd43c95b0996afdc94780d 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](#simshortmessage7)\>> | 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](#cbconfigoptions7) | 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](#cbconfigoptions7) | 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 | | Yes | Callback used to return the result. | + +**Example** + +```js +let slotId = 0; +sms.getSmsSegmentsInfo(slotId, "message", false, (err, data) => { + 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 used to return the result.| + +**Example** + +```js +let slotId = 0; +let promise = sms.getSmsSegmentsInfo(slotId, "message", false); +promise.then(data => + 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,441 @@ 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.| + + +## MmsReadRecInd8+ + +Defines the 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 | Destination. | +| from | [MmsAddress](#mmsaddress8) | Yes | Source. | +| readStatus | number | Yes | Read state.| +| date | number | No | Date. | + + +## 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 | + +## CBConfigOptions7+ + +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.| + +## SimShortMessage7+ + +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-system-router.md b/en/application-dev/reference/apis/js-apis-system-router.md index 0f1f932efe54af1337ce19354d19343b6f637687..a35aa162b0b7eb57c3535f821b74a15d4cb58d9f 100644 --- a/en/application-dev/reference/apis/js-apis-system-router.md +++ b/en/application-dev/reference/apis/js-apis-system-router.md @@ -1,5 +1,7 @@ # Page Routing +The **Router** module provides APIs to access pages through URIs. + > **NOTE** > > - The APIs of this module are no longer maintained since API version 8. You are advised to use [`@ohos.router`](js-apis-router.md) instead. @@ -372,12 +374,12 @@ Defines the **EnableAlertBeforeBackPage** parameters. **System capability**: SystemCapability.ArkUI.ArkUI.Full -| Name | Type | Mandatory | Description | -| -------- | ------------------------ | ---- | ------------------------- | -| message | string | Yes | Content displayed in the confirm dialog box. | -| success | (errMsg: string) => void | No | Called when a dialog box is displayed. **errMsg** indicates the returned information. | -| fail | (errMsg: string) => void | No | Called when the API fails to be called. **errMsg** indicates the returned information.| -| complete | () => void | No | Called when the API call is complete. | +| Name | Type | Mandatory| Description | +| -------- | ------------------------ | ---- | -------------------------------------------------- | +| message | string | Yes | Content displayed in the confirm dialog box. | +| success | (errMsg: string) => void | No | Called when the **OK** button in the confirm dialog box is clicked. **errMsg** indicates the returned information.| +| cancel | (errMsg: string) => void | No | Called when the **Cancel** button in the confirm dialog box is clicked. **errMsg** indicates the returned information.| +| complete | () => void | No | Called when the API call is complete. | ## DisableAlertBeforeBackPageOptions6+ @@ -385,11 +387,11 @@ Define the **DisableAlertBeforeBackPage** parameters. **System capability**: SystemCapability.ArkUI.ArkUI.Full -| Name | Type | Mandatory | Description | -| -------- | ------------------------ | ---- | ------------------------- | -| success | (errMsg: string) => void | No | Called when a dialog box is displayed. **errMsg** indicates the returned information. | -| fail | (errMsg: string) => void | No | Called when the API fails to be called. **errMsg** indicates the returned information.| -| complete | () => void | No | Called when the API call is complete. | +| Name | Type | Mandatory| Description | +| -------- | ------------------------ | ---- | -------------------------------------------------- | +| success | (errMsg: string) => void | No | Called when the dialog box is closed. **errMsg** indicates the returned information.| +| cancel | (errMsg: string) => void | No | Called when the dialog box fails to be closed. **errMsg** indicates the returned information.| +| complete | () => void | No | Called when the API call is complete. | ## ParamsInterface 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-update.md b/en/application-dev/reference/apis/js-apis-update.md index 64d76026eeb3981fd589401d71f599fc2112f9dd..1cad2b9d5796f5039d62124ff9543c77d7dc48f1 100644 --- a/en/application-dev/reference/apis/js-apis-update.md +++ b/en/application-dev/reference/apis/js-apis-update.md @@ -7,7 +7,7 @@ There are two types of updates: SD card update and over the air (OTA) update. - The SD card update depends on the update packages and SD cards. - The OTA update depends on the server deployed by the device manufacturer for managing update packages. The OTA server IP address is passed by the caller. The request interface is fixed and developed by the device manufacturer. -> **NOTE** +> **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. > @@ -29,9 +29,9 @@ Obtains an **OnlineUpdater** object. **Parameters** -| Name | Type | Mandatory | Description | -| ----------- | --------------------------- | ---- | ---- | -| upgradeInfo | [UpgradeInfo](#upgradeinfo) | Yes | **UpgradeInfo** object.| +| Name | Type | Mandatory | Description | +| ----------- | --------------------------- | ---- | ------ | +| upgradeInfo | [UpgradeInfo](#upgradeinfo) | Yes | **UpgradeInfo** object.| **Return value** @@ -41,7 +41,7 @@ Obtains an **OnlineUpdater** object. **Example** -``` +```ts try { var upgradeInfo = { upgradeApp: "com.ohos.ota.updateclient", @@ -67,13 +67,13 @@ Obtains a **Restorer** object for restoring factory settings. **Return value** -| Type | Description | -| ------------------- | ---- | +| Type | Description | +| --------------------- | ------ | | [Restorer](#restorer) | **Restorer** object for restoring factory settings.| **Example** -``` +```ts try { let restorer = update.getRestorer(); } catch(error) { @@ -91,13 +91,13 @@ Obtains a **LocalUpdater** object. **Return value** -| Type | Description | -| ------------------- | ---- | +| Type | Description | +| ----------------------------- | ------ | | [LocalUpdater](#localupdater) | **LocalUpdater** object.| **Example** -``` +```ts try { let localUpdater = update.getLocalUpdater(); } catch(error) { @@ -119,13 +119,13 @@ Checks whether a new version is available. This API uses an asynchronous callbac **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | -------------- | | callback | AsyncCallback\<[CheckResult](#checkresult)> | Yes | Callback used to return the result.| **Example** -``` +```ts updater.checkNewVersion((err, result) => { console.log(`checkNewVersion isExistNewVersion ${result?.isExistNewVersion}`); }); @@ -143,13 +143,13 @@ Checks whether a new version is available. This API uses a promise to return the **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| ------------------------------------- | ------------------- | | Promise\<[CheckResult](#checkresult)> | Promise used to return the result.| **Example** -``` +```ts updater.checkNewVersion().then(result => { console.log(`checkNewVersion isExistNewVersion: ${result.isExistNewVersion}`); // Version digest information @@ -171,13 +171,13 @@ Obtains information about the new version. This API uses an asynchronous callbac **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------------- | | callback | AsyncCallback\<[NewVersionInfo](#newversioninfo)> | Yes | Callback used to return the result.| **Example** -``` +```ts updater.getNewVersionInfo((err, info) => { console.log(`info displayVersion = ${info?.versionComponents[0].displayVersion}`); console.log(`info innerVersion = ${info?.versionComponents[0].innerVersion}`); @@ -196,13 +196,13 @@ Obtains information about the new version. This API uses a promise to return the **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| ---------------------------------------- | -------------------- | | Promise\<[NewVersionInfo](#newversioninfo)> | Promise used to return the result.| **Example** -``` +```ts updater.getNewVersionInfo().then(info => { console.log(`info displayVersion = ${info.versionComponents[0].displayVersion}`); console.log(`info innerVersion = ${info.versionComponents[0].innerVersion}`); @@ -223,15 +223,15 @@ Obtains the description file of the new version. This API uses an asynchronous c **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| -| descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file.| -| callback | AsyncCallback\>) | Yes | Callback used to return the result.| +| Name | Type | Mandatory | Description | +| ------------------ | ---------------------------------------- | ---- | -------------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | +| descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file. | +| callback | AsyncCallback\>) | Yes | Callback used to return the result.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -261,20 +261,20 @@ Obtains the description file of the new version. This API uses a promise to retu **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| Name | Type | Mandatory | Description | +| ------------------ | ---------------------------------------- | ---- | ------ | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| | descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file.| **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| ---------------------------------------- | ------------------- | | Promise\> | Promise used to return the result.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -305,13 +305,13 @@ Obtains information about the current version. This API uses an asynchronous cal **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ---------------- | | callback | AsyncCallback\<[CurrentVersionInfo](#currentversioninfo)> | Yes | Callback used to return the result.| **Example** -``` +```ts updater.getCurrentVersionInfo((err, info) => { console.log(`info osVersion = ${info?.osVersion}`); console.log(`info deviceName = ${info?.deviceName}`); @@ -331,13 +331,13 @@ Obtains information about the current version. This API uses a promise to return **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| ---------------------------------------- | ------------------- | | Promise\<[CurrentVersionInfo](#currentversioninfo)> | Promise used to return the result.| **Example** -``` +```ts updater.getCurrentVersionInfo().then(info => { console.log(`info osVersion = ${info.osVersion}`); console.log(`info deviceName = ${info.deviceName}`); @@ -359,14 +359,14 @@ Obtains the description file of the current version. This API uses an asynchrono **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file.| -| callback | AsyncCallback\>) | Yes | Callback used to return the result.| +| Name | Type | Mandatory | Description | +| ------------------ | ---------------------------------------- | ---- | --------------- | +| descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file. | +| callback | AsyncCallback\>) | Yes | Callback used to return the result.| **Example** -``` +```ts // Options of the description file var descriptionOptions = { format: DescriptionFormat.STANDARD, // Standard format @@ -391,19 +391,19 @@ Obtains the description file of the current version. This API uses a promise to **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | +| Name | Type | Mandatory | Description | +| ------------------ | ---------------------------------------- | ---- | ------ | | descriptionOptions | [DescriptionOptions](#descriptionoptions) | Yes | Options of the description file.| **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| ---------------------------------------- | -------------------- | | Promise\> | Promise used to return the result.| **Example** -``` +```ts // Options of the description file var descriptionOptions = { format: DescriptionFormat.STANDARD, // Standard format @@ -429,13 +429,13 @@ Obtains information about the update task. This API uses an asynchronous callbac **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | +| Name | Type | Mandatory | Description | +| -------- | ------------------------------------- | ---- | ---------------- | | callback | AsyncCallback\<[TaskInfo](#taskinfo)> | Yes | Callback used to return the result.| **Example** -``` +```ts updater.getTaskInfo((err, info) => { console.log(`getTaskInfo isexistTask= ${info?.existTask}`); }); @@ -453,13 +453,13 @@ Obtains information about the update task. This API uses a promise to return the **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| ------------------------------- | ------------------- | | Promise\<[TaskInfo](#taskinfo)> | Promise used to return the result.| **Example** -``` +```ts updater.getTaskInfo().then(info => { console.log(`getTaskInfo isexistTask= ${info.existTask}`); }).catch(err => { @@ -479,15 +479,15 @@ Downloads the new version. This API uses an asynchronous callback to return the **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| -| downloadOptions | [DownloadOptions](#downloadoptions) | Yes | Download options.| -| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| +| Name | Type | Mandatory | Description | +| ----------------- | --------------------------------------- | ---- | ---------------------------------- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | +| downloadOptions | [DownloadOptions](#downloadoptions) | Yes | Download options. | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -515,20 +515,20 @@ Downloads the new version. This API uses a promise to return the result. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | +| Name | Type | Mandatory | Description | +| ----------------- | --------------------------------------- | ---- | ------ | | versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| -| downloadOptions | [DownloadOptions](#downloadoptions) | Yes | Download options.| +| downloadOptions | [DownloadOptions](#downloadoptions) | Yes | Download options. | **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| -------------- | -------------------------- | | Promise\ | Promise that returns no value.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -558,15 +558,15 @@ Resumes download of the new version. This API uses an asynchronous callback to r **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| -| resumeDownloadOptions | [ResumeDownloadOptions](#resumedownloadoptions) | Yes | Options for resuming download.| -| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| +| Name | Type | Mandatory | Description | +| --------------------- | ---------------------------------------- | ---- | ------------------------------------ | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | +| resumeDownloadOptions | [ResumeDownloadOptions](#resumedownloadoptions) | Yes | Options for resuming download. | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -593,20 +593,20 @@ Resumes download of the new version. This API uses a promise to return the resul **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| Name | Type | Mandatory | Description | +| --------------------- | ---------------------------------------- | ---- | ------ | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| | resumeDownloadOptions | [ResumeDownloadOptions](#resumedownloadoptions) | Yes | Options for resuming download.| **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| -------------- | -------------------------- | | Promise\ | Promise that returns no value.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -635,15 +635,15 @@ Pauses download of the new version. This API uses an asynchronous callback to re **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| -| pauseDownloadOptions | [PauseDownloadOptions](#pausedownloadoptions) | Yes | Options for pausing download.| -| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| +| Name | Type | Mandatory | Description | +| -------------------- | ---------------------------------------- | ---- | ------------------------------------ | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | +| pauseDownloadOptions | [PauseDownloadOptions](#pausedownloadoptions) | Yes | Options for pausing download. | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -670,20 +670,20 @@ Resumes download of the new version. This API uses a promise to return the resul **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| Name | Type | Mandatory | Description | +| -------------------- | ---------------------------------------- | ---- | ------ | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| | pauseDownloadOptions | [PauseDownloadOptions](#pausedownloadoptions) | Yes | Options for pausing download.| **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| -------------- | -------------------------- | | Promise\ | Promise that returns no value.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -712,15 +712,15 @@ Updates the version. This API uses an asynchronous callback to return the result **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| -| upgradeOptions | [UpgradeOptions](#upgradeoptions) | Yes | Update options.| -| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| +| Name | Type | Mandatory | Description | +| ----------------- | --------------------------------------- | ---- | ------------------------------------ | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | +| upgradeOptions | [UpgradeOptions](#upgradeoptions) | Yes | Update options. | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -747,20 +747,20 @@ Updates the version. This API uses a promise to return the result. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | +| Name | Type | Mandatory | Description | +| ----------------- | --------------------------------------- | ---- | ------ | | versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| -| upgradeOptions | [UpgradeOptions](#upgradeoptions) | Yes | Update options.| +| upgradeOptions | [UpgradeOptions](#upgradeoptions) | Yes | Update options. | **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| -------------- | -------------------------- | | Promise\ | Promise that returns no value.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -789,15 +789,15 @@ Clears errors. This API uses an asynchronous callback to return the result. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| -| clearOptions | [ClearOptions](#clearoptions) | Yes | Clear options.| -| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| +| Name | Type | Mandatory | Description | +| ----------------- | --------------------------------------- | ---- | ------------------------------------ | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | +| clearOptions | [ClearOptions](#clearoptions) | Yes | Clear options. | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -824,20 +824,20 @@ Clears errors. This API uses a promise to return the result. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | +| Name | Type | Mandatory | Description | +| ----------------- | --------------------------------------- | ---- | ------ | | versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| -| clearOptions | [ClearOptions](#clearoptions) | Yes | Update options.| +| clearOptions | [ClearOptions](#clearoptions) | Yes | Update options. | **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| -------------- | -------------------------- | | Promise\ | Promise that returns no value.| **Example** -``` +```ts // Version digest information var versionDigestInfo = { versionDigest: "versionDigest" // Version digest information in the check result @@ -866,13 +866,13 @@ Obtains the update policy. This API uses an asynchronous callback to return the **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | ---------- | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------------- | | callback | AsyncCallback\<[UpgradePolicy](#upgradepolicy)> | Yes | Callback used to return the result.| **Example** -``` +```ts updater.getUpgradePolicy((err, policy) => { console.log(`policy downloadStrategy = ${policy?.downloadStrategy}`); console.log(`policy autoUpgradeStrategy = ${policy?.autoUpgradeStrategy}`); @@ -891,13 +891,13 @@ Obtains the update policy. This API uses a promise to return the result. **Return value** -| Type | Description | -| --------------------------------------- | ----------------- | +| Type | Description | +| ---------------------------------------- | --------------------- | | Promise\<[UpgradePolicy](#upgradepolicy)> | Promise used to return the result.| **Example** -``` +```ts updater.getUpgradePolicy().then(policy => { console.log(`policy downloadStrategy = ${policy.downloadStrategy}`); console.log(`policy autoUpgradeStrategy = ${policy.autoUpgradeStrategy}`); @@ -918,14 +918,14 @@ Sets the update policy. This API uses an asynchronous callback to return the res **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | ---------- | -| policy | [UpgradePolicy](#upgradepolicy) | Yes | Update policy.| -| callback | AsyncCallback\ | Yes | Callback used to return the result.| +| Name | Type | Mandatory | Description | +| -------- | ------------------------------- | ---- | ------------- | +| policy | [UpgradePolicy](#upgradepolicy) | Yes | Update policy. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| **Example** -``` +```ts let policy = { downloadStrategy: false, autoUpgradeStrategy: false, @@ -948,19 +948,19 @@ Sets the update policy. This API uses a promise to return the result. **Parameters** -| Name | Type | Mandatory | Description | -| ------ | ----------------------------- | ---- | ------ | +| Name | Type | Mandatory | Description | +| ------ | ------------------------------- | ---- | ---- | | policy | [UpgradePolicy](#upgradepolicy) | Yes | Update policy.| **Return value** -| Type | Description | -| ---------------- | --------------- | +| Type | Description | +| -------------- | ------------------- | | Promise\ | Promise used to return the result.| **Example** -``` +```ts let policy = { downloadStrategy: false, autoUpgradeStrategy: false, @@ -985,13 +985,13 @@ Terminates the update. This API uses an asynchronous callback to return the resu **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| +| Name | Type | Mandatory | Description | +| -------- | -------------------- | ---- | -------------------------------------- | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** -``` +```ts updater.terminateUpgrade((err) => { console.log(`terminateUpgrade error ${JSON.stringify(err)}`); }); @@ -1009,13 +1009,13 @@ Terminates the update. This API uses a promise to return the result. **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| -------------- | -------------------------- | | Promise\ | Promise that returns no value.| **Example** -``` +```ts updater.terminateUpgrade().then(() => { console.log(`terminateUpgrade success`); }).catch(err => { @@ -1033,14 +1033,14 @@ Enables listening for update events. This API uses an asynchronous callback to r **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| -| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | Yes | Event callback.| +| Name | Type | Mandatory | Description | +| ----------------- | ---------------------------------------- | ---- | ---- | +| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| +| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | Yes | Event callback.| **Example** -``` +```ts var eventClassifyInfo = { eventClassify: update.EventClassify.TASK, // Listening for update events extraInfo: "" @@ -1060,14 +1060,14 @@ Disables listening for update events. This API uses an asynchronous callback to **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| -| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | No | Event callback.| +| Name | Type | Mandatory | Description | +| ----------------- | ---------------------------------------- | ---- | ---- | +| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| +| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | No | Event callback.| **Example** -``` +```ts var eventClassifyInfo = { eventClassify: update.EventClassify.TASK, // Listening for update events extraInfo: "" @@ -1084,7 +1084,7 @@ updater.off(eventClassifyInfo, (eventInfo) => { factoryReset(callback: AsyncCallback\): void -Restores factory settings. This API uses an asynchronous callback to return the result. +Restore the device to its factory settings. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Update.UpdateService @@ -1092,13 +1092,13 @@ Restores factory settings. This API uses an asynchronous callback to return the **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| +| Name | Type | Mandatory | Description | +| -------- | -------------------- | ---- | -------------------------------------- | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** -``` +```ts restorer.factoryReset((err) => { console.log(`factoryReset error ${JSON.stringify(err)}`); }); @@ -1108,7 +1108,7 @@ restorer.factoryReset((err) => { factoryReset(): Promise\ -Restores factory settings. This API uses a promise to return the result. +Restore the device to its factory settings. This API uses a promise to return the result. **System capability**: SystemCapability.Update.UpdateService @@ -1116,13 +1116,13 @@ Restores factory settings. This API uses a promise to return the result. **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| -------------- | -------------------------- | | Promise\ | Promise that returns no value.| **Example** -``` +```ts restorer.factoryReset().then(() => { console.log(`factoryReset success`); }).catch(err => { @@ -1144,15 +1144,15 @@ Verifies the update package. This API uses an asynchronous callback to return th **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| upgradeFile | [UpgradeFile](#upgradefile) | Yes | Update file.| -| certsFile | string | Yes | Path of the certificate file.| -| callback | AsyncCallback\ | Yes | Callback used to return the result.| +| Name | Type | Mandatory | Description | +| ----------- | --------------------------- | ---- | ---------------- | +| upgradeFile | [UpgradeFile](#upgradefile) | Yes | Update file. | +| certsFile | string | Yes | Path of the certificate file. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| **Example** -``` +```ts var upgradeFile = { fileType: update.ComponentType.OTA, // OTA package filePath: "path" // Path of the local update package @@ -1175,20 +1175,20 @@ Verifies the update package. This API uses a promise to return the result. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| upgradeFile | [UpgradeFile](#upgradefile) | Yes | Update file.| -| certsFile | string | Yes | Path of the certificate file.| +| Name | Type | Mandatory | Description | +| ----------- | --------------------------- | ---- | ------ | +| upgradeFile | [UpgradeFile](#upgradefile) | Yes | Update file. | +| certsFile | string | Yes | Path of the certificate file.| **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| -------------- | ---------------------- | | Promise\ | Promise used to return the result.| **Example** -``` +```ts var upgradeFile = { fileType: update.ComponentType.OTA, // OTA package filePath: "path" // Path of the local update package @@ -1211,14 +1211,14 @@ Installs the update package. This API uses an asynchronous callback to return th **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| upgradeFile | Array<[UpgradeFile](#upgradefile)> | Yes | Update file.| -| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------- | ---- | --------------------------------------- | +| upgradeFile | Array<[UpgradeFile](#upgradefile)> | Yes | Update file. | +| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the operation is successful, `err` is `undefined`; otherwise, `err` is an `Error` object.| **Example** -``` +```ts var upgradeFiles = [{ fileType: update.ComponentType.OTA, // OTA package filePath: "path" // Path of the local update package @@ -1241,13 +1241,13 @@ Installs the update package. This API uses a promise to return the result. **Return value** -| Type | Description | -| ---------------------------------------- | ---------------- | +| Type | Description | +| -------------- | -------------------------- | | Promise\ | Promise that returns no value.| **Example** -``` +```ts var upgradeFiles = [{ fileType: update.ComponentType.OTA, // OTA package filePath: "path" // Path of the local update package @@ -1268,14 +1268,14 @@ Enables listening for update events. This API uses an asynchronous callback to r **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| -| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | Yes | Event callback.| +| Name | Type | Mandatory | Description | +| ----------------- | ---------------------------------------- | ---- | ---- | +| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| +| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | Yes | Event callback.| **Example** -``` +```ts var eventClassifyInfo = { eventClassify: update.EventClassify.TASK, // Listening for update events extraInfo: "" @@ -1297,14 +1297,14 @@ Disables listening for update events. This API uses an asynchronous callback to **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | --------- | -| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| -| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | Yes | Event callback.| +| Name | Type | Mandatory | Description | +| ----------------- | ---------------------------------------- | ---- | ---- | +| eventClassifyInfo | [EventClassifyInfo](#eventclassifyinfo) | Yes | Event information.| +| taskCallback | [UpgradeTaskCallback](#upgradetaskcallback) | Yes | Event callback.| **Example** -``` +```ts var eventClassifyInfo = { eventClassify: update.EventClassify.TASK, // Listening for update events extraInfo: "" @@ -1323,10 +1323,10 @@ Represents update information. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| upgradeApp | string | Yes | Application package name. | -| businessType | [BusinessType](#businesstype) | Yes | Update service type. | +| Name | Type | Mandatory | Description | +| ------------ | ----------------------------- | ---- | ------ | +| upgradeApp | string | Yes | Application package name. | +| businessType | [BusinessType](#businesstype) | Yes | Update service type.| ## BusinessType @@ -1334,10 +1334,10 @@ Enumerates update service types. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| vendor | [BusinessVendor](#businessvendor) | Yes | Application vendor. | -| subType | [BusinessSubType](#businesssubtype) | Yes | Update service sub-type. | +| Name | Type | Mandatory | Description | +| ------- | ----------------------------------- | ---- | ---- | +| vendor | [BusinessVendor](#businessvendor) | Yes | Application vendor. | +| subType | [BusinessSubType](#businesssubtype) | Yes | Type | ## CheckResult @@ -1345,10 +1345,10 @@ Represents the package check result. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| isExistNewVersion | bool | Yes | Whether a new version is available. | -| newVersionInfo | [NewVersionInfo](#newversioninfo) | No | Information about the new version. | +| Name | Type | Mandatory | Description | +| ----------------- | --------------------------------- | ---- | ------ | +| isExistNewVersion | bool | Yes | Whether a new version is available.| +| newVersionInfo | [NewVersionInfo](#newversioninfo) | No | Information about the new version. | ## NewVersionInfo @@ -1356,10 +1356,10 @@ Represents information about the new version. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | -| versionComponents | Array\<[VersionComponent](#versioncomponent)> | Yes | Version components. | +| Name | Type | Mandatory | Description | +| ----------------- | ---------------------------------------- | ---- | ---- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| versionComponents | Array\<[VersionComponent](#versioncomponent)> | Yes | Version components.| ## VersionDigestInfo @@ -1367,9 +1367,9 @@ Represents version digest information. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| versionDigest | string | Yes | Version digest information. | +| Name | Type | Mandatory | Description | +| ------------- | ------ | ---- | ---- | +| versionDigest | string | Yes | Version digest information.| ## VersionComponent @@ -1377,16 +1377,16 @@ Represents a version component. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| componentId | number | Yes | Component ID. | -| componentType | [ComponentType](#componentyype) | Yes | Component type. | -| upgradeAction | [UpgradeAction](#upgradeaction) | Yes | Update mode. | -| displayVersion | string | Yes | Display version number. | -| innerVersion | string | Yes | Internal version number. | -| size | number | Yes | Update package size. | -| effectiveMode | [EffectiveMode](#effectivemode) | Yes | Effective mode. | -| descriptionInfo | [DescriptionInfo](#descriptioninfo) | Yes | Information about the version description file. | +| Parameter | Type | Mandatory | Description | +| --------------- | ----------------------------------- | ---- | -------- | +| componentId | number | Yes | Component ID. | +| componentType | [ComponentType](#componenttype) | Yes | Component type. | +| upgradeAction | [UpgradeAction](#upgradeaction) | Yes | Update mode. | +| displayVersion | string | Yes | Display version number. | +| innerVersion | string | Yes | Internal version number. | +| size | number | Yes | Update package size. | +| effectiveMode | [EffectiveMode](#effectivemode) | Yes | Effective mode. | +| descriptionInfo | [DescriptionInfo](#descriptioninfo) | Yes | Information about the version description file.| ## DescriptionOptions @@ -1394,10 +1394,10 @@ Represents options of the description file. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| format | [DescriptionFormat](#descriptionformat) | Yes | Format of the description file. | -| language | string | Yes | Language of the description file. | +| Name | Type | Mandatory | Description | +| -------- | --------------------------------------- | ---- | ------ | +| format | [DescriptionFormat](#descriptionformat) | Yes | Format of the description file.| +| language | string | Yes | Language of the description file.| ## ComponentDescription @@ -1405,10 +1405,10 @@ Represents a component description file. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| componentId | string | Yes | Component ID. | -| descriptionInfo | [DescriptionInfo](#descriptioninfo) | Yes | Information about the description file. | +| Name | Type | Mandatory | Description | +| --------------- | ----------------------------------- | ---- | ------ | +| componentId | string | Yes | Component ID. | +| descriptionInfo | [DescriptionInfo](#descriptioninfo) | Yes | Information about the description file.| ## DescriptionInfo @@ -1416,10 +1416,10 @@ Represents information about the version description file. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| descriptionType | [DescriptionType](#descriptiontype) | Yes | Type of the description file. | -| content | string | Yes | Content of the description file. | +| Name | Type | Mandatory | Description | +| --------------- | ----------------------------------- | ---- | ------ | +| descriptionType | [DescriptionType](#descriptiontype) | Yes | Type of the description file.| +| content | string | Yes | Content of the description file.| ## CurrentVersionInfo @@ -1427,11 +1427,11 @@ Represents information about the current version. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| osVersion | string | Yes | System version number. | -| deviceName | string | Yes | Device name. | -| versionComponents | Array\<[VersionComponent](#vesioncomponent)> | No | Version components. | +| Name | Type | Mandatory | Description | +| ----------------- | ---------------------------------------- | ---- | ----- | +| osVersion | string | Yes | System version number.| +| deviceName | string | Yes | Device name. | +| versionComponents | Array\<[VersionComponent](#versioncomponent)> | No | Version components. | ## DownloadOptions @@ -1439,10 +1439,10 @@ Represents download options. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| allowNetwork | [NetType](#nettype) | Yes | Network type. | -| order | [Order](#order) | Yes | Update command. | +| Name | Type | Mandatory | Description | +| ------------ | ------------------- | ---- | ---- | +| allowNetwork | [NetType](#nettype) | Yes | Network type.| +| order | [Order](#order) | Yes | Update command.| ## ResumeDownloadOptions @@ -1450,9 +1450,9 @@ Represents options for resuming download. **System capability**: SystemCapability.Update.UpdateService -| Parameter | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| allowNetwork | [NetType](#nettype) | Yes | Network type. | +| Name | Type | Mandatory | Description | +| ------------ | ------------------- | ---- | ---- | +| allowNetwork | [NetType](#nettype) | Yes | Network type.| ## PauseDownloadOptions @@ -1460,9 +1460,9 @@ Represents options for pausing download. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| isAllowAutoResume | bool | Yes | Whether to allow automatic resuming of download. | +| Name | Type| Mandatory | Description | +| ----------------- | ---- | ---- | -------- | +| isAllowAutoResume | bool | Yes | Whether to allow automatic resuming of download.| ## UpgradeOptions @@ -1470,9 +1470,9 @@ Represents update options. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| order | [Order](#order) | Yes | Update command. | +| Name | Type | Mandatory | Description | +| ----- | --------------- | ---- | ---- | +| order | [Order](#order) | Yes | Update command.| ## ClearOptions @@ -1480,9 +1480,9 @@ Represents options for clearing errors. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| status | [UpgradeStatus](#upgradestatus) | Yes | Error status. | +| Name | Type | Mandatory | Description | +| ------ | ------------------------------- | ---- | ---- | +| status | [UpgradeStatus](#upgradestatus) | Yes | Error status.| ## UpgradePolicy @@ -1490,11 +1490,11 @@ Represents an update policy. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| downloadStrategy | bool | Yes | Automatic download policy. | -| autoUpgradeStrategy | bool | Yes | Automatic update policy. | -| autoUpgradePeriods | Array\<[UpgradePeriod](#upgradeperiod)> | Yes | Automatic update period.| +| Name | Type | Mandatory | Description | +| ------------------- | --------------------------------------- | ---- | ------- | +| downloadStrategy | bool | Yes | Automatic download policy. | +| autoUpgradeStrategy | bool | Yes | Automatic update policy. | +| autoUpgradePeriods | Array\<[UpgradePeriod](#upgradeperiod)> | Yes | Automatic update period.| ## UpgradePeriod @@ -1502,10 +1502,10 @@ Represents a period for automatic update. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| start | number | Yes | Start time. | -| end | number | Yes | End time. | +| Name | Type | Mandatory | Description | +| ----- | ------ | ---- | ---- | +| start | number | Yes | Start time.| +| end | number | Yes | End time.| ## TaskInfo @@ -1513,21 +1513,21 @@ Represents task information. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| existTask | bool | Yes | Whether a task exists. | -| taskBody | [TaskBody](#taskinfo) | Yes | Task data. | +| Name | Type | Mandatory | Description | +| --------- | --------------------- | ---- | ------ | +| existTask | bool | Yes | Whether a task exists.| +| taskBody | [TaskBody](#taskinfo) | Yes | Task data. | ## EventInfo -Represents event information. +Represents event type information. **System capability**: SystemCapability.Update.UpdateService -| Parameter | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| eventId | [EventId](#eventid) | Yes | Event ID. | -| taskBody | [TaskBody](#taskinfo) | Yes | Task data. | +| Name | Type | Mandatory | Description | +| -------- | --------------------- | ---- | ---- | +| eventId | [EventId](#eventid) | Yes | Event ID.| +| taskBody | [TaskBody](#taskinfo) | Yes | Task data.| ## TaskBody @@ -1535,15 +1535,15 @@ Represents task data. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information. | -| status | [UpgradeStatus](#upgradestatus) | Yes | Update status. | -| subStatus | number | No | Sub-status. | -| progress | number | Yes | Progress. | -| installMode | number | Yes | Installation mode. | -| errorMessages | Array\<[ErrorMessage](#errormessage)> | No | Error message. | -| versionComponents | Array\<[VersionComponent](#versioncomponent)> | Yes | Version components. | +| Name | Type | Mandatory | Description | +| ----------------- | ---------------------------------------- | ---- | ---- | +| versionDigestInfo | [VersionDigestInfo](#versiondigestinfo) | Yes | Version digest information.| +| status | [UpgradeStatus](#upgradestatus) | Yes | Update status.| +| subStatus | number | No | Sub-status. | +| progress | number | Yes | Progress. | +| installMode | number | Yes | Installation mode.| +| errorMessages | Array\<[ErrorMessage](#errormessage)> | No | Error message.| +| versionComponents | Array\<[VersionComponent](#versioncomponent)> | Yes | Version components.| ## ErrorMessage @@ -1551,10 +1551,10 @@ Represents an error message. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| errorCode | number | Yes | Error code. | -| errorMessage | string | Yes | Error description. | +| Name | Type | Mandatory | Description | +| ------------ | ------ | ---- | ---- | +| errorCode | number | Yes | Error code. | +| errorMessage | string | Yes | Error description.| ## EventClassifyInfo @@ -1562,10 +1562,10 @@ Represents event type information. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| eventClassify | [EventClassify](#eventclassify) | Yes | Event type. | -| extraInfo | string | Yes | Additional information. | +| Name | Type | Mandatory | Description | +| ------------- | ------------------------------- | ---- | ---- | +| eventClassify | [EventClassify](#eventclassify) | Yes | Event type.| +| extraInfo | string | Yes | Additional information.| ## UpgradeFile @@ -1573,22 +1573,22 @@ Represents an update file. **System capability**: SystemCapability.Update.UpdateService -| Name | Type | Mandatory | Description | -| ------------------- | --------------------------- | ---- | ------- | -| fileType | [ComponentType](#componenttype) | Yes | File type. | -| filePath | string | Yes | File path. | +| Name | Type | Mandatory | Description | +| -------- | ------------------------------- | ---- | ---- | +| fileType | [ComponentType](#componenttype) | Yes | File type.| +| filePath | string | Yes | File path.| ## UpgradeTaskCallback ### (eventInfo: [EventInfo](#eventinfo)): void -Event callback. +Represents an event callback. **System capability**: SystemCapability.Update.UpdateService -| Parameter | Type | Mandatory | Description | -| --------------- | ---------------------------------------- | ---- | ---- | -| eventInfo | [EventInfo](#eventinfo) | Yes | Event information.| +| Name | Type | Mandatory | Description | +| --------- | ----------------------- | ---- | ---- | +| eventInfo | [EventInfo](#eventinfo) | Yes | Event information.| ## BusinessVendor @@ -1596,9 +1596,9 @@ Device vendor. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| PUBLIC | "public" | Open source. | +| Name | Default Value | Description | +| ------ | -------- | ---- | +| PUBLIC | "public" | Open source. | ## BusinessSubType @@ -1606,9 +1606,9 @@ Represents an update type. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| FIRMWARE | 1 | Firmware. | +| Name | Default Value | Description | +| -------- | ---- | ---- | +| FIRMWARE | 1 | Firmware. | ## ComponentType @@ -1616,9 +1616,9 @@ Represents a component type. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| OTA | 1 | Firmware. | +| Name | Default Value | Description | +| ---- | ---- | ---- | +| OTA | 1 | Firmware. | ## UpgradeAction @@ -1626,10 +1626,10 @@ Represents an update mode. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| UPGRADE | "upgrade" | Differential package. | -| RECOVERY | "recovery" | Recovery package. | +| Name | Default Value | Description | +| -------- | ---------- | ---- | +| UPGRADE | "upgrade" | Differential package. | +| RECOVERY | "recovery" | Recovery package. | ## EffectiveMode @@ -1637,11 +1637,11 @@ Represents an effective mode. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| COLD | 1 | Cold update. | -| LIVE | 2 | Live update. | -| LIVE_AND_COLD | 3 | Hybrid live and cold update. | +| Name | Default Value | Description | +| ------------- | ---- | ---- | +| COLD | 1 | Cold update. | +| LIVE | 2 | Live update. | +| LIVE_AND_COLD | 3 | Hybrid live and cold update.| ## DescriptionType @@ -1649,10 +1649,10 @@ Represents a description file type. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| CONTENT | 0 | Content. | -| URI | 1 | Link. | +| Name | Default Value | Description | +| ------- | ---- | ---- | +| CONTENT | 0 | Content. | +| URI | 1 | Link. | ## DescriptionFormat @@ -1660,10 +1660,10 @@ Represents a description file format. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| STANDARD | 0 | Standard format. | -| SIMPLIFIED | 1 | Simple format. | +| Name | Default Value | Description | +| ---------- | ---- | ---- | +| STANDARD | 0 | Standard format.| +| SIMPLIFIED | 1 | Simple format.| ## NetType @@ -1671,13 +1671,13 @@ Enumerates network types. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| CELLULAR | 1 | Data network. | -| METERED_WIFI | 2 | Wi-Fi hotspot. | -| NOT_METERED_WIFI | 4 | Non Wi-Fi hotspot. | -| WIFI | 6 | WIFI | -| CELLULAR_AND_WIFI | 7 | Data network and Wi-Fi. | +| Name | Default Value | Description | +| ----------------- | ---- | --------- | +| CELLULAR | 1 | Data network. | +| METERED_WIFI | 2 | Wi-Fi hotspot. | +| NOT_METERED_WIFI | 4 | Non Wi-Fi hotspot. | +| WIFI | 6 | Wi-Fi. | +| CELLULAR_AND_WIFI | 7 | Data network and Wi-Fi.| ## Order @@ -1685,13 +1685,13 @@ Represents an update command. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| DOWNLOAD | 1 | Download. | -| INSTALL | 2 | Install. | -| DOWNLOAD_AND_INSTALL | 3 | Download and install. | -| APPLY | 4 | Apply. | -| INSTALL_AND_APPLY | 6 | Install and apply. | +| Name | Default Value | Description | +| -------------------- | ---- | ----- | +| DOWNLOAD | 1 | Download. | +| INSTALL | 2 | Install. | +| DOWNLOAD_AND_INSTALL | 3 | Download and install.| +| APPLY | 4 | Apply. | +| INSTALL_AND_APPLY | 6 | Install and apply.| ## UpgradeStatus @@ -1699,18 +1699,18 @@ Enumerates update states. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| WAITING_DOWNLOAD | 20 | Waiting for download. | -| DOWNLOADING | 21 | Downloading. | -| DOWNLOAD_PAUSED | 22 | Download paused. | -| DOWNLOAD_FAIL | 23 | Download failed. | -| WAITING_INSTALL | 30 | Waiting for installation. | -| UPDATING | 31 | Updating. | -| WAITING_APPLY | 40 | Waiting for applying the update. | -| APPLYING | 21 | Applying the update. | -| UPGRADE_SUCCESS | 50 | Update succeeded. | -| UPGRADE_FAIL | 51 | Update failed. | +| Name | Default Value | Description | +| ---------------- | ---- | ---- | +| WAITING_DOWNLOAD | 20 | Waiting for download. | +| DOWNLOADING | 21 | Downloading. | +| DOWNLOAD_PAUSED | 22 | Download paused.| +| DOWNLOAD_FAIL | 23 | Download failed.| +| WAITING_INSTALL | 30 | Waiting for installation. | +| UPDATING | 31 | Updating. | +| WAITING_APPLY | 40 | Waiting for applying the update. | +| APPLYING | 21 | Applying the update. | +| UPGRADE_SUCCESS | 50 | Update succeeded.| +| UPGRADE_FAIL | 51 | Update failed.| ## EventClassify @@ -1718,9 +1718,9 @@ Represents an event type. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| TASK | 0x01000000 | Task event. | +| Name | Default Value | Description | +| ---- | ---------- | ---- | +| TASK | 0x01000000 | Task event.| ## EventId @@ -1728,22 +1728,22 @@ Enumerates event IDs. **System capability**: SystemCapability.Update.UpdateService -| Name | Default Value | Description | -| ------------------- | ---- | -------- | -| EVENT_TASK_BASE | 0x01000000 | Indicates a task event. | -| EVENT_TASK_RECEIVE | 0x01000001 | Indicates that a task is received. | -| EVENT_TASK_CANCEL | 0x01000010 | Indicates that a task is cancelled. | -| EVENT_DOWNLOAD_WAIT | 0x01000011 | Indicates the state of waiting for the download. | -| EVENT_DOWNLOAD_START | 0x01000100 | Indicates that the download starts. | -| EVENT_DOWNLOAD_UPDATE | 0x01000101 | Indicates the download progress update. | -| EVENT_DOWNLOAD_PAUSE | 0x01000110 | Indicates that the download is paused. | -| EVENT_DOWNLOAD_RESUME | 0x01000111 | Indicates that the download is resumed. | -| EVENT_DOWNLOAD_SUCCESS | 0x01001000 | Indicates that the download succeeded. | -| EVENT_DOWNLOAD_FAIL | 0x01001001 | Indicates that the download failed. | -| EVENT_UPGRADE_WAIT | 0x01001010 | Indicates the state of waiting for the update. | -| EVENT_UPGRADE_START | 0x01001011 | Indicates that the update starts. | -| EVENT_UPGRADE_UPDATE | 0x01001100 | Indicates that the update is in progress. | -| EVENT_APPLY_WAIT | 0x01001101 | Indicates the state of waiting for applying the update. | -| EVENT_APPLY_START | 0x01001110 | Indicates the state of applying the update. | -| EVENT_UPGRADE_SUCCESS | 0x01001111 | Indicates that the update succeeded. | -| EVENT_UPGRADE_FAIL | 0x01010000 | Indicates that the update failed. | +| Name | Default Value | Description | +| ---------------------- | ---------- | ------ | +| EVENT_TASK_BASE | 0x01000000 | Indicates a task event. | +| EVENT_TASK_RECEIVE | 0x01000001 | Indicates that a task is received. | +| EVENT_TASK_CANCEL | 0x01000010 | Indicates that a task is cancelled. | +| EVENT_DOWNLOAD_WAIT | 0x01000011 | Indicates the state of waiting for the download. | +| EVENT_DOWNLOAD_START | 0x01000100 | Indicates that the download starts. | +| EVENT_DOWNLOAD_UPDATE | 0x01000101 | Indicates the download progress update.| +| EVENT_DOWNLOAD_PAUSE | 0x01000110 | Indicates that the download is paused. | +| EVENT_DOWNLOAD_RESUME | 0x01000111 | Indicates that the download is resumed. | +| EVENT_DOWNLOAD_SUCCESS | 0x01001000 | Indicates that the download succeeded. | +| EVENT_DOWNLOAD_FAIL | 0x01001001 | Indicates that the download failed. | +| EVENT_UPGRADE_WAIT | 0x01001010 | Indicates the state of waiting for the update. | +| EVENT_UPGRADE_START | 0x01001011 | Indicates that the update starts. | +| EVENT_UPGRADE_UPDATE | 0x01001100 | Indicates that the update is in progress. | +| EVENT_APPLY_WAIT | 0x01001101 | Indicates the state of waiting for applying the update. | +| EVENT_APPLY_START | 0x01001110 | Indicates the state of applying the update. | +| EVENT_UPGRADE_SUCCESS | 0x01001111 | Indicates that the update succeeded. | +| EVENT_UPGRADE_FAIL | 0x01010000 | Indicates that the update failed. | 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-basic-gestures-tapgesture.md b/en/application-dev/reference/arkui-ts/ts-basic-gestures-tapgesture.md index 495cd2a220e5c5d775ef395803ca5b26efa55175..5d6a38dd6cb5ec8b13e97b0d660e11674859f585 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-gestures-tapgesture.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-gestures-tapgesture.md @@ -1,7 +1,9 @@ # TapGesture +A tap gesture can recognize one or more taps. -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> **NOTE** +> > This gesture is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. @@ -15,23 +17,24 @@ None TapGesture(options?: { count?: number, fingers?: number }) - Parameters - | Name | Type | Mandatory | Default Value | Description | + | Name | Type | Mandatory | Default Value | Description | | -------- | -------- | -------- | -------- | -------- | - | count | number | No | 1 | Number of consecutive taps. If this parameter is set to a value less than **1**, the default value will be used.
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms. | - | fingers | number | No | 1 | Minimum number of fingers to trigger a tap. The value ranges from 1 to 10.
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> 1. When multi-finger is configured, if the number of fingers used for tap does not reach the specified number within 300 ms after the first finger is tapped, the gesture fails to be recognized.
>
> 2. Gesture recognition fails if the number of fingers used for tap exceeds the configured number. | + | count | number | No | 1 | Number of consecutive taps. If this parameter is set to a value less than **1**, the default value will be used.
> **NOTE**
> If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms. | + | fingers | number | No | 1 | Minimum number of fingers to trigger a tap. The value ranges from 1 to 10.
> **NOTE**
> 1. When multi-finger is configured, if the number of fingers used for tap does not reach the specified number within 300 ms after the first finger is tapped, the gesture fails to be recognized.
> 2. Gesture recognition fails if the number of fingers used for tap exceeds the configured number. | ## Events - | Name | Description | +| Name | Description | | -------- | -------- | -| onAction((event?: GestureEvent) => void) | Callback invoked when a tap gesture is recognized. | +| onAction((event?: [GestureEvent](ts-gesture-settings.md)) => void) | Callback invoked when a tap gesture is recognized. | ## Example -``` +```ts +// xxx.ets @Entry @Component struct TapGestureExample { 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 , , ,