From 122e3050049a59e4b24eef46640657159cb4f8a3 Mon Sep 17 00:00:00 2001 From: shawn_he Date: Mon, 28 Feb 2022 16:37:35 +0800 Subject: [PATCH] update docs Signed-off-by: shawn_he --- .../reference/apis/js-apis-bytrace.md | 277 +++----- .../reference/apis/js-apis-call.md | 465 +++++++------- .../reference/apis/js-apis-hiappevent.md | 497 ++++----------- .../reference/apis/js-apis-hichecker.md | 126 ++++ .../reference/apis/js-apis-hidebug.md | 170 +++++ .../reference/apis/js-apis-hitracechain.md | 259 ++++---- .../reference/apis/js-apis-hitracemeter.md | 128 ++-- .../reference/apis/js-apis-power.md | 234 +++---- .../reference/apis/js-apis-radio.md | 378 +++++------ .../reference/apis/js-apis-runninglock.md | 599 ++++++------------ .../reference/apis/js-apis-sim.md | 385 ++++++----- .../reference/apis/js-apis-sms.md | 308 ++++----- 12 files changed, 1777 insertions(+), 2049 deletions(-) create mode 100644 en/application-dev/reference/apis/js-apis-hichecker.md create mode 100644 en/application-dev/reference/apis/js-apis-hidebug.md diff --git a/en/application-dev/reference/apis/js-apis-bytrace.md b/en/application-dev/reference/apis/js-apis-bytrace.md index a79e890d2a2..ff5fbcee930 100644 --- a/en/application-dev/reference/apis/js-apis-bytrace.md +++ b/en/application-dev/reference/apis/js-apis-bytrace.md @@ -1,197 +1,110 @@ -# Performance Tracing +# Performance Tracing ->![](../../public_sys-resources/icon-note.gif) **NOTE:** +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** > - The APIs of this module are no longer maintained since API version 8. It is recommended that you use the APIs of [hiTraceMeter](js-apis-hitracemeter.md) instead. > - 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 + +## Modules to Import ``` import bytrace from '@ohos.bytrace'; ``` -## Required Permissions - -None - -## bytrace.startTrace - -startTrace\(name: string, taskId: number, expectedTime?: number\): void - -Starts a trace of a task. **expectedTime** is an optional parameter, which specifies the expected duration of the trace. - -- Parameters - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

name

-

string

-

Yes

-

Name of the trace task to start.

-

taskId

-

number

-

Yes

-

Task ID.

-

expectedTime

-

number

-

No

-

Expected duration of the trace, in ms.

-
- - >![](../../public_sys-resources/icon-note.gif) **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 **taskId**s 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 - - ``` - bytrace.startTrace("myTestFunc", 1); - bytrace.startTrace("myTestFunc", 1, 5); // The expected duration of the trace is 5 ms. - ``` - - -## bytrace.finishTrace - -finishTrace\(name: string, taskId: number\): void + +## System Capabilities + +SystemCapability.Developtools.Bytrace + + +## bytrace.startTrace + +startTrace(name: string, taskId: number, expectedTime?: number): void + +Starts a trace task. **expectedTime** is an optional parameter, which specifies the expected duration of the trace. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the trace task to start.| +| taskId | number | Yes| Task ID.| +| expectedTime | number | No| Expected duration of the trace, in ms.| + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **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** + +``` +bytrace.startTrace("myTestFunc", 1); +bytrace.startTrace("myTestFunc", 1, 5); // The expected duration of the trace is 5 ms. +``` + + +## bytrace.finishTrace + +finishTrace(name: string, taskId: number): void Stops a trace task. -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

name

-

string

-

Yes

-

Name of the trace task to stop.

-

taskId

-

number

-

Yes

-

Task ID.

-
- - >![](../../public_sys-resources/icon-note.gif) **NOTE:** - >To stop a trace task, the values of **name** and **taskId** in **finishTrace** must be the same as those in **startTrace**. - -- Example - - ``` - bytrace.finishTrace("myTestFunc", 1); - ``` - - ``` - // Start track tasks with the same name concurrently. - bytrace.startTrace("myTestFunc", 1); - ...... // Service flow - bytrace.startTrace ("myTestFunc", 2); // The second trace task starts while the first task is still running. The first and second tasks have the same name but different task IDs. - ...... // Service flow - bytrace.finishTrace("myTestFunc", 1); - ...... // Service flow - bytrace.finishTrace("myTestFunc", 2); - ``` - - ``` - // Start track tasks with the same name at different times. - bytrace.startTrace("myTestFunc", 1); - ...... // Service flow - bytrace.finishTrace("myTestFunc", 1); // The first trace task ends. - ...... // Service flow - bytrace.startTrace("myTestFunc", 1); // The second trace task starts after the first task ends. The two tasks have the same name and task ID. - ...... // Service flow - bytrace.finishTrace("myTestFunc", 1); - ``` - - -## bytrace.traceByValue - -traceByValue\(name: string, value: number\): void +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the trace task to start.| +| taskId | number | Yes| Task ID.| + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> To stop a trace task, the values of name and task ID in **finishTrace** must be the same as those in **startTrace**. + +**Example** + +``` +bytrace.finishTrace("myTestFunc", 1); +``` + +``` +// Start track tasks with the same name concurrently. +bytrace.startTrace("myTestFunc", 1); +// Service flow +bytrace.startTrace("myTestFunc", 2); // The second trace task starts while the first task is still running. The first and second tasks have the same name but different task IDs. +// Service flow +bytrace.finishTrace("myTestFunc", 1); +// Service flow +bytrace.finishTrace("myTestFunc", 2); +``` + +``` +// Start track tasks with the same name at different times. +bytrace.startTrace("myTestFunc", 1); +// Service flow +bytrace.finishTrace("myTestFunc", 1); // The first trace task ends. +// Service flow +bytrace.startTrace("myTestFunc", 1); // The second trace task starts after the first task ends. The two tasks have the same name and task ID. +// Service flow +bytrace.finishTrace("myTestFunc", 1); +``` + + +## bytrace.traceByValue + +traceByValue(name: string, value: number): void Traces the value changes of a variable. -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

name

-

string

-

Yes

-

Name of the variable to trace.

-

value

-

number

-

Yes

-

Value of the variable to trace.

-
- -- Example - - ``` - let traceCount = 3; - bytrace.traceByValue("myTestCount", traceCount); - ...... - traceCount = 5; - bytrace.traceByValue("myTestCount", traceCount); - ``` +**Parameters** +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the variable.| +| value | number | Yes| Value of the variable.| + +**Example** + +``` +let traceCount = 3; +bytrace.traceByValue("myTestCount", traceCount); +traceCount = 4; +bytrace.traceByValue("myTestCount", traceCount); +// Service flow +``` diff --git a/en/application-dev/reference/apis/js-apis-call.md b/en/application-dev/reference/apis/js-apis-call.md index 14584a1f0e3..cb892795387 100644 --- a/en/application-dev/reference/apis/js-apis-call.md +++ b/en/application-dev/reference/apis/js-apis-call.md @@ -1,6 +1,6 @@ # Call ->**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. @@ -19,20 +19,20 @@ Initiates a call. This function uses an asynchronous callback to return the exec Before using this API, you must declare the **ohos.permission.PLACE\_CALL** permission (a system permission). -- Parameters - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | phoneNumber | string | Yes|Phone number.| - | callback |AsyncCallback<boolean>|Yes|Callback used to return the result.
- **true**: success
-**false**: failure| - -- Example +**Parameters** - ``` - call.dial("138xxxxxxxx", (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +| Name| Type| Mandatory| Description| +| ----------- | ---------------------------- | ---- | ------------------------------------------------- | +| phoneNumber | string | Yes| Phone number.| +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.
- **true**: success
- **false**: failure| + +**Example** + +``` +call.dial("138xxxxxxxx", (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## call.dial @@ -43,24 +43,23 @@ Initiates a call. You can set call options as needed. This function uses an asyn Before using this API, you must declare the **ohos.permission.PLACE\_CALL** permission (a system permission). -- Parameters - - | Parameter| Type| Mandatory| Description| - | ----------- | ---------------------------- | ---- | ------------------------------------------------- | - | phoneNumber | string | Yes| Phone number.| - | options | DialOptions | Yes| Call options. For details, see [DialOptions](#DialOptions).| - | callback | AsyncCallback<boolean> | Yes| Callback used to return the result.
- **true**: success
-**false**: failure| +**Parameters** +| Name| Type| Mandatory| Description| +| ----------- | ---------------------------- | ---- | ------------------------------------------------- | +| phoneNumber | string | Yes| Phone number.| +| options | DialOptions | Yes| Call options. For details, see [DialOptions](#DialOptions).| +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.
- **true**: success
- **false**: failure| -- Example +**Example** - ``` - call.dial("138xxxxxxxx", { - extras: false - }, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +call.dial("138xxxxxxxx", { + extras: false +}, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## call.dial @@ -71,31 +70,31 @@ Initiates a call. You can set call options as needed. This function uses a promi Before using this API, you must declare the **ohos.permission.PLACE\_CALL** permission (a system permission). -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ----------- | ----------- | ---- | ------------------------------------------- | - | phoneNumber | string | Yes| Phone number.| - | options | DialOptions | Yes| Call options. For details, see [DialOptions](#DialOptions).| +| Name| Type| Mandatory| Description| +| ----------- | ----------- | ---- | ------------------------------------------- | +| phoneNumber | string | Yes| Phone number.| +| options | DialOptions | Yes| Call options. For details, see [DialOptions](#DialOptions).| -- Return values +**Return value** - | Type| Description| - | ---------------------- | --------------------------------- | - | Promise<boolean> | Promise used to return the result.| +| Type| Description| +| ---------------------- | --------------------------------- | +| Promise<boolean> | Promise used to return the result.| -- Example +**Example** - ``` - let promise = call.dial("138xxxxxxxx", { - extras: false - }); - promise.then(data => { - console.log(`dial success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`dial fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = call.dial("138xxxxxxxx", { + extras: false +}); +promise.then(data => { + console.log(`dial success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`dial fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## call.hasCall @@ -103,19 +102,19 @@ hasCall\(callback: AsyncCallback\): void Checks whether a call is in progress. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ---------------------------- | ---- | ------------------------------------------------------------ | - | callback | AsyncCallback<boolean> | Yes| Callback used to return the result:
- **true**: A call is in progress.
- **false**: No call is in progress. | +| Name| Type| Mandatory| Description| +| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result:
- **true**: A call is in progress.
- **false**: No call is in progress. | -- Example +**Example** - ``` - call.hasCall((err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +call.hasCall((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## call.hasCall @@ -124,22 +123,22 @@ hasCall\(\): Promise Checks whether a call is in progress. This function uses a promise to return the result. -- Return values +**Return value** - | Type| Description| - | ---------------------- | --------------------------------------- | - | Promise<boolean> | Promise used to return the result.| +| Type| Description| +| ---------------------- | --------------------------------------- | +| Promise<boolean> | Promise used to return the result.| -- Example +**Example** - ``` - let promise = call.hasCall(); - promise.then(data => { - console.log(`hasCall success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`hasCall fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = call.hasCall(); +promise.then(data => { + console.log(`hasCall success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`hasCall fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## call.getCallState @@ -148,19 +147,19 @@ getCallState\(callback: AsyncCallback\): void Obtains the call status. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------------------------------------------- | ---- | ------------------------------------ | - | callback | AsyncCallback<[CallState](#CallState)> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | -------------------------------------------- | ---- | ------------------------------------ | +| callback | AsyncCallback<[CallState](#CallState)> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - call.getCallState((err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +call.getCallState((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## call.getCallState @@ -169,118 +168,118 @@ getCallState\(\): Promise Obtains the call status. This function uses a promise to return the result. -- Return values +**Return value** - | Type| Description| - | -------------------------------------- | ----------------------------------------- | - | Promise<[CallState](#CallState)> | Promise used to return the result.| +| Type| Description| +| -------------------------------------- | ----------------------------------------- | +| Promise<[CallState](#CallState)> | Promise used to return the result.| -- Example +**Example** - ``` - let promise = call.getCallState(); - promise.then(data => { - console.log(`getCallState success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`getCallState fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = call.getCallState(); +promise.then(data => { + console.log(`getCallState success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getCallState fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## call.isEmergencyPhoneNumber7+ isEmergencyPhoneNumber\(phoneNumber: string, callback: AsyncCallback\): void -Checks whether the call number is an emergency number. This function uses an asynchronous callback to return the result. +Checks whether the call number of the SIM card in the specified slot is an emergency number. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ----------- | ---------------------------- | ---- | ------------------------------------------------------------ | - | phoneNumber | string | Yes| Phone number.| - | 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.| +| Name| Type| Mandatory| Description| +| ----------- | ---------------------------- | ---- | ------------------------------------------------------------ | +| phoneNumber | string | Yes| Phone number.| +| 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 +**Example** - ``` - call.isEmergencyPhoneNumber("138xxxxxxxx", (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +call.isEmergencyPhoneNumber("138xxxxxxxx", (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## call.isEmergencyPhoneNumber7+ isEmergencyPhoneNumber\(phoneNumber: string, options: EmergencyNumberOptions, callback: AsyncCallback\): void -Checks whether the call number is an emergency number. This function uses an asynchronous callback to return the result. +Checks whether the call number of the SIM card in the specified slot is an emergency number. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ----------- | ---------------------------- | ---- | ------------------------------------------------------------ | - | phoneNumber | string | Yes| Phone number.| - | options | EmergencyNumberOptions | Yes| Emergency number options defined in [EmergencyNumberOptions](#EmergencyNumberOptions).| - | 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.| +| Name| Type| Mandatory| Description| +| ----------- | ---------------------------- | ---- | ------------------------------------------------------------ | +| phoneNumber | string | Yes| Phone number.| +| options | EmergencyNumberOptions | Yes| Emergency number options defined in [EmergencyNumberOptions](#EmergencyNumberOptions).| +| 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 +**Example** - ``` - call.isEmergencyPhoneNumber("112", {slotId: 1}, (err, value) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +call.isEmergencyPhoneNumber("112", {slotId: 1}, (err, value) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## call.isEmergencyPhoneNumber7+ isEmergencyPhoneNumber\(phoneNumber: string, options?: EmergencyNumberOptions\): Promise -Checks whether the call number is an emergency number. This function uses a promise to return the result. +Checks whether the call number of the SIM card in the specified slot is an emergency number. This function uses a promise to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ----------- | ---------------------- | ---- | ------------------------------------------------------------ | - | phoneNumber | string | Yes| Phone number.| - | options | EmergencyNumberOptions | Yes| Emergency number options defined in [EmergencyNumberOptions](#EmergencyNumberOptions).| +| Name| Type| Mandatory| Description| +| ----------- | ---------------------- | ---- | ------------------------------------------------------------ | +| phoneNumber | string | Yes| Phone number.| +| options | EmergencyNumberOptions | Yes| Emergency number options defined in [EmergencyNumberOptions](#EmergencyNumberOptions).| -- Return values +**Return value** - | Type| Description| - | ---------------------- | --------------------------------------------------- | - | Promise<boolean> | Promise used to return the result.| +| Type| Description| +| ---------------------- | --------------------------------------------------- | +| Promise<boolean> | Promise used to return the result.| -- Example +**Example** - ``` - let promise = call.isEmergencyPhoneNumber("138xxxxxxxx", {slotId: 1}); - promise.then(data => { - console.log(`isEmergencyPhoneNumber success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`isEmergencyPhoneNumber fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = call.isEmergencyPhoneNumber("138xxxxxxxx", {slotId: 1}); +promise.then(data => { + console.log(`isEmergencyPhoneNumber success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`isEmergencyPhoneNumber fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## call.formatPhoneNumber7+ formatPhoneNumber\(phoneNumber: string, callback: AsyncCallback\): void -Formats a phone number. This function uses an asynchronous callback to return the result. +Formats a phone number based on the specified ISO country code. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ----------- | --------------------------- | ---- | ------------------------------------ | - | phoneNumber | string | Yes| Phone number.| - | callback | AsyncCallback<string> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| ----------- | --------------------------- | ---- | ------------------------------------ | +| phoneNumber | string | Yes| Phone number.| +| callback | AsyncCallback<string> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - call.formatPhoneNumber("138xxxxxxxx", (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +call.formatPhoneNumber("138xxxxxxxx", (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## call.formatPhoneNumber7+ @@ -289,23 +288,23 @@ formatPhoneNumber\(phoneNumber: string, options: NumberFormatOptions, callback: Formats a phone number based on specified formatting options. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ----------- | --------------------------- | ---- | ------------------------------------------------------------ | - | phoneNumber | string | Yes| Phone number.| - | options | NumberFormatOptions | Yes| Number formatting options defined in [NumberFormatOptions](#NumberFormatOptions).| - | callback | AsyncCallback<string> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | +| phoneNumber | string | Yes| Phone number.| +| options | NumberFormatOptions | Yes| Number formatting options defined in [NumberFormatOptions](#NumberFormatOptions).| +| callback | AsyncCallback<string> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - call.formatPhoneNumber("138xxxxxxxx",{ - countryCode: "CN" - }, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +call.formatPhoneNumber("138xxxxxxxx",{ + countryCode: "CN" +}, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## call.formatPhoneNumber7+ @@ -314,31 +313,31 @@ formatPhoneNumber\(phoneNumber: string, options?: NumberFormatOptions\): Promise Formats a phone number based on specified formatting options. This function uses a promise to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ----------- | ------------------- | ---- | ------------------------------------------------------------ | - | phoneNumber | string | Yes| Phone number.| - | options | NumberFormatOptions | Yes| Number formatting options defined in [NumberFormatOptions](#NumberFormatOptions).| +| Name| Type| Mandatory| Description| +| ----------- | ------------------- | ---- | ------------------------------------------------------------ | +| phoneNumber | string | Yes| Phone number.| +| options | NumberFormatOptions | Yes| Number formatting options defined in [NumberFormatOptions](#NumberFormatOptions).| -- Return values +**Return value** - | Type| Description| - | --------------------- | ------------------------------------------- | - | Promise<string> | Promise used to return the result.| +| Type| Description| +| --------------------- | ------------------------------------------- | +| Promise<string> | Promise used to return the result.| -- Example +**Example** - ``` - let promise = call.formatPhoneNumber("138xxxxxxxx", { - countryCode: "CN" - }); - promise.then(data => { - console.log(`formatPhoneNumber success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`formatPhoneNumber fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = call.formatPhoneNumber("138xxxxxxxx", { + countryCode: "CN" +}); +promise.then(data => { + console.log(`formatPhoneNumber success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`formatPhoneNumber fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## call.formatPhoneNumberToE1647+ @@ -350,23 +349,23 @@ The phone number must match the specified country code. For example, for a China All country codes are supported. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ----------- | --------------------------- | ---- | ----------------------------------------------------- | - | phoneNumber | string | Yes| Phone number.| - | countryCode | string | Yes| Country code, for example, **CN** (China). All country codes are supported.| - | callback | AsyncCallback<string> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| ----------- | --------------------------- | ---- | ----------------------------------------------------- | +| phoneNumber | string | Yes| Phone number.| +| countryCode | string | Yes| Country code, for example, **CN** (China). All country codes are supported.| +| callback | AsyncCallback<string> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - call.formatPhoneNumberToE164("138xxxxxxxx",{ - countryCode: "CN" - }, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +call.formatPhoneNumberToE164("138xxxxxxxx",{ + countryCode: "CN" +}, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## call.formatPhoneNumberToE1647+ @@ -379,59 +378,59 @@ The phone number must match the specified country code. For example, for a China All country codes are supported. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ----------- | ------ | ---- | ---------------------------------------- | - | phoneNumber | string | Yes| Phone number.| - | countryCode | string | Yes| Country code, for example, **CN** (China). All country codes are supported.| +| Name| Type| Mandatory| Description| +| ----------- | ------ | ---- | ---------------------------------------- | +| phoneNumber | string | Yes| Phone number.| +| countryCode | string | Yes| Country code, for example, **CN** (China). All country codes are supported.| -- Return values +**Return value** - | Type| Description| - | --------------------- | ------------------------------------------------------------ | - | Promise<string> | Promise used to return the result.| +| Type| Description| +| --------------------- | ------------------------------------------------------------ | +| Promise<string> | Promise used to return the result.| -- Example +**Example** - ``` - let promise = call.formatPhoneNumberToE164("138xxxxxxxx", { - countryCode: "CN" - }); - promise.then(data => { - console.log(`formatPhoneNumberToE164 success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`formatPhoneNumberToE164 fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = call.formatPhoneNumberToE164("138xxxxxxxx", { + countryCode: "CN" +}); +promise.then(data => { + console.log(`formatPhoneNumberToE164 success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`formatPhoneNumberToE164 fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## DialOptions Provides an option for determining whether a call is a video call. -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| extras | boolean | No|Indication of a video call. The options are as follows:
- **true**: video call
- **false**: voice call| +| Parameter| Type| Mandatory| Description| +| ------ | ------- | ---- | ------------------------------------------------------------ | +| extras | boolean | No| Indication of a video call. The options are as follows:
- **true**: video call
- **false**: voice call| ## CallState Enumerates call states. | Variable| Value| Description| -| -------- | -------- | -------- | -| CALL_STATE_UNKNOWN | -1 | The call status fails to be obtained and is unknown.| -| CALL_STATE_IDLE | 0 | No call is in progress.| -| CALL_STATE_RINGING | 1 | The call is in the ringing or waiting state.| -| CALL_STATE_OFFHOOK | 2 | At least one call is in dialing, active, or on hold, and no new incoming call is ringing or waiting.| +| ------------------ | ---- | ------------------------------------------------------------ | +| CALL_STATE_UNKNOWN | -1 | The call status fails to be obtained and is unknown.| +| CALL_STATE_IDLE | 0 | No call is in progress.| +| CALL_STATE_RINGING | 1 | The call is in the ringing or waiting state.| +| CALL_STATE_OFFHOOK | 2 | At least one call is in dialing, active, or on hold, and no new incoming call is ringing or waiting.| ## EmergencyNumberOptions7+ Provides an option for determining whether a number is an emergency number for the SIM card in the specified slot. -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| slotId | number | No|SIM card slot ID.
- **0**: slot 1
- **1**: slot 2| +| Parameter| Type| Mandatory| Description| +| ------ | ------ | ---- | ------------------------------------------ | +| slotId | number | No| SIM card slot ID.
- **0**: slot 1
- **1**: slot 2| ## NumberFormatOptions7+ Provides an option for number formatting. -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| countryCode | string | No|Country code, for example, **CN** (China). All country codes are supported. The default value is **CN**.| +| Parameter| Type| Mandatory| Description| +| ----------- | ------ | ---- | ---------------------------------------------------------- | +| countryCode | string | No| Country code, for example, **CN** (China). All country codes are supported. The default value is **CN**.| diff --git a/en/application-dev/reference/apis/js-apis-hiappevent.md b/en/application-dev/reference/apis/js-apis-hiappevent.md index a2db965ba8d..0d8534643b5 100644 --- a/en/application-dev/reference/apis/js-apis-hiappevent.md +++ b/en/application-dev/reference/apis/js-apis-hiappevent.md @@ -1,418 +1,157 @@ -# HiAppEvent +# Application dotting ->![](../../public_sys-resources/icon-note.gif) **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. +> ![icon-note.gif](public_sys-resources/icon-note.gif) **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 + +## Modules to Import ``` import hiAppEvent from '@ohos.hiAppEvent'; ``` + ## System Capabilities SystemCapability.HiviewDFX.HiAppEvent -## hiAppEvent.write -write\(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback\): void +## hiAppEvent.write + +write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback<void>): void Writes event information to the event file of the current day. This function supports JSON parameters and uses an asynchronous callback to return the result. -- Parameters - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

eventName

-

string

-

Yes

-

Indicates the application event name.

-

eventType

-

EventType

-

Yes

-

Indicates the application event type.

-

keyValues

-

object

-

Yes

-

Indicates an array of JSON parameters of the application event. A key must be a string, and a value must be a string, number, boolean, or Array (which can only be a string, number, or boolean).

-

callback

-

AsyncCallback<void>

-

No

-

Indicates the callback function, which can be used to process the received return value.

-
  • Value 0 indicates that the event verification is successful, and the event will be written to the event file asynchronously.
  • A value greater than 0 indicates that invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored.
  • A value smaller than 0 indicates that the event verification fails, and the event will not be written to the event file.
-
- -- Example - - ``` - hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}, (err, value) => { - if (err) { - // Event writing exception: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. - console.error(`failed to write event because ${err.code}`); - return; - } - +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| eventName | string | Yes| App event name.| +| eventType | [EventType](#eventtype) | Yes| Application event type.| +| keyValues | object | Yes| Array of JSON parameters of the application event. A key must be a string, and a value must be a string, number, boolean, or Array (which can only be a string, number, or boolean).| +| callback | AsyncCallback<void> | No| Callback used to process the received return value.
- The value **0** indicates that the event parameter verification is successful, and the event will be written to the event file asynchronously.
- A value greater than **0** indicates that invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored.
- A value smaller than **0** indicates that the event parameter verification fails, and the event will not be written to the event file asynchronously.| + +**Example** + +``` +hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}, (err, value) => { + if (err) { + // Event writing exception: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. + console.error(`failed to write event because ${err.code}`); + return; + } + + // Event writing succeeded. + console.log(`success to write event: ${value}`); +}); +``` + + +## hiAppEvent.write + +write(eventName: string, eventType: EventType, keyValues: object): Promise<void> + +Writes event information to the event file of the current day. This function supports JSON parameters and uses a promise to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| eventName | string | Yes| App event name.| +| eventType | [EventType](#eventtype) | Yes| Application event type.| +| keyValues | object | Yes| Array of JSON parameters of the application event. A key must be a string, and a value must be a string, number, boolean, or Array (which can only be a string, number, or boolean).| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to process the callback in the then() and catch() methods when event writing succeeded or failed.| + +**Example** + +``` +hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}) + .then((value) => { // Event writing succeeded. console.log(`success to write event: ${value}`); + }).catch((err) => { + // Event writing exception: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. + console.error(`failed to write event because ${err.code}`); }); - ``` +``` -## hiAppEvent.write +## hiAppEvent.configure -write\(eventName: string, eventType: EventType, keyValues: object\): Promise +configure(config: ConfigOption): boolean -Writes event information to the event file of the current day. This function supports JSON parameters and uses a promise to return the result. +Configures the application event logging function, such as setting the event logging switch and maximum size of the directory that stores the event logging files. -- Parameters - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

eventName

-

string

-

Yes

-

Indicates the application event name.

-

eventType

-

EventType

-

Yes

-

Indicates the application event type.

-

keyValues

-

object

-

Yes

-

Indicates an array of JSON parameters of the application event. A key must be a string, and a value must be a string, number, boolean, or Array (which can only be a string, number, or boolean).

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Promise used to process the callback in the then() and catch() methods when event writing succeeded or failed.

-
- -- Example - - ``` - hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}) - .then((value) => { - // Event writing succeeded. - console.log(`success to write event: ${value}`); - }).catch((err) => { - // Event writing exception: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. - console.error(`failed to write event because ${err.code}`); - }); - ``` - - -## hiAppEvent.configure - -configure\(config: ConfigOption\): boolean +**Parameters** -Configures the application event logging function, such as setting the event logging switch and maximum size of the directory that stores the event logging files. +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| config | [ConfigOption](#configoption) | Yes| Configuration items for application event logging.| -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

config

-

ConfigOption

-

Yes

-

Configuration items for application event logging.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

boolean

-

Returns true if the configuration is successful; returns false otherwise.

-
- -- Example - - ``` - // Configure the application event logging switch. - hiAppEvent.configure({ - disable: true - }); - - // Configure the maximum size of the directory that stores the event logging files. - hiAppEvent.configure({ - maxStorage: '100M' - }); - ``` +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the configuration is successful; returns **false** otherwise.| + +**Example** +``` +// Set the application event logging switch. +hiAppEvent.configure({ + disable: true +}); + +// Configure the maximum size of the directory that stores the event logging files. +hiAppEvent.configure({ + maxStorage: '100M' +}); +``` -## ConfigOption +## ConfigOption Provides the configuration items for application event logging. - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

disable

-

boolean

-

No

-

Application event logging switch. The value true means to disable the application event logging function, and the value false means the opposite.

-

maxStorage

-

string

-

No

-

Maximum size of the event file storage directory. The default value is 10M. If the specified size is exceeded, the oldest event logging files in the storage directory will be deleted to free up space.

-
- -## EventType +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| disable | boolean | No| Application event logging switch. The value true means to disable the application event logging function, and the value false means the opposite.| +| maxStorage | string | No| Maximum size of the event file storage directory. The default value is **10M**. If the specified size is exceeded, the oldest event logging files in the storage directory will be deleted to free up space.| + + +## EventType Enumerates event types. - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Default Value

-

Description

-

FAULT

-

1

-

Fault event

-

STATISTIC

-

2

-

Statistical event

-

SECURITY

-

3

-

Security event

-

BEHAVIOR

-

4

-

Behavior event

-
- -## Event +| Name| Default Value| Description| +| -------- | -------- | -------- | +| FAULT | 1 | Fault event| +| STATISTIC | 2 | Statistical event| +| SECURITY | 3 | Security event| +| BEHAVIOR | 4 | Behavior event| + + +## Event Provides constants that define the names of all predefined events. - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Parameter Type

-

Readable

-

Writable

-

Description

-

USER_LOGIN

-

string

-

Yes

-

No

-

User login event.

-

USER_LOGOUT

-

string

-

Yes

-

No

-

User logout event.

-

DISTRIBUTED_SERVICE_START

-

string

-

Yes

-

No

-

Distributed service startup event.

-
- -## Param +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| USER_LOGIN | string | Yes| No| User login event.| +| USER_LOGOUT | string | Yes| No| User logout event.| +| DISTRIBUTED_SERVICE_START | string | Yes| No| Distributed service startup event.| -Provides constants that define the names of all predefined event parameters. - - - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Parameter Type

-

Readable

-

Writable

-

Description

-

USER_ID

-

string

-

Yes

-

No

-

Custom user ID.

-

DISTRIBUTED_SERVICE_NAME

-

string

-

Yes

-

No

-

Distributed service name.

-

DISTRIBUTED_SERVICE_INSTANCE_ID

-

string

-

Yes

-

No

-

Distributed service instance ID.

-
+## Param + +Provides constants that define the names of all predefined event parameters. +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| USER_ID | string | Yes| No| Custom user ID.| +| DISTRIBUTED_SERVICE_NAME | string | Yes| No| Distributed service name.| +| DISTRIBUTED_SERVICE_INSTANCE_ID | string | Yes| No| Distributed service instance ID.| diff --git a/en/application-dev/reference/apis/js-apis-hichecker.md b/en/application-dev/reference/apis/js-apis-hichecker.md new file mode 100644 index 00000000000..dec8de1c541 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-hichecker.md @@ -0,0 +1,126 @@ +# HiChecker + +> **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 hichecker from '@ohos.hichecker'; +``` + + +## System Capabilities + +SystemCapability.HiviewDFX.HiChecker + +## Rule Constants + +Provides the constants of all rule types. + +| Name| Type| Description| +| ---------------------------------- | -------- | ------------------------------------------------------ | +| RULE_CAUTION_PRINT_LOG | BigInt | Alarm rule, which is programmed to print a log when an alarm is generated.| +| RULE_CAUTION_TRIGGER_CRASH | BigInt | Alarm rule. When an alarm is generated, the application exits.| +| RULE_THREAD_CHECK_SLOW_PROCESS | BigInt | Caution rule, which is programmed to detect whether any time-consuming function is invoked.| +| RULE_CHECK_SLOW_EVENT | BigInt | Caution rule, which is programmed to detect whether the event distribution or processing time has exceeded the specified time threshold.| +| RULE_CHECK_ABILITY_CONNECTION_LEAK | BigInt | Caution rule, which is programmed to detect whether ability leakage has occurred.| + + +## hichecker.addRule + +addRule(rule: BigInt): void + +Adds one or more rules. HiChecker detects unexpected operations or gives feedback based on the added rules. + +**Parameters** + +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | ---------------- | +| rule | BigInt | Yes| Rule to be added.| + +**Example** + +``` +// Add a rule. +hichecker.addRule(hichecker.RULE_CAUTION_PRINT_LOG); + +// Add multiple rules. +hichecker.addRule( + hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH); +``` + +## hichecker.removeRule + +removeRule(rule: BigInt): void + +Removes one or more rules. The removed rules will become ineffective. + +**Parameters** + +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | ---------------- | +| rule | BigInt | Yes| Rule to be removed.| + +**Example** + +``` +// Remove a rule. +hichecker.removeRule(hichecker.RULE_CAUTION_PRINT_LOG); + +// Remove multiple rules. +hichecker.removeRule( + hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH); +``` + +## hichecker.getRule + +getRule(): BigInt + +Obtains a collection of thread, process, and alarm rules that have been added. + +**Return value** + +| Type| Description| +| ------ | ---------------------- | +| BigInt | Collection of added rules.| + +**Example** + +``` +// Add a rule. +hichecker.addRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); + +// Obtain the collection of added rules. +hichecker.getRule(); // return 1n; +``` + +## hichecker.contains + +contains(rule: BigInt): boolean + +Checks whether the specified rule exists in the collection of added rules. If the rule is of the thread level, this operation is performed only on the current thread. + +**Parameters** + +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | ---------------- | +| rule | BigInt | Yes| Rule to be checked.| + +**Return value** + +| Type| Description| +| ------- | ---------------------------------------------------------- | +| boolean | Returns **true** if the rule exists in the collection of added rules; returns **false** otherwise.| + +**Example** + +``` +// Add a rule. +hichecker.addRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); + +// Check whether the added rule exists in the collection of added rules. +hichecker.contains(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); // return true; +hichecker.contains(hichecker.RULE_CAUTION_PRINT_LOG); // return false; +``` diff --git a/en/application-dev/reference/apis/js-apis-hidebug.md b/en/application-dev/reference/apis/js-apis-hidebug.md new file mode 100644 index 00000000000..78b6282ce68 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-hidebug.md @@ -0,0 +1,170 @@ +# HiDebug + +> ![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. + +You can run the hidebug command to obtain the memory usage of an application, including the static heap memory (native heap) and proportional set size (PSS) occupied by the application process. You can also export VM memory slices and collect VM CPU profiling data. + +## Modules to Import + +``` +import hidebug from '@ohos.hidebug'; +``` + + +## System Capabilities +SystemCapability.HiviewDFX.HiProfiler.HiDebug + + +## hidebug.getNativeHeapSize + +getNativeHeapSize(): bigint + +Obtains the total size of the native heap memory. + + +- **Return value** + | Type| Description| + | -------- | -------- | + | bigint | Total size of the native heap memory.| + + +- **Example** + ``` + let nativeHeapSize = hidebug.getNativeHeapSize(); + ``` + + +## hidebug.getNativeHeapAllocatedSize + +getNativeHeapAllocatedSize(): bigint + +Obtains the size of the allocated native heap memory. + + +- **Return value** + | Type| Description| + | -------- | -------- | + | bigint | Size of the allocated native heap memory.| + + +- **Example** + ``` + let nativeHeapAllocatedSize = hidebug.getNativeHeapAllocatedSize(); + ``` + + +## hidebug.getNativeHeapFreeSize + +getNativeHeapFreeSize(): bigint + +Obtains the size of the free native heap memory. + + +- **Return value** + | Type| Description| + | -------- | -------- | + | bigint | Size of the free native heap memory.| + + +- **Example** + ``` + let nativeHeapFreeSize = hidebug.getNativeHeapFreeSize(); + ``` + + +## hidebug.getPss + +getPss(): bigint + +Obtains the PSS of this process. + + +- **Return value** + | Type| Description| + | -------- | -------- | + | bigint | PSS of the process.| + + +- **Example** + ``` + let pss = hidebug.getPss(); + ``` + + +## hidebug.getSharedDirty + +getSharedDirty(): bigint + +Obtains the size of the shared dirty memory of this process. + + +- **Return value** + | Type| Description| + | -------- | -------- | + | bigint | Size of the shared dirty memory of the process.| + + +- **Example** + ``` + let sharedDirty = hidebug.getSharedDirty()); + ``` + + +## hidebug.startProfiling + +startProfiling(filename : string) : void + +Starts the profiling method. `startProfiling()` and `stopProfiling()` are called in pairs. `startProfiling()` always occurs before `stopProfiling()`; that is, calling the functions in the following sequences is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | ------ | ---- | ------------------------------------------------------------ | +| filename | string | Yes| User-defined profile name. The `filename.json` file is generated in the `files` directory of the application based on the specified `filename`.| + +**Example** + +```js +hidebug.startProfiling("cpuprofiler-20220216"); +// Code block +// ... +// Code block +hidebug.stopProfiling(); +``` + + + +## hidebug.stopProfiling + +stopProfiling() : void + +Stops the profiling method. `stopProfiling()` and `startProfiling()` are called in pairs. `stopProfiling()` always occurs after `startProfiling()`; that is, calling the functions in the following sequences is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`. + +**Example** + +```js +hidebug.startProfiling("cpuprofiler-20220216"); +// Code block +// ... +// Code block +hidebug.stopProfiling(); +``` + +## hidebug.dumpHeapData + +dumpHeapData(filename : string) : void + +Exports the heap data. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | ------ | ---- | ------------------------------------------------------------ | +| filename | string | Yes| User-defined heap file name. The `filename.heapsnapshot` file is generated in the `files` directory of the app based on the specified `filename`.| + +**Example** + +```js +hidebug.dumpHeapData("heap-20220216"); +``` diff --git a/en/application-dev/reference/apis/js-apis-hitracechain.md b/en/application-dev/reference/apis/js-apis-hitracechain.md index 370e48bd2a3..70ac9e5d594 100644 --- a/en/application-dev/reference/apis/js-apis-hitracechain.md +++ b/en/application-dev/reference/apis/js-apis-hitracechain.md @@ -1,6 +1,6 @@ # Distributed Call Chain Tracing -> ![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. ## Modules to Import @@ -68,20 +68,24 @@ begin(name: string, flags: number = HiTraceFlag.DEFAULT): HiTraceId Starts call chain tracing. This API works in synchronous manner. -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | name | string | Yes| Traced service name.| - | flags | number | Yes| [Trace flag combination](#hitraceflag).| -- Return value - | Type| Description| - | -------- | -------- | - | [HiTraceId](#hitraceid) | **HiTraceId** instance.| - -- Example - ``` - let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); - ``` +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Traced service name.| +| flags | number | Yes| Trace flag combination. For details, see [HiTraceFlag](#hitraceflag).| + +**Return value** + +| Type| Description| +| -------- | -------- | +| [HiTraceId](#hitraceid) | **HiTraceId** instance.| + +**Example** + +``` +let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); +``` ## hiTraceChain.end @@ -89,17 +93,19 @@ end(id: HiTraceId): void Stops call chain tracing. This API works in synchronous manner. -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| + +**Example** -- Example - ``` - let asyncTraceId = hiTraceChain.begin("business"); - // End the call chain tracing after the service logic is executed for several times. - hiTraceChain.end(asyncTraceId); - ``` +``` +let asyncTraceId = hiTraceChain.begin("business"); +// End the call chain tracing after the service logic is executed for several times. +hiTraceChain.end(asyncTraceId); +``` ## hiTraceChain.getId @@ -107,17 +113,19 @@ getId(): HiTraceId Obtains the trace ID. This API works in synchronous manner. -- Return value - | Type| Description| - | -------- | -------- | - | [HiTraceId](#hitraceid) | **HiTraceId** instance.| +**Return value** + +| Type| Description| +| -------- | -------- | +| [HiTraceId](#hitraceid) | **HiTraceId** instance.| -- Example - ``` - let traceId = hiTraceChain.begin("business"); - // Obtain the current trace ID after the service logic is executed for several times. - let curTraceId = hiTraceChain.getId(); - ``` +**Example** + +``` +let traceId = hiTraceChain.begin("business"); +// Obtain the current trace ID after the service logic is executed for several times. +let curTraceId = hiTraceChain.getId(); +``` ## hiTraceChain.setId @@ -125,17 +133,19 @@ setId(id: HiTraceId): void Sets a trace ID. This API works in synchronous manner. -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| -- Example - ``` - let traceId = hiTraceChain.begin("business"); - // Set the current trace ID after the service logic is executed for several times. - hiTraceChain.setId(asyncTraceId); - ``` +**Example** + +``` +let traceId = hiTraceChain.begin("business"); +// Set the current trace ID after the service logic is executed for several times. +hiTraceChain.setId(asyncTraceId); +``` ## hiTraceChain.clearId @@ -143,12 +153,13 @@ clearId(): void Clears the trace ID. This API works in synchronous manner. -- Example - ``` - let traceId = hiTraceChain.begin("business"); - // Clear the current trace ID after the service logic is executed for several times. - hiTraceChain.clearId(); - ``` +**Example** + +``` +let traceId = hiTraceChain.begin("business"); +// Clear the current trace ID after the service logic is executed for several times. +hiTraceChain.clearId(); +``` ## hiTraceChain.createSpan @@ -156,17 +167,19 @@ createSpan(): HiTraceId Creates a trace span. This API works in synchronous manner. -- Return value - | Type| Description| - | -------- | -------- | - | [HiTraceId](#hitraceid) | **HiTraceId** instance.| +**Return value** -- Example - ``` - let traceId = hiTraceChain.begin("business"); - // Create a trace span after the service logic is executed for several times. - let spanTraceId = hiTraceChain.createSpan(); - ``` +| Type| Description| +| -------- | -------- | +| [HiTraceId](#hitraceid) | **HiTraceId** instance.| + +**Example** + +``` +let traceId = hiTraceChain.begin("business"); +// Create a trace span after the service logic is executed for several times. +let spanTraceId = hiTraceChain.createSpan(); +``` ## hiTraceChain.tracepoint @@ -174,20 +187,22 @@ tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTr Triggers a trace point. This API works in synchronous manner. -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | mode | [HiTraceCommunicationMode](#hitracecommunicationmode) | Yes| Communication mode for the trace point.| - | type | [HiTraceTracepointType](#hitracetracepointtype)| Yes| Trace point type.| - | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance for trace point triggering.| - | msg | string | No| Trace description passed for trace point triggering.| - -- Example - ``` - let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); - // Trigger the trace point after the service logic is executed for several times. - hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, asyncTraceId, "Just a example"); - ``` +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| mode | [HiTraceCommunicationMode](#hitracecommunicationmode) | Yes| Communication mode for the trace point.| +| type | [HiTraceTracepointType](#hitracetracepointtype)| Yes| Trace point type.| +| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance for trace point triggering.| +| msg | string | No| Trace description passed for trace point triggering.| + +**Example** + +``` +let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); +// Trigger the trace point after the service logic is executed for several times. +hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, asyncTraceId, "Just a example"); +``` ## hiTraceChain.isValid @@ -195,20 +210,24 @@ isValid(id: HiTraceId): boolean Checks whether a **HiTraceId** instance is valid. This API works in synchronous manner. -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| -- Return value - | Type| Description| - | -------- | -------- | - | boolean | Returns **true** if the **HiTraceId** instance is valid; returns **false** otherwise.| - -- Example - ``` - let traceId = hiTraceChain.begin("business"); - let traceIdIsvalid = hiTraceChain.isValid(traceId); - ``` +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the **HiTraceId** instance is valid; returns **false** otherwise.| + +**Example** + +``` +let traceId = hiTraceChain.begin("business"); +let traceIdIsvalid = hiTraceChain.isValid(traceId); +``` ## hiTraceChain.isFlagEnabled @@ -216,21 +235,26 @@ isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean Checks whether the specified trace flag in the **HiTraceId** instance is enabled. This API works in synchronous manner. -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| - | flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| -- Return value - | Type| Description| - | -------- | -------- | - | boolean | Returns **true** if the specified trace flag in the **HiTraceId** instance is enabled; returns **false** otherwise.| -- Example - ``` - let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); - // The value of enabledDoNotCreateSpanFlag is true. - let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); - ``` +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| +| flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the specified trace flag in the **HiTraceId** instance is enabled; returns **false** otherwise.| + +**Example** + +``` +let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); +// The value of enabledDoNotCreateSpanFlag is true. +let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); +``` ## hiTraceChain.enableFlag @@ -238,16 +262,17 @@ enableFlag(id: HiTraceId, flag: HiTraceFlag): void Enables the specified trace flag in the **HiTraceId** instance. This API works in synchronous manner. -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| - | flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| - -- Example - ``` - let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); - hiTraceChain.enable(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); - // The value of enabledDoNotCreateSpanFlag is true. - let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); - ``` +**Parameters** +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| +| flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| + +**Example** + +``` +let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); +hiTraceChain.enable(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); +// The value of enabledDoNotCreateSpanFlag is true. +let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); +``` diff --git a/en/application-dev/reference/apis/js-apis-hitracemeter.md b/en/application-dev/reference/apis/js-apis-hitracemeter.md index fc8599f907a..14e6b745d1e 100644 --- a/en/application-dev/reference/apis/js-apis-hitracemeter.md +++ b/en/application-dev/reference/apis/js-apis-hitracemeter.md @@ -1,6 +1,6 @@ # Performance Tracing -> ![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. @@ -22,22 +22,24 @@ startTrace(name: string, taskId: number, expectedTime?: number): void Starts a trace task. **expectedTime** is an optional parameter, which specifies the expected duration of the trace. +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**. -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | name | string | Yes| Name of the trace task to start.| - | taskId | number | Yes| Task ID.| - | expectedTime | number | No| Expected duration of the trace, in ms.| +If the trace tasks with the same name are not performed at the same time, the same taskId can be used. For a specific example, refer to an example in [hiTraceMeter.finishTrace](#hitracemeterfinishtrace). - > ![icon-note.gif](public_sys-resources/icon-note.gif) **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 task ID can be used. For details, see the **hiTraceMeter.finishTrace** example. +**Parameters** -- Example - ``` - hiTraceMeter.startTrace("myTestFunc", 1); - hiTraceMeter.startTrace("myTestFunc", 1, 5); // The expected duration of the trace task is 5 ms. - ``` +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the trace task to start.| +| taskId | number | Yes| Task ID.| +| expectedTime | number | No| Expected duration of the trace, in ms.| + +**Example** + +``` +hiTraceMeter.startTrace("myTestFunc", 1); +hiTraceMeter.startTrace("myTestFunc", 1, 5); // The expected duration of the trace task is 5 ms. +``` ## hiTraceMeter.finishTrace @@ -46,42 +48,42 @@ finishTrace(name: string, taskId: number): void Stops a trace task. +To stop a trace task, the values of name and task ID in **finishTrace** must be the same as those in [startTrace](#hitracemeterstarttrace). + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the trace task to start.| +| taskId | number | Yes| Task ID.| + +**Example** + +``` +hiTraceMeter.finishTrace("myTestFunc", 1); +``` + +``` +// Start track tasks with the same name concurrently. +hiTraceMeter.startTrace("myTestFunc", 1); +// Service flow +hiTraceMeter.startTrace("myTestFunc", 2); // The second trace task starts while the first task is still running. The first and second tasks have the same name but different task IDs. +// Service flow +hiTraceMeter.finishTrace("myTestFunc", 1); +// Service flow +hiTraceMeter.finishTrace("myTestFunc", 2); +``` -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | name | string | Yes| Name of the trace task to start.| - | taskId | number | Yes| Task ID.| - - > ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:** - > To stop a trace task, the values of name and task ID in **finishTrace** must be the same as those in **startTrace**. - -- Example - ``` - hiTraceMeter.finishTrace("myTestFunc", 1); - ``` - - ``` - // Start track tasks with the same name concurrently. - hiTraceMeter.startTrace("myTestFunc", 1); - // Service flow - hiTraceMeter.startTrace("myTestFunc", 2); // The second trace task starts while the first task is still running. The first and second tasks have the same name but different task IDs. - // Service flow - hiTraceMeter.finishTrace("myTestFunc", 1); - // Service flow - hiTraceMeter.finishTrace("myTestFunc", 2); - ``` - - ``` - // Start track tasks with the same name at different times. - hiTraceMeter.startTrace("myTestFunc", 1); - // Service flow - hiTraceMeter.finishTrace("myTestFunc", 1); // The first trace task ends. - // Service flow - hiTraceMeter.startTrace("myTestFunc", 1); // The second trace task starts after the first task ends. The two tasks have the same name and task ID. - // Service flow - hiTraceMeter.finishTrace("myTestFunc", 1); - ``` +``` +// Start track tasks with the same name at different times. +hiTraceMeter.startTrace("myTestFunc", 1); +// Service flow +hiTraceMeter.finishTrace("myTestFunc", 1); // The first trace task ends. +// Service flow +hiTraceMeter.startTrace("myTestFunc", 1); // The second trace task starts after the first task ends. The two tasks have the same name and task ID. +// Service flow +hiTraceMeter.finishTrace("myTestFunc", 1); +``` ## hiTraceMeter.traceByValue @@ -90,18 +92,18 @@ traceByValue(name: string, value: number): void Traces the value changes of a variable. +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the variable.| +| value | number | Yes| Value of the variable.| -- Parameters - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | name | string | Yes| Name of the variable.| - | value | number | Yes| Value of the variable.| - -- Example - ``` - let traceCount = 3; - hiTraceMeter.traceByValue("myTestCount", traceCount); - traceCount = 4; - hiTraceMeter.traceByValue("myTestCount", traceCount); - // Service flow - ``` +**Example** +``` +let traceCount = 3; +hiTraceMeter.traceByValue("myTestCount", traceCount); +traceCount = 4; +hiTraceMeter.traceByValue("myTestCount", traceCount); +// Service flow +``` diff --git a/en/application-dev/reference/apis/js-apis-power.md b/en/application-dev/reference/apis/js-apis-power.md index 6932b76b924..6cd3cbf21a4 100644 --- a/en/application-dev/reference/apis/js-apis-power.md +++ b/en/application-dev/reference/apis/js-apis-power.md @@ -1,9 +1,10 @@ -# Power Management +# Power Management ->![](../../public_sys-resources/icon-note.gif) **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. +> ![icon-note.gif](public_sys-resources/icon-note.gif) **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 + +## Modules to Import ``` import power from '@ohos.power'; @@ -14,163 +15,94 @@ import power from '@ohos.power'; SystemCapability.PowerManager.PowerManager -## power.shutdownDevice +## power.shutdownDevice -shutdownDevice\(reason: string\): void +shutdownDevice(reason: string): void Shuts down the system. -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

reason

-

string

-

Yes

-

Reason for system shutdown.

-
- -- Example - - ``` - power.shutdownDevice("shutdown_test"); - console.info('power_shutdown_device_test success') - ``` - - -## power.rebootDevice - -rebootDevice\(reason: string\): void - -Reboots the system. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

reason

-

string

-

Yes

-

Reason for system reboot.

-
- -- Example - - ``` - power.rebootDevice("reboot_test"); - console.info('power_reboot_device_test success') - ``` - - -## power.isScreenOn - -isScreenOn\(callback: AsyncCallback\): void +Before using this API, you must declare the **ohos.permission.SHUTDOWN** permission. -Checks the screen status of the current device. +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| reason | string | Yes| Reason for system shutdown.| + +**Example** + +``` +power.shutdownDevice("shutdown_test"); +console.info('power_shutdown_device_test success') +``` + + +## power.rebootDevice -- Parameters - - - - - - - - - - - - - - -

Type

-

Type

-

Mandatory

-

Description

-

callback

-

AsyncCallback<boolean>

-

Yes

-

Callback used to obtain the return value.

-

The value true indicates that the screen is on, and value false indicates the opposite.

-
- - -- Example - - ``` - power.isScreenOn((error, screenOn) => { - if (typeof error === "undefined") { - console.info('screenOn status is ' + screenOn); - } else { - console.log('error: ' + error); - } - }) - ``` - - -## power.isScreenOn - -isScreenOn\(\): Promise +rebootDevice(reason: string): void + +Restarts the device. + +Before using this API, you must declare the **ohos.permission.REBOOT** permission (to reboot) or the **ohos.permission.REBOOT_RECOVERY** permission (to reboot and enter the recovery mode) + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| reason | string | Yes| Reason for system reboot.| + +**Example** + +``` +power.rebootDevice("reboot_test"); +console.info('power_reboot_device_test success') +``` + + +## power.isScreenOn + +isScreenOn(callback: AsyncCallback<boolean>): void Checks the screen status of the current device. -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<boolean>

-

Promise used to asynchronously obtain the return value. The value true indicates that the screen is on, and value false indicates the opposite.

-
- -- Example - - ``` - power.isScreenOn() - .then(screenOn => { +**Parameters** + +| Type| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to obtain the return value.
The value **true** indicates that the screen is on, and value **false** indicates the opposite.| + +**Example** + +``` +power.isScreenOn((error, screenOn) => { + if (typeof error === "undefined") { console.info('screenOn status is ' + screenOn); - }) - .catch(error => { + } else { console.log('error: ' + error); - }) - ``` + } +}) +``` +## power.isScreenOn + +isScreenOn(): Promise<boolean> + +Checks the screen status of the current device. + +**Return value** +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to asynchronously obtain the return value.
The value **true** indicates that the screen is on, and value **false** indicates the opposite.| + +**Example** + +``` +power.isScreenOn() +.then(screenOn => { + console.info('screenOn status is ' + screenOn); +}) +.catch(error => { + console.log('error: ' + error); +}) +``` diff --git a/en/application-dev/reference/apis/js-apis-radio.md b/en/application-dev/reference/apis/js-apis-radio.md index 0c5c2e4e316..a59cb7b5346 100644 --- a/en/application-dev/reference/apis/js-apis-radio.md +++ b/en/application-dev/reference/apis/js-apis-radio.md @@ -1,6 +1,6 @@ # Radio ->**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. @@ -19,21 +19,21 @@ Obtains the radio access technologies (RATs) used by the CS and PS domains. This Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\<{psRadioTech: [RadioTechnology](#RadioTechnology), csRadioTech:[RadioTechnology](#RadioTechnology)}\> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\<{psRadioTech: [RadioTechnology](#RadioTechnology), csRadioTech:[RadioTechnology](#RadioTechnology)}\> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - radio.getRadioTech(slotId, (err, data) =>{ - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +let slotId = 0; +radio.getRadioTech(slotId, (err, data) =>{ + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## radio.getRadioTech @@ -44,52 +44,52 @@ Obtains the RAT used by the CS and PS domains. This function uses a promise to r Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | ------------------------------------------------------------ | ----------------------------------------------- | - | Promise<{psRadioTech: [RadioTechnology](#RadioTechnology), csRadioTech: [RadioTechnology](#RadioTechnology)}> | Promise used to return the result.| +| Type| Description| +| ------------------------------------------------------------ | ----------------------------------------------- | +| Promise<{psRadioTech: [RadioTechnology](#RadioTechnology), csRadioTech: [RadioTechnology](#RadioTechnology)}> | Promise used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - let promise = radio.getRadioTech(slotId); - promise.then(data => { - console.log(`getRadioTech success, data->${JSON.stringify(data)}`); - }).catch(err => { - console.log(`getRadioTech fail, err->${JSON.stringify(err)}`); - }); - ``` +``` +let slotId = 0; +let promise = radio.getRadioTech(slotId); +promise.then(data => { + console.log(`getRadioTech success, data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getRadioTech fail, err->${JSON.stringify(err)}`); +}); +``` ## radio.getNetworkState getNetworkState\(callback: AsyncCallback\): void -Obtains the network status. This function uses an asynchronous callback to return the result. +Obtains the network status of the SIM card in the specified slot. This function uses an asynchronous callback to return the result. Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ---------------------------------------------- | ---- | ---------- | - | callback | AsyncCallback\<[NetworkState](#NetworkState)\> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | ---------------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\<[NetworkState](#NetworkState)\> | Yes| Callback invoked to traverse the entries in the container.| -- Example +**Example** - ``` - radio.getNetworkState((err, data) =>{ - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +radio.getNetworkState((err, data) =>{ + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## radio.getNetworkState @@ -100,21 +100,21 @@ Obtains the network status of the SIM card in the specified slot. This function Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ---------------------------------------------- | ---- | -------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\<[NetworkState](#NetworkState)\> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | ---------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\<[NetworkState](#NetworkState)\> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - radio.getNetworkState(slotId, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +let slotId = 0; +radio.getNetworkState(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## radio.getNetworkState @@ -125,29 +125,29 @@ Obtains the network status of the SIM card in the specified slot. This function Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | No| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | No| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | ---------------------------------------- | --------------------------- | - | Promise\<[NetworkState](#NetworkState)\> | Promise used to return the result.| +| Type| Description| +| ---------------------------------------- | --------------------------- | +| Promise\<[NetworkState](#NetworkState)\> | Promise used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - let promise = radio.getNetworkState(slotId); - promise.then(data => { - console.log(`getNetworkState success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.log(`getNetworkState fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let slotId = 0; +let promise = radio.getNetworkState(slotId); +promise.then(data => { + console.log(`getNetworkState success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getNetworkState fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## radio.getNetworkSelectionMode @@ -156,21 +156,21 @@ getNetworkSelectionMode\(slotId: number, callback: AsyncCallback - **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\<[NetworkSelectionMode](#NetworkSelectionMode)\> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\<[NetworkSelectionMode](#NetworkSelectionMode)\> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - radio.getNetworkSelectionMode(slotId, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +let slotId = 0; +radio.getNetworkSelectionMode(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## radio.getNetworkSelectionMode @@ -179,29 +179,29 @@ getNetworkSelectionMode\(slotId: number\): Promise Obtains the network selection mode of the SIM card in the specified slot. This function uses a promise to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | -------------------------------------------------------- | ------------------------------- | - | Promise\<[NetworkSelectionMode](#NetworkSelectionMode)\> | Promise used to return the result.| +| Type| Description| +| -------------------------------------------------------- | ------------------------------- | +| Promise\<[NetworkSelectionMode](#NetworkSelectionMode)\> | Promise used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - let promise = radio.getNetworkSelectionMode(slotId); - promise.then(data => { - console.log(`getNetworkSelectionMode success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.log(`getNetworkSelectionMode fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let slotId = 0; +let promise = radio.getNetworkSelectionMode(slotId); +promise.then(data => { + console.log(`getNetworkSelectionMode success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getNetworkSelectionMode fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## radio.getISOCountryCodeForNetwork7+ @@ -210,21 +210,21 @@ getISOCountryCodeForNetwork\(slotId: number, callback: AsyncCallback\): Obtains the ISO country code of the network with which the SIM card in the specified slot is registered. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ----------------------- | ---- | ---------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\ | Yes| Callback used to return the result, which is a country code, for example, **CN** (China).| +| Name| Type| Mandatory| Description| +| -------- | ----------------------- | ---- | ---------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\ | Yes| Callback used to return the result, which is a country code, for example, **CN** (China).| -- Example +**Example** - ``` - let slotId = 0; - radio.getISOCountryCodeForNetwork(slotId, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +let slotId = 0; +radio.getISOCountryCodeForNetwork(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## radio.getISOCountryCodeForNetwork7+ @@ -233,29 +233,29 @@ getISOCountryCodeForNetwork\(slotId: number\): Promise Obtains the ISO country code of the network with which the SIM card in the specified slot is registered. This function uses a promise to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | ----------------- | ------------------------------------------------------------ | - | Promise\ | Promise used to return the result, which is an ISO country code, for example, **CN** (China).| +| Type| Description| +| ----------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the result, which is an ISO country code, for example, **CN** (China).| -- Example +**Example** - ``` - let slotId = 0; - let promise = radio.getISOCountryCodeForNetwork(slotId); - promise.then(data => { - console.log(`getISOCountryCodeForNetwork success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.log(`getISOCountryCodeForNetwork fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let slotId = 0; +let promise = radio.getISOCountryCodeForNetwork(slotId); +promise.then(data => { + console.log(`getISOCountryCodeForNetwork success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getISOCountryCodeForNetwork fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## radio.getSignalInformation @@ -264,21 +264,21 @@ getSignalInformation\(slotId: number, callback: AsyncCallback - **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\\> | Yes| Callback used to return the result, which is a list of [SignalInformation](#SignalInformation) objects.| +| Name| Type| Mandatory| Description| +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\\> | Yes| Callback used to return the result, which is a list of [SignalInformation](#SignalInformation) objects.| -- Example +**Example** - ``` - let slotId = 0; - radio.getSignalInformation(slotId, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +let slotId = 0; +radio.getSignalInformation(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## radio.getSignalInformation @@ -287,78 +287,78 @@ getSignalInformation\(slotId: number\): Promise\> Obtains a list of signal strengths of the network with which the SIM card in the specified slot is registered. This function uses a promise to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | ----------------------------------------------------------- | ------------------------------------------------------------ | - | Promise\\> | Promise used to return the result, which is a list of [SignalInformation](#SignalInformation) objects.| +| Type| Description| +| ----------------------------------------------------------- | ------------------------------------------------------------ | +| Promise\\> | Promise used to return the result, which is a list of [SignalInformation](#SignalInformation) objects.| -- Example +**Example** - ``` - let slotId = 0; - let promise = radio.getSignalInformation(slotId); - promise.then(data => { - console.log(`getSignalInformation success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`getSignalInformation fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let slotId = 0; +let promise = radio.getSignalInformation(slotId); +promise.then(data => { + console.log(`getSignalInformation success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getSignalInformation fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## radio.isRadioOn7+ isRadioOn\(callback: AsyncCallback\): void -Checks whether radio is turned on. This function uses an asynchronous callback to return the result. +Checks whether the radio service is enabled. This function uses an asynchronous callback to return the result. Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ------------------------ | ---- | ------------------------------------------------------- | - | callback | AsyncCallback\ | Yes| Callback used to return the result.
- **true**: Radio is turned on.
- **false**: Radio is turned off.| +| Name| Type| Mandatory| Description| +| -------- | ------------------------ | ---- | ------------------------------------------------------- | +| callback | AsyncCallback\ | Yes| Callback used to return the result.
- **true**: The radio service is enabled.
- **false**: The radio service is disabled.| -- Example +**Example** - ``` - radio.isRadioOn((err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +radio.isRadioOn((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## radio.isRadioOn7+ isRadioOn\(\): Promise -Checks whether radio is turned on. This function uses a promise to return the result. +Checks whether the radio service is enabled. This function uses a promise to return the result. Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. -- Return values +**Return value** - | Type| Description| - | ------------------ | ------------------------------------------------------------ | - | Promise\ | Promise used to return the result.
- **true**: Radio is turned on.
- **false**: Radio is turned off.| +| Type| Description| +| ------------------ | ------------------------------------------------------------ | +| Promise\ | Promise used to return the result.
- **true**: The radio service is enabled.
- **false**: The radio service is disabled.| -- Example +**Example** - ``` - let promise = radio.isRadioOn(); - promise.then(data => { - console.log(`isRadioOn success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`isRadioOn fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = radio.isRadioOn(); +promise.then(data => { + console.log(`isRadioOn success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`isRadioOn fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## RadioTechnology @@ -394,7 +394,7 @@ Defines the signal strength. ## NetworkType -Enumerates network types. +Network type. | Variable| Value| Description| | -------------------- | ---- | ------------------------------------------------------------ | @@ -424,7 +424,7 @@ Defines the network registration status. ## RegState -Enumerates network registration states. +Defines the network registration status. | Variable| Value| Description| | ----------------------------- | ---- | -------------------------- | diff --git a/en/application-dev/reference/apis/js-apis-runninglock.md b/en/application-dev/reference/apis/js-apis-runninglock.md index 106d47b814e..beefced18a8 100644 --- a/en/application-dev/reference/apis/js-apis-runninglock.md +++ b/en/application-dev/reference/apis/js-apis-runninglock.md @@ -1,403 +1,226 @@ -# Running Lock +# Running Lock ->![icon-note.gif](public_sys-resources/icon-note.gif) **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. +> ![icon-note.gif](public_sys-resources/icon-note.gif) **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 + +## Modules to Import ``` import runninglock from '@ohos.runningLock'; ``` + ## System Capabilities SystemCapability.PowerManager.PowerManager -## RunningLockType - -Enumerates the types of running locks. - - - - - - - - - - - - - - - - -

Description

-

Default Value

-

Description

-

BACKGROUND

-

1

-

A lock that prevents the system from hibernating.

-

PROXIMITY_SCREEN_CONTROL

-

2

-

A lock that determines whether to turn on or off the screen based on the distance away from the screen.

-
- -## runninglock.isRunningLockTypeSupported - -isRunningLockTypeSupported\(type: RunningLockType, callback: AsyncCallback\): void - -Checks whether a specified type of **RunningLock** is supported. This function uses an asynchronous callback to return the result. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

type

-

RunningLockType

-

Yes

-

Type of the RunningLock object.

-

callback

-

AsyncCallback<boolean>

-

Yes

-

Callback used to obtain the return value.

-

The value true indicates that the specified type of RunningLock is supported, and value false indicates the opposite.

-
- -- Example - - ``` - runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND, (error, supported) => { - if (typeof error === "undefined") { - console.info('BACKGROUND support status is ' + supported); - } else { - console.log('error: ' + error); - } - }) - ``` - - -## runninglock.isRunningLockTypeSupported - -isRunningLockTypeSupported\(type: RunningLockType\): Promise - -Checks whether a specified type of **RunningLock** is supported. This function uses a promise to return the result. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

type

-

RunningLockType

-

Yes

-

Type of the RunningLock object.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<boolean>

-

Promise used to asynchronously obtain the return value. The value true indicates that the specified type of RunningLock is supported, and value false indicates the opposite.

-
- -- Example - - ``` - runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL) - .then(supported => { - console.info('PROXIMITY_SCREEN_CONTROL support status is ' + supported); - }) - .catch(error => { +## RunningLockType + +Enumerates the types of **RunningLock** objects. + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| BACKGROUND | 1 | Defines a **RunningLock** object.| +| PROXIMITY_SCREEN_CONTROL | 2 | A lock that determines whether to turn on or off the screen based on the distance away from the screen.| + + +## isRunningLockTypeSupported + +isRunningLockTypeSupported(type: RunningLockType, callback: AsyncCallback<boolean>): void + +Checks whether a specified type of RunningLock is supported. This function uses an asynchronous callback to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | RunningLockType | Yes| Type of the **RunningLock** object.| +| callback | AsyncCallback<boolean> | Yes| Callback used to obtain the return value.
The value **true** indicates that the specified type of **RunningLock** is supported, and value **false** indicates the opposite.| + +**Example** + +``` +runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND, (error, supported) => { + if (typeof error === "undefined") { + console.info('BACKGROUND support status is ' + supported); + } else { console.log('error: ' + error); - }); - ``` - - -## runninglock.createRunningLock - -createRunningLock\(name: string, type: RunningLockType, callback: AsyncCallback\): void - -Creates a **RunningLock** object. - -- Parameters - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

name

-

string

-

Yes

-

Name of the RunningLock object.

-

type

-

RunningLockType

-

Yes

-

Type of the RunningLock object to be created.

-

callback

-

AsyncCallback<RunningLock>

-

Yes

-

Callback used to obtain the return value.

-
- -- Example - - ``` - runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) - .then(runninglock => { - var used = runninglock.isUsed(); - console.info('runninglock is used: ' + used); - runninglock.lock(500); - used = runninglock.isUsed(); - console.info('after lock runninglock is used ' + used); - }) - .catch(error => { - console.log('create runningLock test error: ' + error); - }) - ``` - - -## runninglock.createRunningLock - -createRunningLock\(name: string, type: RunningLockType\): Promise - -Creates a **RunningLock** object. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

name

-

string

-

Yes

-

Name of the RunningLock object.

-

type

-

RunningLockType

-

Yes

-

Type of the RunningLock object to be created.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<RunningLock>

-

Promise used to asynchronously obtain the returned RunningLock object.

-
- -- Example - - ``` - runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) - .then(runninglock => { - console.info('create runningLock success'); - }) - .catch(error => { - console.log('create runningLock test error: ' + error); - }) - ``` - - -## RunningLock - -Defines a **RunningLock** object. - -### lock - -lock\(timeout: number\): void - -Locks and holds a **RunningLock** object. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

timeout

-

number

-

No

-

Duration for locking and holding the RunningLock object.

-
- -- Example - - ``` - runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) - .then(runningLock => { - runningLock.lock(100) - console.info('create runningLock success') - }) - .catch(error => { - console.log('Lock runningLock test error: ' + error) - }); - ``` - - -### unlock - -unlock\(\): void - -Releases a **Runninglock** object. - -- Example - - ``` - runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) - .then(runningLock => { - runningLock.unlock() - console.info('unLock runningLock success') - }) - .catch(error => { - console.log('unLock runningLock test error: ' + error) - }); - ``` - - -### isUsed - -isUsed\(\): boolean - -Checks the status of the **Runninglock** object. - -- Return values - - - - - - - - - - -

Type

-

Description

-

boolean

-

Returns true if the Runninglock object is held; returns false if the Runninglock object is released.

-
- -- Example - - ``` - runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) - .then(runningLock => { - var used = runningLock.isUsed() - console.info('runningLock used status: ' + used) - }) - .catch(error => { - console.log('runningLock isUsed test error: ' + error) - }); - ``` + } +}) +``` + + +## isRunningLockTypeSupported + +isRunningLockTypeSupported(type: RunningLockType): Promise<boolean> + +Checks whether a specified type of **RunningLock** is supported. This function uses an asynchronous callback to return the result. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | RunningLockType | Yes| Type of the **RunningLock** object.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to asynchronously obtain the return value. The value **true** indicates that the specified type of **RunningLock** is supported, and value **false** indicates the opposite.| + +**Example** + +``` +runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL) +.then(supported => { + console.info('PROXIMITY_SCREEN_CONTROL support status is ' + supported); +}) +.catch(error => { + console.log('error: ' + error); +}); +``` + + +## createRunningLock + +createRunningLock(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void + +Creates a **RunningLock** object. + +Before using this API, you must declare the **ohos.permission.RUNNING_LOCK** permission. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the **RunningLock** object.| +| type | RunningLockType | Yes| Type of the **RunningLock** object to be created.| +| callback | AsyncCallback<[RunningLock](#runninglock)> | Yes| Callback used to obtain the return value.| + +**Example** + +``` +runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) +.then(runninglock => { + var used = runninglock.isUsed(); + console.info('runninglock is used: ' + used); + runninglock.lock(500); + used = runninglock.isUsed(); + console.info('after lock runninglock is used ' + used); +}) +.catch(error => { + console.log('create runningLock test error: ' + error); +}) +``` + + +## createRunningLock +createRunningLock(name: string, type: RunningLockType): Promise<RunningLock> +Creates a **RunningLock** object. + +Before using this API, you must declare the **ohos.permission.RUNNING_LOCK** permission. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of the **RunningLock** object.| +| type | RunningLockType | Yes| Type of the **RunningLock** object to be created.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[RunningLock](#runninglock)> | Promise used to asynchronously obtain the returned **RunningLock** object.| + +**Example** + +``` +runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) +.then(runninglock => { + console.info('create runningLock success'); +}) +.catch(error => { + console.log('create runningLock test error: ' + error); +}) +``` + + +## RunningLock + +Defines a **RunningLock** object. + + +### lock + +lock(timeout: number): void + +Locks and holds a **RunningLock** object. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| timeout | number | No| Duration for locking and holding the **RunningLock** object.| + +**Example** + +``` +runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) +.then(runningLock => { + runningLock.lock(100) + console.info('create runningLock success') +}) +.catch(error => { + console.log('Lock runningLock test error: ' + error) +}); +``` + + +### unlock + +unlock(): void + +Releases a **Runninglock** object. + +**Example** + +``` +runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) +.then(runningLock => { + runningLock.unlock() + console.info('unLock runningLock success') +}) +.catch(error => { + console.log('unLock runningLock test error: ' + error) +}); +``` + + +### isUsed + +isUsed(): boolean + +Checks the status of the **Runninglock** object. + +**Return value** +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the **Runninglock** object is held; returns **false** if the **Runninglock** object is released.| + +**Example** + +``` +runningLock.createRunningLock("running_lock_test", runningLock.RunningLockType.BACKGROUND) +.then(runningLock => { + var used = runningLock.isUsed() + console.info('runningLock used status: ' + used) +}) +.catch(error => { + console.log('runningLock isUsed test error: ' + error) +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-sim.md b/en/application-dev/reference/apis/js-apis-sim.md index bf7ff76d158..4af4fa4a29e 100644 --- a/en/application-dev/reference/apis/js-apis-sim.md +++ b/en/application-dev/reference/apis/js-apis-sim.md @@ -1,6 +1,6 @@ # SIM Management ->**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. @@ -18,21 +18,20 @@ Obtains the integrated circuit card identity (ICCID) of the SIM card in the spe Before using this API, you must declare the **ohos.permission.GET\_TELEPHONY\_STATE** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | --------------------------- | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback<string> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | --------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback<string> | Yes| Callback used to return the result.| +**Example** -- Example - - ``` - sim.getSimIccId(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +sim.getSimIccId(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sim.getSimIccId @@ -43,28 +42,28 @@ Obtains the ICCID of the SIM card in the specified slot. This function uses a pr Before using this API, you must declare the **ohos.permission.GET\_TELEPHONY\_STATE** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | --------------------- | ---------------------------------- | - | Promise<string> | Promise used to return the result.| +| Type| Description| +| --------------------- | ---------------------------------- | +| Promise<string> | Promise used to return the result.| -- Example +**Example** - ``` - 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)}`); - }); - ``` +``` +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.getDefaultVoiceSlotId7+ @@ -72,19 +71,19 @@ getDefaultVoiceSlotId\(callback: AsyncCallback\): void Obtains the default slot ID of the SIM card that provides voice services. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | --------------------------- | ---- | ---------- | - | callback | AsyncCallback<number> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | --------------------------- | ---- | ---------- | +| callback | AsyncCallback<number> | Yes| Callback invoked to traverse the entries in the container.| -- Example +**Example** - ``` - sim.getDefaultVoiceSlotId((err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +sim.getDefaultVoiceSlotId((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sim.getDefaultVoiceSlotId7+ @@ -93,22 +92,22 @@ getDefaultVoiceSlotId\(\): Promise Obtains the default slot ID of the SIM card that provides voice services. This function uses a promise to return the result. -- Return values +**Return value** - | Type| Description| - | ----------------- | --------------------------------------- | - | Promise\ | Promise used to return the result.| +| Type| Description| +| ----------------- | --------------------------------------- | +| Promise\ | Promise used to return the result.| -- Example +**Example** - ``` - let promise = sim.getDefaultVoiceSlotId(); - promise.then(data => { - console.log(`getDefaultVoiceSlotId success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.log(`getDefaultVoiceSlotId fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = sim.getDefaultVoiceSlotId(); +promise.then(data => { + console.log(`getDefaultVoiceSlotId success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getDefaultVoiceSlotId fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## sim.getISOCountryCodeForSim @@ -116,20 +115,20 @@ getISOCountryCodeForSim\(slotId: number, callback: AsyncCallback\): voi Obtains the ISO country code of the SIM card in the specified slot. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ----------------------- | ---- | ---------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\ | Yes| Callback used to return the result, which is a country code, for example, **CN** (China).| +| Name| Type| Mandatory| Description| +| -------- | ----------------------- | ---- | ---------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\ | Yes| Callback used to return the result, which is a country code, for example, **CN** (China).| -- Example +**Example** - ``` - sim.getISOCountryCodeForSim(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +sim.getISOCountryCodeForSim(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sim.getISOCountryCodeForSim @@ -138,28 +137,28 @@ getISOCountryCodeForSim\(slotId: number\): Promise Obtains the ISO country code of the SIM card in the specified slot. This function uses a promise to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | ----------------- | ------------------------------------------------------------ | - | Promise\ | Promise used to return the result, which is a country code, for example, **CN** (China).| +| Type| Description| +| ----------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the result, which is a country code, for example, **CN** (China).| -- Example +**Example** - ``` - let promise = sim.getISOCountryCodeForSim(0); - promise.then(data => { - console.log(`getISOCountryCodeForSim success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.log(`getISOCountryCodeForSim fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = sim.getISOCountryCodeForSim(0); +promise.then(data => { + console.log(`getISOCountryCodeForSim success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getISOCountryCodeForSim fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## sim.getSimOperatorNumeric @@ -168,20 +167,20 @@ getSimOperatorNumeric\(slotId: number, callback: AsyncCallback\): void Obtains the public land mobile network (PLMN) ID of the SIM card in the specified slot. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ----------------------- | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\ | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | ----------------------- | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| -- Example +**Example** - ``` - sim.getSimOperatorNumeric(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +sim.getSimOperatorNumeric(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sim.getSimOperatorNumeric @@ -190,28 +189,28 @@ getSimOperatorNumeric\(slotId: number\): Promise Obtains the PLMN ID of the SIM card in the specified slot. This function uses a promise to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | ----------------- | ------------------------------------------------ | - | Promise\ | Promise used to return the result.| +| Type| Description| +| ----------------- | ------------------------------------------------ | +| Promise\ | Promise used to return the result.| -- Example +**Example** - ``` - let promise = sim.getSimOperatorNumeric(0); - promise.then(data => { - console.log(`getSimOperatorNumeric success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.log(`getSimOperatorNumeric fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = sim.getSimOperatorNumeric(0); +promise.then(data => { + console.log(`getSimOperatorNumeric success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getSimOperatorNumeric fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## sim.getSimSpn @@ -220,20 +219,20 @@ getSimSpn\(slotId: number, callback: AsyncCallback\): void Obtains the service provider name (SPN) of the SIM card in the specified slot. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ----------------------- | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\ | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | ----------------------- | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| -- Example +**Example** - ``` - sim.getSimSpn(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +sim.getSimSpn(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sim.getSimSpn @@ -242,28 +241,28 @@ getSimSpn\(slotId: number\): Promise Obtains the SPN of the SIM card in the specified slot. This function uses a promise to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | ----------------- | ----------------------------------------- | - | Promise\ | Promise used to return the result.| +| Type| Description| +| ----------------- | ----------------------------------------- | +| Promise\ | Promise used to return the result.| -- Example +**Example** - ``` - let promise = sim.getSimSpn(0); - promise.then(data => { - console.log(`getSimSpn success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.log(`getSimSpn fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = sim.getSimSpn(0); +promise.then(data => { + console.log(`getSimSpn success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getSimSpn fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## sim.getSimState @@ -272,20 +271,20 @@ getSimState\(slotId: number, callback: AsyncCallback\): void Obtains the status of the SIM card in the specified slot. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------------------------------------- | ---- | ----------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\<[SimState](#SimState)\> | Yes| Callback used to return the result. For details, see [SimState](#SimState).| +| Name| Type| Mandatory| Description| +| -------- | -------------------------------------- | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\<[SimState](#SimState)\> | Yes| Callback used to return the result, For details, see [SimState](#SimState).| -- Example +**Example** - ``` - sim.getSimState(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +sim.getSimState(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sim.getSimState @@ -294,28 +293,28 @@ getSimState\(slotId: number\): Promise Obtains the status of the SIM card in the specified slot. This function uses a promise to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | -------------------------------- | ------------------------------------------ | - | Promise\<[SimState](#SimState)\> | Promise used to return the result.| +| Type| Description| +| -------------------------------- | ------------------------------------------ | +| Promise\<[SimState](#SimState)\> | Promise used to return the result.| -- Example +**Example** - ``` - let promise = sim.getSimState(0); - promise.then(data => { - console.log(`getSimState success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.log(`getSimState fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = sim.getSimState(0); +promise.then(data => { + console.log(`getSimState success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getSimState fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## sim.getSimGid1 @@ -325,20 +324,20 @@ Obtains the group identifier level 1 (GID1) of the SIM card in the specified slo Before using this API, you must declare the **ohos.permission.GET\_TELEPHONY\_STATE** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ----------------------- | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback\ | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | ----------------------- | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| -- Example +**Example** - ``` - sim.getSimGid1(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +sim.getSimGid1(0, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sim.getSimGid1 @@ -349,28 +348,28 @@ Obtains the GID1 of the SIM card in the specified slot. This function uses a pro Before using this API, you must declare the **ohos.permission.GET\_TELEPHONY\_STATE** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | -------------------------------------- | - | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | ----------------- | ------------------------------------------------------------ | - | Promise\ | Promise used to return the result.| +| Type| Description| +| ----------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the result.| -- Example +**Example** - ``` - 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)}`); - }); - ``` +``` +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)}`); +}); +``` ## SimState diff --git a/en/application-dev/reference/apis/js-apis-sms.md b/en/application-dev/reference/apis/js-apis-sms.md index d1e0be717b9..65fcef6b4fb 100644 --- a/en/application-dev/reference/apis/js-apis-sms.md +++ b/en/application-dev/reference/apis/js-apis-sms.md @@ -1,6 +1,6 @@ # SMS ->**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. @@ -16,24 +16,24 @@ createMessage\(pdu: Array, specification: string, callback: AsyncCallba Creates an SMS message instance based on the protocol data unit (PDU) and the specified SMS protocol. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | - | pdu | Array<number> | Yes| Protocol data unit, which is obtained from the received SMS message.| - | specification | string | Yes| SMS protocol type. The options are as follows:
- **3gpp**: GSM/UMTS/LTE SMS
- **3gpp2**: CDMA SMS| - | callback | AsyncCallback<[ShortMessage](#ShortMessage)> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| ------------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | +| pdu | Array<number> | Yes| PDU, which is obtained from the received SMS message.| +| specification | string | Yes| SMS protocol type. The options are as follows:
- **3gpp**: GSM/UMTS/LTE SMS
- **3gpp2**: CDMA SMS| +| callback | AsyncCallback<[ShortMessage](#ShortMessage)> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - const specification = '3gpp'; - // Display PDUs using numbers in an array, for example, [0x08, 0x91, ...]. - const pdu = [0x08, 0x91]; - sms.createMessage(pdu, specification, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +const specification = '3gpp'; +// Display PDUs using numbers in an array, for example, [0x08, 0x91, ...]. +const pdu = [0x08, 0x91]; +sms.createMessage(pdu, specification, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sms.createMessage @@ -42,32 +42,32 @@ createMessage\(pdu: Array, specification: string\): Promise - **3gpp**: GSM/UMTS/LTE SMS
- **3gpp2**: CDMA SMS| +| Name| Type| Mandatory| Description| +| ------------- | ------------------- | ---- | ------------------------------------------------------------ | +| pdu | Array<number> | Yes| PDU, which is obtained from the received SMS message.| +| specification | string | Yes| SMS protocol type. The options are as follows:
- **3gpp**: GSM/UMTS/LTE SMS
- **3gpp2**: CDMA SMS| -- Return values +**Return value** - | Type| Description| - | -------------------------------------------- | --------------------------------- | - | Promise<[ShortMessage](#ShortMessage)> | Promise used to return the result.| +| Type| Description| +| -------------------------------------------- | --------------------------------- | +| Promise<[ShortMessage](#ShortMessage)> | Promise used to return the result.| -- Example +**Example** - ``` - const specification = '3gpp'; - // Display PDUs using numbers in an array, for example, [0x08, 0x91, ...]. - const pdu = [0x08, 0x91]; - let promise = sms.createMessage(pdu, specification); - promise.then(data => { - console.log(`createMessage success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`createMessage fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +const specification = '3gpp'; +// Display PDUs using numbers in an array, for example, [0x08, 0x91, ...]. +const pdu = [0x08, 0x91]; +let promise = sms.createMessage(pdu, specification); +promise.then(data => { + console.log(`createMessage success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`createMessage fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## sms.sendMessage @@ -77,29 +77,29 @@ Sends an SMS message. Before using this API, you must declare the **ohos.permission.SEND_MESSAGES** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | - | options | [SendMessageOptions](#SendMessageOptions) | Yes| Options (including the callback) for sending an SMS message. For details, see [SendMessageOptions](#SendMessageOptions).| +| Name| Type| Mandatory| Description| +| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| options | [SendMessageOptions](#SendMessageOptions) | Yes| Options (including the callback) for sending an SMS message. For details, see [SendMessageOptions](#SendMessageOptions).| -- Example +**Example** - ``` - let sendCallback = function (err, data) { - console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - } - let deliveryCallback = function (err, data) { - console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - } - let slotId = 0; - let content ='SMS message content'; - let destinationHost = '+861xxxxxxxxxx'; - let serviceCenter = '+861xxxxxxxxxx'; - let destinationPort = 1000; - let options = {slotId, content, destinationHost, serviceCenter, destinationPort, sendCallback, deliveryCallback}; - sms.sendMessage(options); - ``` +``` +let sendCallback = function (err, data) { + console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +} +let deliveryCallback = function (err, data) { + console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +} +let slotId = 0; +let content ='SMS message content'; +let destinationHost = '+861xxxxxxxxxx'; +let serviceCenter = '+861xxxxxxxxxx'; +let destinationPort = 1000; +let options = {slotId, content, destinationHost, serviceCenter, destinationPort, sendCallback, deliveryCallback}; +sms.sendMessage(options); +``` ## sms.getDefaultSmsSlotId7+ @@ -108,19 +108,19 @@ getDefaultSmsSlotId\(callback: AsyncCallback\): void Obtains the default slot of the SIM card used to send SMS messages. This function uses an asynchronous callback to return the result. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | --------------------------- | ---- | ---------------------------------------- | - | callback | AsyncCallback<number> | Yes| Callback used to return the result.
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| -------- | --------------------------- | ---- | ---------------------------------------- | +| callback | AsyncCallback<number> | Yes| Callback used to return the result,
- **0**: slot 1
- **1**: slot 2| -- Example +**Example** - ``` - sms.getDefaultSmsSlotId((err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +sms.getDefaultSmsSlotId((err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sms.getDefaultSmsSlotId7+ @@ -129,22 +129,22 @@ getDefaultSmsSlotId\(\): Promise Obtains the default slot of the SIM card used to send SMS messages. This function uses a promise to return the result. -- Return values +**Return value** - | Type| Description| - | --------------- | ------------------------------------------------------------ | - | Promise | Promise used to return the result.
- **0**: slot 1
- **1**: slot 2| +| Type| Description| +| --------------- | ------------------------------------------------------------ | +| Promise | Promise used to return the result.
- **0**: slot 1
- **1**: slot 2| -- Example +**Example** - ``` - let promise = call.getDefaultSmsSlotId(); - promise.then(data => { - console.log(`getDefaultSmsSlotId success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`getDefaultSmsSlotId fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let promise = call.getDefaultSmsSlotId(); +promise.then(data => { + console.log(`getDefaultSmsSlotId success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getDefaultSmsSlotId fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## sms.setSmscAddr7+ @@ -155,23 +155,23 @@ Sets the short message service center (SMSC) address. This function uses an asyn Before using this API, you must declare the **ohos.permission.SET\_TELEPHONY\_STATE** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ------------------------- | ---- | ----------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | smscAddr | string | Yes| SMSC address. | - | callback | AsyncCallback<void> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | ------------------------- | ---- | ----------------------------------------- | +| slotId | number | Yes| SIM card slot ID:
- **0**: slot 1
- **1**: slot 2| +| smscAddr | string | Yes| SMSC address. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - let smscAddr = '+861xxxxxxxxxx'; - sms.setSmscAddr(slotId, smscAddr, (err,data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +let slotId = 0; +let smscAddr = '+861xxxxxxxxxx'; +sms.setSmscAddr(slotId, smscAddr, (err,data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sms.setSmscAddr7+ @@ -182,31 +182,31 @@ Sets the SMSC address. This function uses a promise to return the result. Before using this API, you must declare the **ohos.permission.SET\_TELEPHONY\_STATE** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | ------ | ---- | ----------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | smscAddr | string | Yes| SMSC address.| +| Name| Type| Mandatory| Description| +| -------- | ------ | ---- | ----------------------------------------- | +| slotId | number | Yes| SIM card slot ID:
- **0**: slot 1
- **1**: slot 2| +| smscAddr | string | Yes| SMSC address. | -- Return values +**Return value** - | Type| Description| - | ------------------- | ------------------------------- | - | Promise<void> | Promise used to return the result.| +| Type| Description| +| ------------------- | ------------------------------- | +| Promise<void> | Promise used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - let smscAddr = '+861xxxxxxxxxx'; - let promise = sms.setSmscAddr(slotId, smscAddr); - promise.then(data => { - console.log(`setSmscAddr success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`setSmscAddr fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let slotId = 0; +let smscAddr = '+861xxxxxxxxxx'; +let promise = sms.setSmscAddr(slotId, smscAddr); +promise.then(data => { + console.log(`setSmscAddr success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`setSmscAddr fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## sms.getSmscAddr7+ @@ -217,21 +217,21 @@ Obtains the SMSC address. This function uses an asynchronous callback to return Before using this API, you must declare the **ohos.permission.GET\_TELEPHONY\_STATE** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | -------- | --------------------------- | ---- | ----------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| - | callback | AsyncCallback<string> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | --------------------------- | ---- | ----------------------------------------- | +| slotId | number | Yes| SIM card slot ID:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback<string> | Yes| Callback used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - sms.getSmscAddr(slotId, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); - }); - ``` +``` +let slotId = 0; +sms.getSmscAddr(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` ## sms.getSmscAddr7+ @@ -242,29 +242,29 @@ Obtains the SMSC address. This function uses a promise to return the result. Before using this API, you must declare the **ohos.permission.GET\_TELEPHONY\_STATE** permission. -- Parameters +**Parameters** - | Name| Type| Mandatory| Description| - | ------ | ------ | ---- | ----------------------------------------- | - | slotId | number | Yes| SIM card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | ----------------------------------------- | +| slotId | number | Yes| SIM card slot ID:
- **0**: slot 1
- **1**: slot 2| -- Return values +**Return value** - | Type| Description| - | --------------------- | --------------------------------------------- | - | Promise<string> | Promise used to return the result.| +| Type| Description| +| --------------------- | --------------------------------------------- | +| Promise<string> | Promise used to return the result.| -- Example +**Example** - ``` - let slotId = 0; - let promise = sms.getSmscAddr(slotId); - promise.then(data => { - console.log(`getSmscAddr success, promise: data->${JSON.stringify(data)}`); - }).catch(err => { - console.error(`getSmscAddr fail, promise: err->${JSON.stringify(err)}`); - }); - ``` +``` +let slotId = 0; +let promise = sms.getSmscAddr(slotId); +promise.then(data => { + console.log(`getSmscAddr success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.error(`getSmscAddr fail, promise: err->${JSON.stringify(err)}`); +}); +``` ## ShortMessage @@ -281,13 +281,13 @@ Defines an SMS message instance. | isSmsStatusReportMessage | boolean | Whether the received SMS message is an SMS delivery status report. The default value is **false**.
SMS delivery status report: a message sent from the SMSC to show the current status of the SMS message you delivered.| | messageClass | [ShortMessageClass](#ShortMessageClass) | SMS message type.| | pdu | Array<number> | PDU in the SMS message.| -|protocolId|number|Protocol identifier used for delivering the SMS message.| -|scAddress|string|SMSC address.| -|scTimestamp|number|SMSC timestamp.| -|status|number|SMS message status sent by the SMSC in the **SMS-STATUS-REPORT** message.| -|userRawData|Array<number>|User data excluding the data header.| -|visibleMessageBody|string|SMS message body.| -|visibleRawAddress|string|Sender address to be displayed on the UI.| +| protocolId | number | ID of the protocol used for sending SMS messages.| +| scAddress | string | Address of the short message service center (SMSC).| +| scTimestamp | number | SMSC timestamp.| +| status | number | SMS message status sent by the SMSC in the **SMS-STATUS-REPORT** message.| +| userRawData | Array<number> | User data except the data header.| +| visibleMessageBody | string | SMS message body.| +| visibleRawAddress | string | Sender address.| ## ShortMessageClass @@ -315,7 +315,7 @@ For example, you can specify the SMS message type by the optional parameter **co | destinationHost | string | Yes| Destination address of the SMS message.| | content | string \| Array<number> | Yes| SMS message type. If the content is comprised of character strings, the SMS message is a text message. If the content is comprised of byte arrays, the SMS message is a data message.| | serviceCenter | string | No| SMSC address. By default, the SMSC address in the SIM card is used.| -| destinationPort | number | No| Destination port of the SMS message. This parameter is mandatory only for a data message. | +| destinationPort | number | No| Destination port of the SMS message. This parameter is mandatory only for a data message. Otherwise, it is optional.| | sendCallback | AsyncCallback<[ISendShortMessageCallback](#ISendShortMessageCallback)> | No| Callback used to return the SMS message sending result. For details, see [ISendShortMessageCallback](#ISendShortMessageCallback).| | deliveryCallback | AsyncCallback<[IDeliveryShortMessageCallback](#IDeliveryShortMessageCallback)> | No| Callback used to return the SMS message delivery report. For details, see [IDeliveryShortMessageCallback](#IDeliveryShortMessageCallback).| @@ -333,7 +333,7 @@ Provides the callback for the SMS message delivery report. It consists of three ## IDeliveryShortMessageCallback -Provides the callback for the SMS message delivery report. +Provides the callback for the SMS message delivery report. Return the SMS delivery report. | Name| Type| Mandatory| Description| | ------ | ------------------- | ---- | -------------- | @@ -346,7 +346,7 @@ Enumerates SMS message sending results. | Name| Value| Description| | ------------------------------------ | ---- | ------------------------------------------------------ | -| SEND_SMS_SUCCESS | 0 | The SMS message is sent successfully.| +| SEND_SMS_SUCCESS | 0 | SMS message sent successfully.| | SEND_SMS_FAILURE_UNKNOWN | 1 | Failed to send the SMS message due to unknown reasons.| | 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.| -- Gitee