diff --git a/en/application-dev/faqs/Readme-EN.md b/en/application-dev/faqs/Readme-EN.md index 7eb9cad6b546996a47e92cd01b03f783a1f4a6d2..63535a32ae16eca13b03d20b4bce93569e2fe1d0 100644 --- a/en/application-dev/faqs/Readme-EN.md +++ b/en/application-dev/faqs/Readme-EN.md @@ -18,5 +18,4 @@ - [Native API Usage](faqs-native.md) - [Usage of Third- and Fourth-Party Libraries](faqs-third-party-library.md) - [IDE Usage](faqs-ide.md) -- [hdc_std Command Usage](faqs-hdc-std.md) - [Development Board](faqs-development-board.md) \ No newline at end of file diff --git a/en/application-dev/faqs/faqs-hdc-std.md b/en/application-dev/faqs/faqs-hdc-std.md deleted file mode 100644 index 60f93da61d7d78a4e148b65c0e30d379b1e1206d..0000000000000000000000000000000000000000 --- a/en/application-dev/faqs/faqs-hdc-std.md +++ /dev/null @@ -1,87 +0,0 @@ -# hdc_std Command Usage - -## Common Log Commands - -Applicable to: OpenHarmony SDK 3.2.2.5 - -Clearing logs: hdc_std shell hilog -r - -Increasing the buffer size to 20 MB: hdc_std shell hilog -G 20M - -Capturing logs: hdc_std shell hilog > log.txt - -## What should I do to avoid log flow control? - -Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9 - -- Disabling log flow control: hdc_std shell hilog -Q pidoff - -- Disabling the privacy flag: hdc_std shell hilog -p off - -- Increasing the log buffer to 200 MB: hdc_std shell hilog -G 200M - -- Enabling the log function of the specific domain (that is, disabling the global log function): hdc_std shell hilog –b D –D 0xd0xxxxx - -After performing the preceding operations, restart the DevEco Studio. - -## What should I do if the HAP installed on the development board through the IDE cannot be opened? - -Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9 - -Check whether the SDK version is consistent with the system version on the development board. You are advised to use the SDK version and system version that are released on the same day. - -## How do I upload files using the hdc command? - -Applicable to: OpenHarmony SDK 3.2.2.5 - -Run the **hdc_std file send** command. - -## How do I prevent the screen of the RK3568 development board from turning off? - -Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9 - -Run the **hdc_std shell "power-shell setmode 602"** command. - -## How do I start an ability using the hdc command? - -Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9 - -Run the **hdc\_std shell aa start -a AbilityName -b bundleName -m moduleName** command. - -## How do I change the read and write permissions on a file directory on the development board? - -Applicable to: OpenHarmony SDK 3.2.5.6, stage model of API version 9 - -Run the **hdc\_std shell mount -o remount,rw /** command. - -## What should I do if the error message "Unknown file option -r" is displayed when hdc_std file recv is run? - -Applicable to: OpenHarmony SDK 3.2.5.6, stage model of API version 9 - -1. Use the the hdc tool in the device image or SDK of the same version. - -2. Remove any Chinese characters or spaces from the directory specified for the hdc tool. - -## How do I uninstall an application using the hdc command? - -Applicable to: OpenHarmony SDK 3.2.2.5 - -Run the **hdc\_std uninstall [-k] [package_name]** command. - -## How do I check whether the system is 32-bit or 64-bit? - -Applicable to: OpenHarmony SDK 3.2.5.5 - -Run the **hdc\_std shell getconf LONG_BIT** command. - -If **64** is returned, the system is a 64-bit one. Otherwise, the system is a 32-bit one. - -## How do I view the component tree structure? - -Applicable to: OpenHarmony SDK 3.2.5.5 - -1. Run the **hdc\_std shell** command to launch the CLI. - -2. Run the **aa dump -a** command to find **abilityID**. - -3. Run the **aa dump -i [abilityID] -c -render** command to view the component tree. diff --git a/en/application-dev/reference/apis/js-apis-call.md b/en/application-dev/reference/apis/js-apis-call.md index 8c8be8e633e1d86f38b342be5a1c8586e1b62fac..12ebe7c4d1a7fdb84ca8af45cd0efc2fb74bda6c 100644 --- a/en/application-dev/reference/apis/js-apis-call.md +++ b/en/application-dev/reference/apis/js-apis-call.md @@ -14,110 +14,6 @@ To subscribe to the call status, use [`observer.on('callStateChange')`](js-apis- import call from '@ohos.telephony.call'; ``` -## call.dial(deprecated) - -dial\(phoneNumber: string, callback: AsyncCallback\): void - -Initiates a call. This API uses an asynchronous callback to return the result. - ->**NOTE** -> ->This parameter is supported since API version 6 and deprecated since API version 9. You are advised to use [dialCall](#calldialcall9). - -**Required Permissions**: ohos.permission.PLACE_CALL - -**System capability**: SystemCapability.Telephony.CallManager - -**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** - -```js -call.dial("138xxxxxxxx", (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); -}); -``` - - -## call.dial(deprecated) - -dial\(phoneNumber: string, options: DialOptions, callback: AsyncCallback\): void - -Initiates a call. You can set call options as needed. This API uses an asynchronous callback to return the result. - ->**NOTE** -> ->This parameter is supported since API version 6 and deprecated since API version 9. You are advised to use [dialCall](#calldialcall9). - -**Required Permissions**: ohos.permission.PLACE_CALL - -**System capability**: SystemCapability.Telephony.CallManager - -**Parameters** - -| Name | Type | Mandatory| Description | -| ----------- | ---------------------------- | ---- | --------------------------------------- | -| phoneNumber | string | Yes | Phone number. | -| options | [DialOptions](#dialoptions) | Yes | Call option, which indicates whether the call is a voice call or video call. | -| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.
- **true**: success
- **false**: failure| - -**Example** - -```js -call.dial("138xxxxxxxx", { - extras: false -}, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); -}); -``` - - -## call.dial(deprecated) - -dial\(phoneNumber: string, options?: DialOptions\): Promise - -Initiates a call. You can set call options as needed. This API uses a promise to return the result. - ->**NOTE** -> ->This parameter is supported since API version 6 and deprecated since API version 9. You are advised to use [dialCall](#calldialcall9). - -**Required Permissions**: ohos.permission.PLACE_CALL - -**System capability**: SystemCapability.Telephony.CallManager - -**Parameters** - -| Name | Type | Mandatory| Description | -| ----------- | --------------------------- | ---- | -------------------------------------- | -| phoneNumber | string | Yes | Phone number. | -| options | [DialOptions](#dialoptions) | No | Call option, which indicates whether the call is a voice call or video call.| - -**Return value** - -| Type | Description | -| ---------------------- | ------------------------------------------------------------ | -| Promise<boolean> | Promise used to return the result.
- **true**: success
- **false**: failure| - -**Example** - -```js -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.dialCall9+ dialCall\(phoneNumber: string, callback: AsyncCallback\): void @@ -158,7 +54,6 @@ call.dialCall("138xxxxxxxx", (err) => { }); ``` - ## call.dialCall9+ dialCall\(phoneNumber: string, options: DialCallOptions, callback: AsyncCallback\): void @@ -205,7 +100,6 @@ call.dialCall("138xxxxxxxx", { }); ``` - ## call.dialCall9+ dialCall\(phoneNumber: string, options?: DialCallOptions\): Promise @@ -260,6 +154,108 @@ promise.then(() => { }); ``` +## call.dial(deprecated) + +dial\(phoneNumber: string, callback: AsyncCallback\): void + +Initiates a call. This API uses an asynchronous callback to return the result. + +>**NOTE** +> +> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [dialCall](#calldialcall9). The substitute API is available only for system applications. + +**Required Permissions**: ohos.permission.PLACE_CALL + +**System capability**: SystemCapability.Telephony.CallManager + +**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** + +```js +call.dial("138xxxxxxxx", (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.dial(deprecated) + +dial\(phoneNumber: string, options: DialOptions, callback: AsyncCallback\): void + +Initiates a call. You can set call options as needed. This API uses an asynchronous callback to return the result. + +>**NOTE** +> +> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [dialCall](#calldialcall9). The substitute API is available only for system applications. + +**Required Permissions**: ohos.permission.PLACE_CALL + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ---------------------------- | ---- | --------------------------------------- | +| phoneNumber | string | Yes | Phone number. | +| options | [DialOptions](#dialoptions) | Yes | Call option, which indicates whether the call is a voice call or video call. | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.
- **true**: success
- **false**: failure| + +**Example** + +```js +call.dial("138xxxxxxxx", { + extras: false +}, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.dial(deprecated) + +dial\(phoneNumber: string, options?: DialOptions\): Promise + +Initiates a call. You can set call options as needed. This API uses a promise to return the result. + +>**NOTE** +> +> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [dialCall](#calldialcall9). The substitute API is available only for system applications. + +**Required Permissions**: ohos.permission.PLACE_CALL + +**System capability**: SystemCapability.Telephony.CallManager + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | --------------------------- | ---- | -------------------------------------- | +| phoneNumber | string | Yes | Phone number. | +| options | [DialOptions](#dialoptions) | No | Call option, which indicates whether the call is a voice call or video call.| + +**Return value** + +| Type | Description | +| ---------------------- | ------------------------------------------------------------ | +| Promise<boolean> | Promise used to return the result.
- **true**: success
- **false**: failure| + +**Example** + +```js +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.makeCall7+ diff --git a/en/application-dev/reference/apis/js-apis-contact.md b/en/application-dev/reference/apis/js-apis-contact.md index bcc8b36fc9a93191258ed78edb68df61ccce4c28..c2386b6d6755e4268aa5830a89a87403ce18a533 100644 --- a/en/application-dev/reference/apis/js-apis-contact.md +++ b/en/application-dev/reference/apis/js-apis-contact.md @@ -488,8 +488,6 @@ selectContact(callback: AsyncCallback<Array<Contact>>): void Selects a contact. This API uses an asynchronous callback to return the result. -**Permission required**: ohos.permission.READ_CONTACTS - **System capability**: SystemCapability.Applications.Contacts **Parameters** @@ -517,8 +515,6 @@ selectContact(): Promise<Array<Contact>> Selects a contact. This API uses a promise to return the result. -**Permission required**: ohos.permission.READ_CONTACTS - **System capability**: SystemCapability.Applications.Contacts **Return Value** diff --git a/en/application-dev/reference/apis/js-apis-hichecker.md b/en/application-dev/reference/apis/js-apis-hichecker.md index 7dc240114cbcb7d3b5511f4bd8dd8f884c4cef71..35c86ccd1c0143dea06b5f1a24634b6cc09a2187 100644 --- a/en/application-dev/reference/apis/js-apis-hichecker.md +++ b/en/application-dev/reference/apis/js-apis-hichecker.md @@ -1,8 +1,9 @@ # @ohos.hichecker (HiChecker) -The **hichecker** module is provided for you to check issues that may be easily ignored during development of OpenHarmony applications (including system-built and third-party applications). Such issues include calling of time-consuming functions by key application threads, event distribution and execution timeout in application processes, and ability resource leakage in application processes. The issues are recorded in logs or lead to process crashes explicitly so that you can find and rectify them. +The HiChecker module allows you to check issues that may be easily ignored during development of applications (including system-built and third-party applications). Such issues include calling of time-consuming functions by key application threads, event distribution and execution timeout in application processes, and ability resource leakage in application processes. The issues are recorded in logs or lead to process crashes explicitly so that you can find and rectify them. -> **NOTE**
+> **NOTE** +> > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -13,7 +14,7 @@ import hichecker from '@ohos.hichecker'; ``` -## Constant +## Constants Provides the constants of all rule types. @@ -26,10 +27,8 @@ Provides the constants of all rule types. | RULE_THREAD_CHECK_SLOW_PROCESS | bigint | Caution rule, which is programmed to detect whether any time-consuming function is invoked. | | RULE_CHECK_ABILITY_CONNECTION_LEAK | bigint | Caution rule, which is programmed to detect whether ability leakage has occurred. | - ## hichecker.addCheckRule9+ -## hichecker.addRule addCheckRule(rule: bigint): void Adds one or more rules. HiChecker detects unexpected operations or gives feedback based on the added rules. @@ -121,12 +120,12 @@ try { ## hichecker.addRule(deprecated) -## hichecker.addRule - -> **NOTE**
This API is deprecated since API version 9. You are advised to use [hichecker.addCheckRule](#hicheckeraddcheckrule9) instead. - addRule(rule: bigint): void +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [hichecker.addCheckRule](#hicheckeraddcheckrule9). + Adds one or more rules. HiChecker detects unexpected operations or gives feedback based on the added rules. **System capability**: SystemCapability.HiviewDFX.HiChecker @@ -152,7 +151,9 @@ hichecker.addRule( removeRule(rule: bigint): void -> **NOTE**
This API is deprecated since API version 9. You are advised to use [hichecker.removeCheckRule](#hicheckerremovecheckrule9) instead. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [hichecker.removeCheckRule](#hicheckerremovecheckrule9). Removes one or more rules. The removed rules will become ineffective. @@ -203,7 +204,9 @@ hichecker.getRule(); // return 1n; contains(rule: bigint): boolean -> **NOTE**
This API is deprecated since API version 9. You are advised to use [hichecker.containsCheckRule](#hicheckercontainscheckrule9) instead. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [hichecker.containsCheckRule](#hicheckercontainscheckrule9). 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. diff --git a/en/application-dev/reference/apis/js-apis-http.md b/en/application-dev/reference/apis/js-apis-http.md index 0e443e4668decb55ed3036022ef3567d69d495bd..b956565ee8dd1e03a12c4a81b389cf7087802e7b 100644 --- a/en/application-dev/reference/apis/js-apis-http.md +++ b/en/application-dev/reference/apis/js-apis-http.md @@ -336,7 +336,7 @@ on(type: 'headerReceive', callback: AsyncCallback\): void Registers an observer for HTTP Response Header events. >**NOTE** ->This API has been deprecated. You are advised to use [on('headersReceive')8+](#onheadersreceive8) instead. +>This API has been deprecated. You are advised to use [on('headersReceive')8+](#onheadersreceive8). **System capability**: SystemCapability.Communication.NetStack @@ -363,7 +363,7 @@ Unregisters the observer for HTTP Response Header events. >**NOTE** > ->1. This API has been deprecated. You are advised to use [off('headersReceive')8+](#offheadersreceive8) instead. +>1. This API has been deprecated. You are advised to use [off('headersReceive')8+](#offheadersreceive8). > >2. You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. diff --git a/en/application-dev/reference/apis/js-apis-net-connection.md b/en/application-dev/reference/apis/js-apis-net-connection.md index efa97d016e1c37edc0c5a7c681d823265b767d36..1e6f83b64a91d36533586c46ddef8f7c6e05a1e4 100644 --- a/en/application-dev/reference/apis/js-apis-net-connection.md +++ b/en/application-dev/reference/apis/js-apis-net-connection.md @@ -275,8 +275,8 @@ Binds an application to the specified network, so that the application can acces ```js connection.getDefaultNet().then(function (netHandle) { - connection.setAppNet(netHandle).then((error, data) => { - console.log(JSON.stringify(data)) + connection.setAppNet(netHandle).then(() => { + console.log("success") }).catch(error => { console.log(JSON.stringify(error)) }) @@ -936,7 +936,7 @@ getAddressesByName(host: string, callback: AsyncCallback\>): Resolves the host name by using the default network to obtain all IP addresses. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.GET_NETWORK_INFO +**Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.Communication.NetManager.Core @@ -973,7 +973,7 @@ getAddressesByName(host: string): Promise\> Resolves the host name by using the default network to obtain all IP addresses. This API uses a promise to return the result. -**Required permission**: ohos.permission.GET_NETWORK_INFO +**Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.Communication.NetManager.Core @@ -1478,7 +1478,7 @@ getAddressesByName(host: string, callback: AsyncCallback\>): Resolves the host name by using the corresponding network to obtain all IP addresses. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.GET_NETWORK_INFO +**Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.Communication.NetManager.Core @@ -1517,7 +1517,7 @@ getAddressesByName(host: string): Promise\> Resolves the host name by using the corresponding network to obtain all IP addresses. This API uses a promise to return the result. -**Required permission**: ohos.permission.GET_NETWORK_INFO +**Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.Communication.NetManager.Core @@ -1560,7 +1560,7 @@ getAddressByName(host: string, callback: AsyncCallback\): void Resolves the host name by using the corresponding network to obtain the first IP address. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.GET_NETWORK_INFO +**Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.Communication.NetManager.Core @@ -1599,7 +1599,7 @@ getAddressByName(host: string): Promise\ Resolves the host name by using the corresponding network to obtain the first IP address. This API uses a promise to return the result. -**Required permission**: ohos.permission.GET_NETWORK_INFO +**Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.Communication.NetManager.Core diff --git a/en/application-dev/reference/apis/js-apis-radio.md b/en/application-dev/reference/apis/js-apis-radio.md index 59a98be8dee948023e3fe8baac94605b82d767f8..15c1fc484dd8987dd26c9229beeb200ba8a711e9 100644 --- a/en/application-dev/reference/apis/js-apis-radio.md +++ b/en/application-dev/reference/apis/js-apis-radio.md @@ -10,7 +10,7 @@ The **radio** module provides basic network search management functions. You can ## Modules to Import ``` -import radio from '@ohos.telephony.radio' +import radio from '@ohos.telephony.radio'; ``` ## radio.getRadioTech @@ -31,6 +31,7 @@ Obtains the RAT used in the CS and PS domains for the SIM card in the specified | callback | AsyncCallback\<{psRadioTech: [RadioTechnology](#radiotechnology), csRadioTech:[RadioTechnology](#radiotechnology)}\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -46,7 +47,7 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; -radio.getRadioTech(slotId, (err, data) =>{ +radio.getRadioTech(slotId, (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -75,6 +76,7 @@ Obtains the RAT used in the CS and PS domains for the SIM card in the specified | Promise<{psRadioTech: [RadioTechnology](#radiotechnology), csRadioTech: [RadioTechnology](#radiotechnology)}> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -116,6 +118,7 @@ Obtains the network status. This API uses an asynchronous callback to return the | callback | AsyncCallback\<[NetworkState](#networkstate)\> | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -130,7 +133,7 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -radio.getNetworkState((err, data) =>{ +radio.getNetworkState((err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` @@ -154,6 +157,7 @@ Obtains the network status. This API uses an asynchronous callback to return the | callback | AsyncCallback\<[NetworkState](#networkstate)\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -198,6 +202,7 @@ Obtains the network status. This API uses a promise to return the result. | Promise\<[NetworkState](#networkstate)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -238,6 +243,7 @@ Obtains the network selection mode of the SIM card in the specified slot. This A | callback | AsyncCallback\<[NetworkSelectionMode](#networkselectionmode)\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -279,6 +285,7 @@ Obtains the network selection mode of the SIM card in the specified slot. This A | Promise\<[NetworkSelectionMode](#networkselectionmode)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -318,6 +325,7 @@ Obtains the ISO country code of the network with which the SIM card in the speci | callback | AsyncCallback\ | Yes | Callback used to return the result, which is an ISO country code, for example, **CN** (China).| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -359,6 +367,7 @@ Obtains the ISO country code of the network with which the SIM card in the speci | Promise\ | Promise used to return the result, which is an ISO country code, for example, **CN** (China).| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -397,6 +406,7 @@ Obtains the ID of the slot in which the primary card is located. This API uses a | callback | AsyncCallback\ | Yes | Callback invoked to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -430,6 +440,7 @@ Obtains the ID of the slot in which the primary card is located. This API uses a | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -467,6 +478,7 @@ Obtains a list of signal strengths of the network with which the SIM card in the | callback | AsyncCallback\\> | Yes | Callback used to return the result, which is a list of [SignalInformation](#signalinformation) objects.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -508,6 +520,7 @@ Obtains a list of signal strengths of the network with which the SIM card in the | Promise\\> | Promise used to return the result, which is a list of [SignalInformation](#signalinformation) objects.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -656,6 +669,7 @@ Checks whether the radio service is enabled on the primary SIM card. This API us | callback | AsyncCallback\ | Yes | Callback used to return the result.
- **true**: The radio service is enabled.
- **false**: The radio service is disabled.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -694,6 +708,7 @@ Checks whether the radio service is enabled on the SIM card in the specified slo | callback | AsyncCallback\ | Yes | Callback used to return the result.
- **true**: The radio service is enabled.
- **false**: The radio service is disabled.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -738,6 +753,7 @@ Checks whether the radio service is enabled on the SIM card in the specified slo | Promise\ | Promise used to return the result.
- **true**: The radio service is enabled.
- **false**: The radio service is disabled.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -778,6 +794,7 @@ Obtains the carrier name for the SIM card in the specified slot. This API uses a | callback | AsyncCallback\ | Yes | Callback used to return the result, which is the carrier name, for example, China Mobile.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -819,6 +836,7 @@ Obtains the carrier name for the SIM card in the specified slot. This API uses a | Promise\ | Promise used t return the result, which is the carrier name, for example, China Mobile. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -861,6 +879,7 @@ Sets the ID of the slot in which the primary card is located. This API uses an a | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -877,8 +896,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; -radio.setPrimarySlotId(slotId, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +radio.setPrimarySlotId(slotId, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -908,6 +927,7 @@ Sets the ID of the slot in which the primary card is located. This API uses a pr | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -925,9 +945,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; let promise = radio.setPrimarySlotId(slotId); -promise.then(data => { - console.log(`setPrimarySlotId success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`setPrimarySlotId success.`); +}).catch((err) => { console.log(`setPrimarySlotId failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -951,6 +971,7 @@ Obtains the IMEI of the SIM card in a card slot. This API uses an asynchronous c | callback | AsyncCallback\ | Yes | Callback used to return the result. If the IMEI does not exist, an empty string is returned.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -991,6 +1012,7 @@ Obtains the IMEI of the SIM card in the specified card slot. This API uses an as | callback | AsyncCallback\ | Yes | Callback used to return the result. If the IMEI does not exist, an empty string is returned.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1037,6 +1059,7 @@ Obtains the IMEI of the SIM card in the specified card slot. This API uses a pro | Promise\ | Promise used to return the result. If the IMEI does not exist, an empty string is returned.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1079,6 +1102,7 @@ Obtains the MEID of the SIM card in a card slot. This API uses an asynchronous c | callback | AsyncCallback\ | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1119,6 +1143,7 @@ Obtains the MEID of the SIM card in the specified card slot. This API uses an as | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1165,6 +1190,7 @@ Obtains the MEID of the SIM card in the specified card slot. This API uses a pro | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1207,6 +1233,7 @@ Obtains the unique device ID of the SIM card in a card slot. This API uses an as | callback | AsyncCallback\ | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1247,6 +1274,7 @@ Obtains the unique device ID of the SIM card in the specified card slot. This AP | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1293,6 +1321,7 @@ Obtains the unique device ID of the SIM card in the specified card slot. This AP | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1335,6 +1364,7 @@ Sends a cell location update request. This API uses an asynchronous callback to | callback | AsyncCallback\ | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1349,8 +1379,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -radio.sendUpdateCellLocationRequest((err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +radio.sendUpdateCellLocationRequest((err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -1374,6 +1404,7 @@ Sends a cell location update request for the SIM card in the specified slot. Thi | callback | AsyncCallback\ | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1389,8 +1420,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; -radio.sendUpdateCellLocationRequest(slotId, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +radio.sendUpdateCellLocationRequest(slotId, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -1419,6 +1450,7 @@ Sends a cell location update request for the SIM card in the specified slot. Thi | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1434,10 +1466,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; -let promise = radio.sendUpdateCellLocationRequest(slotId); -promise.then(data => { - console.log(`sendUpdateCellLocationRequest success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +radio.sendUpdateCellLocationRequest(slotId).then(() => { + console.log(`sendUpdateCellLocationRequest success.`); +}).catch((err) => { console.log(`sendUpdateCellLocationRequest failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -1461,6 +1492,7 @@ Obtains cell information. This API uses an asynchronous callback to return the r | callback | AsyncCallback\\> | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1501,6 +1533,7 @@ Obtains cell information for the SIM card in the specified slot. This API uses a | callback | AsyncCallback\\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1547,6 +1580,7 @@ Obtains cell information for the SIM card in the specified slot. This API uses a | Promise\\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1590,6 +1624,7 @@ Sets the network selection mode. This API uses an asynchronous callback to retur | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1616,8 +1651,8 @@ let networkSelectionModeOptions={ networkInformation: networkInformation, resumeSelection: true } -radio.setNetworkSelectionMode(networkSelectionModeOptions, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +radio.setNetworkSelectionMode(networkSelectionModeOptions, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -1646,6 +1681,7 @@ Sets the network selection mode. This API uses a promise to return the result. | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1673,9 +1709,9 @@ let networkSelectionModeOptions={ resumeSelection: true } let promise = radio.setNetworkSelectionMode(networkSelectionModeOptions); -promise.then(data => { - console.log(`setNetworkSelectionMode success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`setNetworkSelectionMode success.`); +}).catch((err) => { console.log(`setNetworkSelectionMode failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -1700,6 +1736,7 @@ Obtains network search information for the SIM card in the specified slot. This | callback | AsyncCallback\<[NetworkSearchResult](#networksearchresult)\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1744,6 +1781,7 @@ Obtains network search information for the SIM card in the specified slot. This | Promise\<[NetworkSearchResult](#networksearchresult)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1783,6 +1821,7 @@ Obtains the NR option mode. This API uses an asynchronous callback to return the | callback | AsyncCallback\<[NrOptionMode](#nroptionmode8)\> | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1820,6 +1859,7 @@ Obtains the NR option mode for the SIM card in the specified slot. This API uses | callback | AsyncCallback\<[NrOptionMode](#nroptionmode8)\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1863,6 +1903,7 @@ Obtains the NR option mode for the SIM card in the specified slot. This API uses | Promise\<[NrOptionMode](#nroptionmode8)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1904,6 +1945,7 @@ Turns on the radio function. This API uses an asynchronous callback to return th | callback | AsyncCallback\ | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1918,8 +1960,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -radio.turnOnRadio((err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +radio.turnOnRadio((err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -1944,6 +1986,7 @@ Turns on the radio function for the SIM card in the specified slot. This API use | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1959,8 +2002,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; -radio.turnOnRadio(slotId, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +radio.turnOnRadio(slotId, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -1990,6 +2033,7 @@ Turns on the radio function for the SIM card in the specified slot. This API use | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2005,10 +2049,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; -let promise = radio.turnOnRadio(slotId); -promise.then(data => { - console.log(`turnOnRadio success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +radio.turnOnRadio(slotId).then(() => { + console.log(`turnOnRadio success.`); +}).catch((err) => { console.error(`turnOnRadio failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -2032,6 +2075,7 @@ Turns off the radio function. This API uses an asynchronous callback to return t | callback | AsyncCallback\ | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2046,8 +2090,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -radio.turnOffRadio((err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +radio.turnOffRadio((err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -2072,6 +2116,7 @@ Turns off the radio function for the SIM card in the specified slot. This API us | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2087,8 +2132,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; -radio.turnOffRadio(slotId, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +radio.turnOffRadio(slotId, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -2118,6 +2163,7 @@ Turns off the radio function for the SIM card in the specified slot. This API us | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2133,10 +2179,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; -let promise = radio.turnOffRadio(slotId); -promise.then(data => { - console.log(`turnOffRadio success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +radio.turnOffRadio(slotId).then(() => { + console.log(`turnOffRadio success.`); +}).catch((err) => { console.error(`turnOffRadio failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -2162,6 +2207,7 @@ Sets the preferred network for the SIM card in the specified slot. This API uses | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2176,8 +2222,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -radio.setPreferredNetwork(0, 1, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +let slotId = 0; +radio.setPreferredNetwork(slotId, radio.PreferredNetworkMode.PREFERRED_NETWORK_MODE_GSM, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -2207,9 +2254,10 @@ Sets the preferred network for the SIM card in the specified slot. This API uses | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). -| ID| Error Message | +| ID| Error Message | | -------- | -------------------------------------------- | | 201 | Permission denied. | | 401 | Parameter error. | @@ -2221,10 +2269,10 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -let promise = radio.setPreferredNetwork(0, 1); -promise.then(data => { - console.log(`setPreferredNetwork success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +let slotId = 0; +radio.setPreferredNetwork(slotId, radio.PreferredNetworkMode.PREFERRED_NETWORK_MODE_GSM).then(() => { + console.log(`setPreferredNetwork success.`); +}).catch((err) => { console.log(`setPreferredNetwork failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -2249,6 +2297,7 @@ Obtains the preferred network for the SIM card in the specified slot. This API u | callback | AsyncCallback\<[PreferredNetworkMode](#preferrednetworkmode8)\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2293,6 +2342,7 @@ Obtains the preferred network for the SIM card in the specified slot. This API u | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2336,6 +2386,7 @@ Obtains the IMS registration status of the specified IMS service type for the SI | callback | AsyncCallback<[ImsRegInfo](#imsreginfo9)\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2381,6 +2432,7 @@ Obtains the IMS registration status of the specified IMS service type for the SI | Promise\<[ImsRegInfo](#imsreginfo9)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2425,6 +2477,7 @@ Enables listening for **imsRegStateChange** events. This API uses an asynchronou | callback | Callback<[ImsRegInfo](#imsreginfo9)> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2466,6 +2519,7 @@ Disables listening for **imsRegStateChange** events. This API uses an asynchrono | callback | Callback<[ImsRegInfo](#imsreginfo9)> | No | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | diff --git a/en/application-dev/reference/apis/js-apis-sim.md b/en/application-dev/reference/apis/js-apis-sim.md index 3e17df01ff13c5e74e300989517ca606f8b2e069..5c13c134789a04415e1bd7cf95d8954b22a342ae 100644 --- a/en/application-dev/reference/apis/js-apis-sim.md +++ b/en/application-dev/reference/apis/js-apis-sim.md @@ -133,6 +133,7 @@ Checks whether the application (caller) has been granted the operator permission | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -141,7 +142,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -173,6 +173,7 @@ Checks whether the application (caller) has been granted the operator permission | Promise\ | Promise used to return the result. The value **true** indicates that the application (caller) has been granted the carrier permission, and the value **false** indicates the opposite.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -181,7 +182,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -211,6 +211,7 @@ Obtains the ISO country code of the SIM card in the specified slot. This API use | callback | AsyncCallback\ | Yes | Callback used to return the result, which is an ISO country code, for example, **CN** (China).| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -252,6 +253,7 @@ Obtains the ISO country code of the SIM card in the specified slot. This API use | Promise\ | Promise used to return the result, which is an ISO country code, for example, **CN** (China).| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -291,6 +293,7 @@ Obtains the public land mobile network \(PLMN\) ID of the SIM card in the specif | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -332,6 +335,7 @@ Obtains the PLMN ID of the SIM card in the specified slot. This API uses a promi | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -371,6 +375,7 @@ Obtains the service provider name (SPN) of the SIM card in the specified slot. T | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -412,6 +417,7 @@ Obtains the SPN of the SIM card in the specified slot. This API uses a promise t | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -451,6 +457,7 @@ Obtains the state of the SIM card in the specified slot. This API uses an asynch | callback | AsyncCallback\<[SimState](#simstate)\> | Yes | Callback used to return the result. For details, see [SimState](#simstate). | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -459,7 +466,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -492,6 +498,7 @@ Obtains the state of the SIM card in the specified slot. This API uses a promise | Promise\<[SimState](#simstate)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -500,7 +507,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -530,6 +536,7 @@ Obtains the type of the SIM card in the specified slot. This API uses an asynchr | callback | AsyncCallback\<[CardType](#cardtype7)\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -571,6 +578,7 @@ Obtains the type of the SIM card in the specified slot. This API uses a promise | Promise\<[CardType](#cardtype7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -579,7 +587,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -610,6 +617,7 @@ Checks whether the SIM card in the specified slot is installed. This API uses an | callback | AsyncCallback<boolean> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -618,7 +626,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -651,6 +658,7 @@ Checks whether the SIM card in the specified slot is installed. This API uses a | Promise<boolean> | Promise used to return the result. The value **true** indicates that the SIM card in the specified slot is installed, and the value **false** indicates the opposite.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -693,6 +701,7 @@ Obtains SIM card account information. This API uses an asynchronous callback to | callback | AsyncCallback\<[IccAccountInfo](#iccaccountinfo7)\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -740,6 +749,7 @@ Obtains SIM card account information. This API uses a promise to return the resu | Promise<[IccAccountInfo](#iccaccountinfo7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -783,6 +793,7 @@ Obtains the account information list of the active SIM card. This API uses an as | callback | AsyncCallback\\> | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -823,6 +834,7 @@ Obtains the account information list of the active SIM card. This API uses a pro | Promise\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -866,6 +878,7 @@ Sets the default slot ID of the SIM card that provides voice services. This API | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -882,8 +895,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -sim.setDefaultVoiceSlotId(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.setDefaultVoiceSlotId(0, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -913,6 +926,7 @@ Sets the default slot ID of the SIM card that provides voice services. This API | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -930,9 +944,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let promise = sim.setDefaultVoiceSlotId(0); -promise.then(data => { - console.log(`setDefaultVoiceSlotId success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`setDefaultVoiceSlotId success.`); +}).catch((err) => { console.log(`setDefaultVoiceSlotId failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -958,6 +972,7 @@ Sets a display name for the SIM card in the specified slot. This API uses an asy | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -974,8 +989,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let name = "ShowName"; -sim.setShowName(0, name, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.setShowName(0, name, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -1005,6 +1020,7 @@ Sets a display name for the SIM card in the specified slot. This API uses a prom | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1022,9 +1038,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let name = "ShowName"; let promise = sim.setShowName(0, name); -promise.then(data => { - console.log(`setShowName success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`setShowName success.`); +}).catch((err) => { console.log(`setShowName failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -1049,6 +1065,7 @@ Obtains the name of the SIM card in the specified slot. This API uses an asynchr | callback | AsyncCallback<string> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1095,6 +1112,7 @@ Obtains the name of the SIM card in the specified slot. This API uses a promise | Promise<string> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1139,6 +1157,7 @@ Sets a display number for the SIM card in the specified slot. This API uses an a | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1155,8 +1174,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let number = '+861xxxxxxxxxx'; -sim.setShowNumber(0, number, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.setShowNumber(0, number, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -1187,6 +1206,7 @@ Sets a display number for the SIM card in the specified slot. This API uses a pr | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1204,9 +1224,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let number = '+861xxxxxxxxxx'; let promise = sim.setShowNumber(0, number); -promise.then(data => { - console.log(`setShowNumber success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`setShowNumber success.`); +}).catch((err) => { console.log(`setShowNumber failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -1231,6 +1251,7 @@ Obtains the display number of the SIM card in the specified slot. This API uses | callback | AsyncCallback<string> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1277,6 +1298,7 @@ Obtains the display number of the SIM card in the specified slot. This API uses | Promise<string> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1320,6 +1342,7 @@ Activates a SIM card in a specified card slot. This API uses an asynchronous cal | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1335,8 +1358,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -sim.activateSim(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.activateSim(0, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -1366,6 +1389,7 @@ Activates the SIM card in the specified slot. This API uses a promise to return | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1382,9 +1406,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let promise = sim.activateSim(0); -promise.then(data => { - console.log(`activateSim success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`activateSim success.`); +}).catch((err) => { console.log(`activateSim failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -1409,6 +1433,7 @@ Disables the SIM card in the specified slot. This API uses an asynchronous callb | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1424,8 +1449,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -sim.deactivateSim(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.deactivateSim(0, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -1455,6 +1480,7 @@ Disables the SIM card in the specified slot. This API uses a promise to return t | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1471,9 +1497,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let promise = sim.deactivateSim(0); -promise.then(data => { - console.log(`deactivateSim success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`deactivateSim success.`); +}).catch((err) => { console.log(`deactivateSim failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -1499,6 +1525,7 @@ Sets the lock status of the SIM card in the specified slot. This API uses an asy | options | [LockInfo](#lockinfo8) | Yes | Lock information.
- lockType: [LockType](#locktype8)
- password: string
- state: [LockState](#lockstate8) | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1552,6 +1579,7 @@ Sets the lock status of the SIM card in the specified slot. This API uses a prom | Promise<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1602,6 +1630,7 @@ Obtains the lock status of the SIM card in the specified slot. This API uses an | options | [LockType](#locktype8) | Yes | Lock type.
- **1**: PIN lock
- **2**: PIN 2 lock| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1650,6 +1679,7 @@ Obtains the lock status of the SIM card in the specified slot. This API uses a p | Promise<[LockState](#lockstate8)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1696,6 +1726,7 @@ Changes the PIN of the SIM card in the specified slot. This API uses an asynchro | oldPin | string | Yes | Old PIN. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1745,6 +1776,7 @@ Changes the PIN of the SIM card in the specified slot. This API uses a promise t | Promise<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1791,6 +1823,7 @@ Changes PIN 2 of the SIM card in the specified slot. This API uses an asynchrono | oldPin2 | string | Yes | Old PIN. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1840,6 +1873,7 @@ Changes PIN 2 of the SIM card in the specified slot. This API uses a promise to | Promise<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1885,6 +1919,7 @@ Unlocks the PIN of the SIM card in the specified slot. This API uses an asynchro | callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1934,6 +1969,7 @@ Unlocks the PIN of the SIM card in the specified slot. This API uses a promise t | Promise\<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1981,6 +2017,7 @@ Unlocks the PUK of the SIM card in the specified slot. This API uses an asynchro | callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2032,6 +2069,7 @@ Unlocks the PUK of the SIM card in the specified slot. This API uses a promise t | Promise\<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2075,10 +2113,11 @@ Unlocks PIN 2 of the SIM card in the specified slot. This API uses an asynchrono | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| pin2 | string | Yes | PIN 2 of the SIM card. | +| pin2 | string | Yes | PIN of the SIM card. | | callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2119,7 +2158,7 @@ Unlocks PIN 2 of the SIM card in the specified slot. This API uses a promise to | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| pin2 | string | Yes | PIN 2 of the SIM card. | +| pin2 | string | Yes | PIN of the SIM card. | **Return value** @@ -2128,6 +2167,7 @@ Unlocks PIN 2 of the SIM card in the specified slot. This API uses a promise to | Promise\<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2171,10 +2211,11 @@ Unlocks PUK 2 of the SIM card in the specified slot. This API uses an asynchrono | -------- | ------------------------------------------------------------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| | newPin2 | string | Yes | New PIN 2. | -| puk2 | string | Yes | PUK 2 of the SIM card. | +| puk2 | string | Yes | PUK of the SIM card. | | callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2217,7 +2258,7 @@ Unlocks PUK 2 of the SIM card in the specified slot. This API uses a promise to | ------- | ------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| | newPin2 | string | Yes | New PIN 2. | -| puk2 | string | Yes | PUK 2 of the SIM card. | +| puk2 | string | Yes | PUK of the SIM card. | **Return value** @@ -2226,6 +2267,7 @@ Unlocks PUK 2 of the SIM card in the specified slot. This API uses a promise to | Promise\<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2292,6 +2334,7 @@ Obtains the ICCID of the SIM card in the specified slot. This API uses an asynch | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2338,6 +2381,7 @@ Obtains the ICCID of the SIM card in the specified slot. This API uses a promise | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2381,6 +2425,7 @@ Obtains the voice mailbox alpha identifier of the SIM card in the specified slot | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2427,6 +2472,7 @@ Obtains the voice mailbox alpha identifier of the SIM card in the specified slot | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2470,6 +2516,7 @@ Obtains the voice mailbox number of the SIM card in the specified slot. This API | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2516,6 +2563,7 @@ Obtains the voice mailbox number of the SIM card in the specified slot. This API | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2562,6 +2610,7 @@ Sets voice mailbox information for the SIM card in the specified slot. This API | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2578,8 +2627,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -sim.setVoiceMailInfo(0, "mail", "xxx@xxx.com", (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.setVoiceMailInfo(0, "mail", "xxx@xxx.com", (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -2611,6 +2660,7 @@ Sets voice mailbox information for the SIM card in the specified slot. This API | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2628,9 +2678,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let promise = sim.setVoiceMailInfo(0, "mail", "xxx@xxx.com"); -promise.then(data => { - console.log(`setVoiceMailInfo success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`setVoiceMailInfo success.`); +}).catch((err) => { console.log(`setVoiceMailInfo failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -2655,6 +2705,7 @@ Obtains the MSISDN of the SIM card in the specified slot. This API uses an async | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2701,6 +2752,7 @@ Obtains the MSISDN of the SIM card in the specified slot. This API uses a promis | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2744,6 +2796,7 @@ Obtains the group identifier level 1 (GID1) of the SIM card in the specified slo | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2790,6 +2843,7 @@ Obtains the GID1 of the SIM card in the specified slot. This API uses a promise | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2799,7 +2853,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -2833,6 +2886,7 @@ Obtains the international mobile subscriber identity (IMSI) of the SIM card in t | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2842,7 +2896,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -2879,6 +2932,7 @@ Obtains the IMSI of the SIM card in the specified slot. This API uses a promise | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2922,6 +2976,7 @@ Obtains the carrier configuration of the SIM card in the specified slot. This AP | callback | AsyncCallback> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -2968,6 +3023,7 @@ Obtains the carrier configuration of the SIM card in the specified slot. This AP | Promise> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3012,6 +3068,7 @@ Queries contact numbers of the SIM card in the specified slot. This API uses an | callback | AsyncCallback> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3060,6 +3117,7 @@ Queries contact numbers of the SIM card in the specified slot. This API uses a p | Promise> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3106,6 +3164,7 @@ Adds contact numbers for the SIM card in the specified slot. This API uses an as | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3127,8 +3186,8 @@ let diallingNumbersInof = { number: "138xxxxxxxx", pin2: "1234" }; -sim.addIccDiallingNumbers(0, sim.ContactType.GENERAL_CONTACT, diallingNumbersInof, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.addIccDiallingNumbers(0, sim.ContactType.GENERAL_CONTACT, diallingNumbersInof, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -3160,6 +3219,7 @@ Adds contact numbers for the SIM card in the specified slot. This API uses a pro | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3181,9 +3241,9 @@ let diallingNumbersInof = { number: "138xxxxxxxx" }; let promise = sim.addIccDiallingNumbers(0, sim.ContactType.GENERAL_CONTACT, diallingNumbersInof); -promise.then(data => { - console.log(`addIccDiallingNumbers success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`addIccDiallingNumbers success.`); +}).catch((err) => { console.log(`addIccDiallingNumbers failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -3205,11 +3265,12 @@ Deletes contact numbers from the SIM card in the specified slot. This API uses a | Name | Type | Mandatory| Description | | --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | -| type | [ContactType](#contacttype8) | Yes | Contact type.
- 1 : GENERAL_CONTACT
- 2 : FIXED_DIALING | +| type | [ContactType](#contacttype8) | Yes | Contact type.
- **1**: GENERAL_CONTACT
- **2**: FIXED_DIALING | | diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3232,8 +3293,8 @@ let diallingNumbersInof = { recordNumber: 123, pin2: "1234" }; -sim.delIccDiallingNumbers(0, sim.ContactType.GENERAL_CONTACT, diallingNumbersInof, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.delIccDiallingNumbers(0, sim.ContactType.GENERAL_CONTACT, diallingNumbersInof, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -3255,7 +3316,7 @@ Deletes contact numbers from the SIM card in the specified slot. This API uses a | Name | Type | Mandatory| Description | | --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | -| type | [ContactType](#contacttype8) | Yes | Contact type.
- 1 : GENERAL_CONTACT
- 2 : FIXED_DIALING | +| type | [ContactType](#contacttype8) | Yes | Contact type.
- **1**: GENERAL_CONTACT
- **2**: FIXED_DIALING | | diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | **Return value** @@ -3265,6 +3326,7 @@ Deletes contact numbers from the SIM card in the specified slot. This API uses a | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3286,9 +3348,9 @@ let diallingNumbersInof = { number: "138xxxxxxxx" }; let promise = sim.delIccDiallingNumbers(0, sim.ContactType.GENERAL_CONTACT, diallingNumbersInof); -promise.then(data => { - console.log(`delIccDiallingNumbers success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`delIccDiallingNumbers success.`); +}).catch((err) => { console.log(`delIccDiallingNumbers failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -3310,11 +3372,12 @@ Updates contact numbers for the SIM card in the specified slot. This API uses an | Name | Type | Mandatory| Description | | --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | -| type | [ContactType](#contacttype8) | Yes | Contact type.
- **1**: GENERAL_CONTACT
- **2**: FIXED_DIALING| +| type | [ContactType](#contacttype8) | Yes | Contact type.
- **1**: GENERAL_CONTACT
- **2**: FIXED_DIALING | | diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3337,8 +3400,8 @@ let diallingNumbersInof = { recordNumber: 123, pin2: "1234" }; -sim.updateIccDiallingNumbers(0, sim.ContactType.GENERAL_CONTACT, diallingNumbersInof, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.updateIccDiallingNumbers(0, sim.ContactType.GENERAL_CONTACT, diallingNumbersInof, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -3360,7 +3423,7 @@ Updates contact numbers for the SIM card in the specified slot. This API uses a | Name | Type | Mandatory| Description | | --------------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2 | -| type | [ContactType](#contacttype8) | Yes | Contact type.
- **1**: GENERAL_CONTACT
- **2**: FIXED_DIALING| +| type | [ContactType](#contacttype8) | Yes | Contact type.
- **1**: GENERAL_CONTACT
- **2**: FIXED_DIALING | | diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | Yes | Contact number information. | **Return value** @@ -3370,6 +3433,7 @@ Updates contact numbers for the SIM card in the specified slot. This API uses a | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3392,9 +3456,9 @@ let diallingNumbersInof = { recordNumber: 123 }; let promise = sim.updateIccDiallingNumbers(0, sim.ContactType.GENERAL_CONTACT, diallingNumbersInof); -promise.then(data => { - console.log(`updateIccDiallingNumbers success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`updateIccDiallingNumbers success.`); +}).catch((err) => { console.log(`updateIccDiallingNumbers failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -3420,6 +3484,7 @@ Sends an envelope command to the SIM card in the specified slot. This API uses a | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3435,8 +3500,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -sim.sendEnvelopeCmd(0, "ls", (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.sendEnvelopeCmd(0, "ls", (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -3467,6 +3532,7 @@ Sends an envelope command to the SIM card in the specified slot. This API uses a | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3483,9 +3549,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let promise = sim.sendEnvelopeCmd(0, "ls"); -promise.then(data => { - console.log(`sendEnvelopeCmd success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`sendEnvelopeCmd success.`); +}).catch((err) => { console.log(`sendEnvelopeCmd failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -3507,10 +3573,11 @@ Sends a terminal response command to the SIM card in the specified slot. This AP | Name | Type | Mandatory| Description | | -------- | -------------------- | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| cmd | string | Yes | Command. | +| cmd | string | Yes | Envelope command. | | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3520,14 +3587,13 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** ```js -sim.sendTerminalResponseCmd(0, "ls", (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sim.sendTerminalResponseCmd(0, "ls", (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -3549,7 +3615,7 @@ Sends a terminal response command to the SIM card in the specified slot. This AP | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------------------------- | | slotId | number | Yes | Card slot ID.
- **0**: card slot 1
- **1**: card slot 2| -| cmd | string | Yes | Command. | +| cmd | string | Yes | Envelope command. | **Return value** @@ -3558,6 +3624,7 @@ Sends a terminal response command to the SIM card in the specified slot. This AP | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3567,16 +3634,15 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** ```js let promise = sim.sendTerminalResponseCmd(0, "ls"); -promise.then(data => { - console.log(`sendTerminalResponseCmd success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`sendTerminalResponseCmd success.`); +}).catch((err) => { console.log(`sendTerminalResponseCmd failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -3603,6 +3669,7 @@ Unlocks the SIM card in the specified slot. This API uses an asynchronous callba | callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)\> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3655,6 +3722,7 @@ Unlocks the SIM card in the specified slot. This API uses a promise to return th | Promise<[LockStatusResponse](#lockstatusresponse7)\> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3699,6 +3767,7 @@ Obtains the opkey of the SIM card in the specified slot. This API uses an asynch | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3708,7 +3777,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -3749,6 +3817,7 @@ Obtains the opkey of the SIM card in the specified slot. This API uses a promise | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3758,7 +3827,6 @@ For details about the following error codes, see [Telephony Error Codes](../../r | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | | 8300003 | System internal error. | -| 8300004 | Do not have sim card. | | 8300999 | Unknown error code. | **Example** @@ -3788,6 +3856,7 @@ Obtains the OpName of the SIM card in the specified slot. This API uses an async | callback | AsyncCallback | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3838,6 +3907,7 @@ Obtains the OpName of the SIM card in the specified slot. This API uses a promis | Promise | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -3929,17 +3999,17 @@ Enumerates personalized lock types. **System capability**: SystemCapability.Telephony.CoreService -| Name | Value | Description | -| ------------ | ---- | ----------------------------------------------- | -| PN_PIN_LOCK | 0 | Personalized network PIN lock. For details, see *3GPP TS 22.022 [33]*. | +| Name | Value | Description | +| ------------ | ---- | ------------------------------------------------ | +| PN_PIN_LOCK | 0 | Personalized network PIN lock. For details, see *3GPP TS 22.022 [33]*. | | PN_PUK_LOCK | 1 | Personalized network PUK lock. | -| PU_PIN_LOCK | 2 | Personalized network subset PIN lock. For details, see *3GPP TS 22.022 [33]*. | +| PU_PIN_LOCK | 2 | Personalized network subset PIN lock. For details, see *3GPP TS 22.022 [33]*. | | PU_PUK_LOCK | 3 | Personalized network subset PUK lock. | -| PP_PIN_LOCK | 4 | Personalized service provider PIN lock. For details, see *3GPP TS 22.022 [33]*.| +| PP_PIN_LOCK | 4 | Personalized service provider PIN lock. For details, see *3GPP TS 22.022 [33]*. | | PP_PUK_LOCK | 5 | Personalized service provider PUK lock. | -| PC_PIN_LOCK | 6 | Personalized corporate PIN lock. For details, see *3GPP TS 22.022 [33]*. | +| PC_PIN_LOCK | 6 | Personalized corporate PIN lock. For details, see *3GPP TS 22.022 [33]*. | | PC_PUK_LOCK | 7 | Personalized corporate PUK lock. | -| SIM_PIN_LOCK | 8 | Personalized SIM card PIN lock. For details, see *3GPP TS 22.022 [33]*. | +| SIM_PIN_LOCK | 8 | Personalized SIM card PIN lock. For details, see *3GPP TS 22.022 [33]*. | | SIM_PUK_LOCK | 9 | Personalized SIM card PUK lock. | ## LockStatusResponse7+ diff --git a/en/application-dev/reference/apis/js-apis-sms.md b/en/application-dev/reference/apis/js-apis-sms.md index fa060c0d474ef8b0fdca74e517bfebca03f44b7a..464f34595cc67c5051524d2f7f6ef0753bede543 100644 --- a/en/application-dev/reference/apis/js-apis-sms.md +++ b/en/application-dev/reference/apis/js-apis-sms.md @@ -91,6 +91,19 @@ Sends an SMS message. | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | | options | [SendMessageOptions](#sendmessageoptions) | Yes | Options (including the callback) for sending an SMS message.| +**Error codes** + +For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). + +| ID| Error Message | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **Example** ```js @@ -178,6 +191,7 @@ Sets the default slot ID of the SIM card used to send SMS messages. This API use | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -193,8 +207,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r **Example** ```js -sms.setDefaultSmsSlotId(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sms.setDefaultSmsSlotId(0, (err) => { + console.log(`callback: err->${JSON.stringify(err)}.`); }); ``` @@ -224,6 +238,7 @@ Sets the default slot ID of the SIM card used to send SMS messages. This API use | Promise\ | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -240,9 +255,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let promise = sms.setDefaultSmsSlotId(0); -promise.then(data => { - console.log(`setDefaultSmsSlotId success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`setDefaultSmsSlotId success.`); +}).catch((err) => { console.error(`setDefaultSmsSlotId failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -268,6 +283,7 @@ Sets the short message service center (SMSC) address. This API uses an asynchron | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -284,8 +300,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; let smscAddr = '+861xxxxxxxxxx'; -sms.setSmscAddr(slotId, smscAddr, (err,data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sms.setSmscAddr(slotId, smscAddr, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -316,6 +332,7 @@ Sets the SMSC address. This API uses a promise to return the result. | Promise<void> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -333,9 +350,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r 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 => { +promise.then(() => { + console.log(`setSmscAddr success.`); +}).catch((err) => { console.error(`setSmscAddr failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -361,6 +378,7 @@ Obtains the SMSC address. This API uses an asynchronous callback to return the r | callback | AsyncCallback<string> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -407,6 +425,7 @@ Obtains the SMSC address. This API uses a promise to return the result. | Promise<string> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -469,6 +488,7 @@ Splits an SMS message into multiple segments. This API uses an asynchronous call | callback | AsyncCallback> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -515,6 +535,7 @@ Splits an SMS message into multiple segments. This API uses a promise to return | Promise> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -558,6 +579,7 @@ Adds a SIM message. This API uses an asynchronous callback to return the result. | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -578,8 +600,8 @@ let simMessageOptions = { pdu: "xxxxxx", status: sms.SimMessageStatus.SIM_MESSAGE_STATUS_READ }; -sms.addSimMessage(simMessageOptions, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sms.addSimMessage(simMessageOptions, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -609,6 +631,7 @@ Adds a SIM message. This API uses a promise to return the result. | Promise<void> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -630,9 +653,9 @@ let simMessageOptions = { status: sms.SimMessageStatus.SIM_MESSAGE_STATUS_READ }; let promise = sms.addSimMessage(simMessageOptions); -promise.then(data => { - console.log(`addSimMessage success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`addSimMessage success.`); +}).catch((err) => { console.error(`addSimMessage failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -658,6 +681,7 @@ Deletes a SIM message. This API uses an asynchronous callback to return the resu | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -674,8 +698,8 @@ For details about the following error codes, see [Telephony Error Codes](../../r ```js let slotId = 0; let msgIndex = 1; -sms.delSimMessage(slotId, msgIndex, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sms.delSimMessage(slotId, msgIndex, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -706,6 +730,7 @@ Deletes a SIM message. This API uses a promise to return the result. | Promise<void> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -723,9 +748,9 @@ For details about the following error codes, see [Telephony Error Codes](../../r let slotId = 0; let msgIndex = 1; let promise = sms.delSimMessage(slotId, msgIndex); -promise.then(data => { - console.log(`delSimMessage success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`delSimMessage success.`); +}).catch((err) => { console.error(`delSimMessage failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -750,6 +775,7 @@ Updates a SIM message. This API uses an asynchronous callback to return the resu | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -771,8 +797,8 @@ let updateSimMessageOptions = { pdu: "xxxxxxx", smsc: "test" }; -sms.updateSimMessage(updateSimMessageOptions, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sms.updateSimMessage(updateSimMessageOptions, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -802,6 +828,7 @@ Updates a SIM message. This API uses a promise to return the result. | Promise<void> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -824,9 +851,9 @@ let updateSimMessageOptions = { smsc: "test" }; let promise = sms.updateSimMessage(updateSimMessageOptions); -promise.then(data => { - console.log(`updateSimMessage success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`updateSimMessage success.`); +}).catch((err) => { console.error(`updateSimMessage failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -851,6 +878,7 @@ Obtains all SIM card messages. This API uses an asynchronous callback to return | callback | AsyncCallback> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -897,6 +925,7 @@ Obtains all SIM card messages. This API uses a promise to return the result. | PromiseArray<[SimShortMessage](#simshortmessage7)\>> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -940,6 +969,7 @@ Sets the cell broadcast configuration. This API uses an asynchronous callback to | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -961,8 +991,8 @@ let cbConfigOptions = { endMessageId: 200, ranType: sms.RanType.TYPE_GSM }; -sms.setCBConfig(cbConfigOptions, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +sms.setCBConfig(cbConfigOptions, (err) => { + console.log(`callback: err->${JSON.stringify(err)}`); }); ``` @@ -992,6 +1022,7 @@ Sets the cell broadcast configuration. This API uses a promise to return the res | Promise<void> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1014,9 +1045,9 @@ let cbConfigOptions = { ranType: sms.RanType.TYPE_GSM }; let promise = sms.setCBConfig(cbConfigOptions); -promise.then(data => { - console.log(`setCBConfig success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { +promise.then(() => { + console.log(`setCBConfig success.`); +}).catch((err) => { console.error(`setCBConfig failed, promise: err->${JSON.stringify(err)}`); }); ``` @@ -1041,6 +1072,7 @@ Obtains SMS message segment information. This API uses an asynchronous callback | callback | AsyncCallback<[SmsSegmentsInfo](#smssegmentsinfo8)> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1086,6 +1118,7 @@ Obtains SMS message segment information. This API uses a promise to return the r | Promise<[SmsSegmentsInfo](#smssegmentsinfo8)> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1126,6 +1159,7 @@ Checks whether SMS is supported on IMS. This API uses an asynchronous callback t | callback | AsyncCallback<boolean> | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1169,6 +1203,7 @@ This API uses an asynchronous callback to return the result. This API uses a pro | Promise<boolean> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1208,11 +1243,11 @@ Obtains the SMS format supported by the IMS. This API uses an asynchronous callb | callback | AsyncCallback<string> | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | | -------- | -------------------------------------------- | -| 201 | Permission denied. | | 401 | Parameter error. | | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | @@ -1245,11 +1280,11 @@ Obtains the SMS format supported by the IMS. This API uses a promise to return t | Promise<string> | Promise used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | | -------- | -------------------------------------------- | -| 201 | Permission denied. | | 401 | Parameter error. | | 8300001 | Invalid parameter value. | | 8300002 | Operation failed. Cannot connect to service. | @@ -1285,6 +1320,7 @@ Decodes MMS messages. This API uses an asynchronous callback to return the resul | callback | AsyncCallback<[MmsInformation](#mmsinformation8)> | Yes | Callback used to return the result. | **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1328,6 +1364,7 @@ Decodes MMS messages. This API uses a promise to return the result. | Promise<<[MmsInformation](#mmsinformation8)>> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1368,6 +1405,7 @@ MMS message code. This API uses an asynchronous callback to return the result. | callback | AsyncCallback<Array> | Yes | Callback used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1419,6 +1457,7 @@ MMS message code. This API uses a promise to return the result. | Promise<Array> | Promise used to return the result.| **Error codes** + For details about the following error codes, see [Telephony Error Codes](../../reference/errorcodes/errorcode-telephony.md). | ID| Error Message | @@ -1955,7 +1994,7 @@ Defines an MMS response index. | Name | Type | Mandatory| Description | | ------------- | ---------------------------------- | ---- | -------- | | transactionId | string | Yes | Event ID. | -| status | number | Yes | Status. | +| status | number | Yes | Status | | version | [MmsVersionType](#mmsversiontype8) | Yes | Version. | | reportAllowed | [ReportType](#reporttype8) | No | Report allowed.| diff --git a/en/application-dev/reference/apis/js-apis-socket.md b/en/application-dev/reference/apis/js-apis-socket.md index f8952db4dfbe9e9dd957c70b179572c308cbc6c1..d60b3e4eaf6245634140ba6c217bb3d97eb2ac25 100644 --- a/en/application-dev/reference/apis/js-apis-socket.md +++ b/en/application-dev/reference/apis/js-apis-socket.md @@ -1,5 +1,7 @@ # # @ohos.net.socket (Socket Connection) +The **socket** module implements data transfer over TCPSocket, UDPSocket, WebSocket, and TLSSocket connections. + > **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. diff --git a/en/application-dev/website.md b/en/application-dev/website.md index 8a54c79bc5251bb3a75b09f7fab5acc62035c208..22372d596c6ead11a925f9633d02571197b1d621 100644 --- a/en/application-dev/website.md +++ b/en/application-dev/website.md @@ -1303,5 +1303,4 @@ - [Native API Usage](faqs/faqs-native.md) - [Usage of Third- and Fourth-Party Libraries](faqs/faqs-third-party-library.md) - [IDE Usage](faqs/faqs-ide.md) - - [hdc_std Command Usage](faqs/faqs-hdc-std.md) - [Development Board](faqs/faqs-development-board.md) diff --git a/en/device-dev/subsystems/Readme-EN.md b/en/device-dev/subsystems/Readme-EN.md index 7dd8216273a99eff11577851a9622d10eb8011b5..81fb9648c011a9591bfa6616e4a24950bcc34669 100644 --- a/en/device-dev/subsystems/Readme-EN.md +++ b/en/device-dev/subsystems/Readme-EN.md @@ -100,7 +100,6 @@ - [HiSysEvent Listening](subsys-dfx-hisysevent-listening.md) - [HiSysEvent Query](subsys-dfx-hisysevent-query.md) - [HiSysEvent Tool Usage](subsys-dfx-hisysevent-tool.md) - - [HiDumper Development](subsys-dfx-hidumper.md) - [HiChecker Development](subsys-dfx-hichecker.md) - [FaultLogger Development](subsys-dfx-faultlogger.md) - [Hiview Development](subsys-dfx-hiview.md) @@ -108,3 +107,4 @@ - [bytrace](subsys-toolchain-bytrace-guide.md) - [hdc](subsys-toolchain-hdc-guide.md) - [hiperf](subsys-toolchain-hiperf.md) + - [HiDumper](subsys-dfx-hidumper.md) diff --git a/en/device-dev/subsystems/figures/call-chain-tracing-in-synchronous-communication.png b/en/device-dev/subsystems/figures/call-chain-trace-in-synchronous-communication.png similarity index 100% rename from en/device-dev/subsystems/figures/call-chain-tracing-in-synchronous-communication.png rename to en/device-dev/subsystems/figures/call-chain-trace-in-synchronous-communication.png diff --git a/en/device-dev/subsystems/figures/process_crash_handling_flowchart.png b/en/device-dev/subsystems/figures/process_crash_handling_flowchart.png new file mode 100644 index 0000000000000000000000000000000000000000..65774b41cd4b6bc3c4f03c271fd0cefb9aec6d8d Binary files /dev/null and b/en/device-dev/subsystems/figures/process_crash_handling_flowchart.png differ diff --git a/en/device-dev/subsystems/subsys-dfx-faultlogger.md b/en/device-dev/subsystems/subsys-dfx-faultlogger.md index 209734174320846cc68004b82dfff89447df453b..21513ea9cf913eff37a626c7e74294e95fde69ed 100644 --- a/en/device-dev/subsystems/subsys-dfx-faultlogger.md +++ b/en/device-dev/subsystems/subsys-dfx-faultlogger.md @@ -4,108 +4,121 @@ ## Overview -### Function +### Function Introduction FaultLogger is a maintenance and debugging log framework provided by OpenHarmony. It enables unified detection, log collection, log storage, and log reporting for application, ability, and system service process crashes. It is available for the standard system and the Linux kernel-based small system. FaultLogger is responsible for fault recording of OpenHarmony. It runs on the following two components based on the service object: -- HiView: serves functional modules at the application layer and native layer. It manages various fault information in the system and provides APIs for modules to query faults. +- Hiview: serves functional modules at the application layer and native layer. It manages various fault information in the system and provides APIs for modules to query faults. -- FaultLoggerd: serves the crash process. It collects information about abnormal daemon processes in C/C++ and obtains the process call stack. +- Faultloggerd: serves the crash process. It collects information about the abnormal daemon process in C/C++ and obtains call stack information of the process. The following figure shows the process of handling a process crash based on the FaultLogger service. **Figure 1** Process crash handling flowchart -![process_crash_handling](figures/process_crash_handling.png) +![Process crash handling flowchart](figures/process_crash_handling_flowchart.png) -1. After the signal processor is installed, the **DFX_SignalHandler** function detects and responds to the process crash exception signal. +1. After the signal processor is installed, SignalHandler uses the **DFX_SignalHandler** function to detect and respond to the process crash exception signal thrown by the kernel. -2. **SignalHandler** forks a child process after detecting the exception signal and runs **ProcessDump** to dump the stack information of the crashed process and thread. +2. When detecting a process crash exception signal, SignalHandler forks a child process and runs ProcessDump to dump the stack information of the crashed process and thread. -3. **ProcessDump** then writes a log to the temporary storage directory in FaultLoggerd, generating a full crash log. +3. ProcessDump applies to Faultloggerd for a file handle for storing fault logs. After reading the exception stack information, ProcessDump writes the information to the file to generate a complete crash log. -4. FaultLoggerd reports the fault through the **AddFaultLog()** API provided by HiView. HiView handles the fault, generates a simple crash log, and reports a HiSysEvent. +4. After collecting the complete crash log, ProcessDump reports the log to Hiview by using the **AddFaultLog()** API. Hiview generates a simplified crash log and reports a system event through HiSysEvent. -With this design, a small-system with limited resources can obtain logs for locating crash faults as long as FaultLoggerd is deployed. +With this design, a small-system with limited resources can obtain logs for locating crash faults as long as Faultloggerd is deployed. ### Use Cases -FaultLoggerd provides a lightweight approach for you to locate crash or suspension problems during development and testing. +Faultloggerd provides a lightweight approach for you to locate crash or suspension problems during development and testing. -It is applicable to the following scenarios: +The following table describes the application scenarios. **Table 1** Application scenarios of the Faultloggerd module -| Scenario| Tool| Usage| +| Scenario| Tool| Usage| | -------- | -------- | -------- | -| To understand the function call sequence| DumpCatcher API | See [Using DumpCatcher to Obtain the Call Stack](#using-dumpcatcher-to-obtain-the-call-stack).| -| Application suspension or high CPU usage| ProcessDump | See [Using ProcessDump to Obtain the Call Stack](#using-processdump-to-obtain-the-call-stack).| -| Signal crash not handled by the process| Crash log and addr2line tool| See [Locating Faults Based on Crash Logs](#locating-faults-based-on-crash-logs).| +| Understanding of the function call sequence| DumpCatcher API | See [Using DumpCatcher APIs to Obtain Call Stack Information](#using-dumpcatcher-apis-to-obtain-call-stack-information).| +| Application suspension or high CPU usage| DumpCatcher Command Tool | See [Using DumpCatcher Commands to Obtain Call Stack Information](#using-dumpcatcher-commands-to-obtain-call-stack-information).| +| Crash fault location| Crash log and addr2line tool| For details, see [Locating Faults Based on the Crash Log](#locating-faults-based-on-the-crash-log).| -## Using DumpCatcher to Obtain the Call Stack +## Using DumpCatcher APIs to Obtain Call Stack Information ### Available APIs -DumpCatcher can capture the call stack of a specified process (thread) on OpenHarmony. +DumpCatcher can capture the call stack information of the specified process (thread) on OpenHarmony. - Table 2 DumpCatcher APIs + **Table 2** DumpCatcher APIs -| Class| API| Description| +| Class| API| Description| | -------- | -------- | -------- | -| DfxDumpCatcher | bool DumpCatch(const int pid, const int tid, std::string& msg) | Return value:
**true**: Back trace is successful. Related information is stored in the **msg** string object.
**false**: Back trace failed.
Input arguments:
**pid**: target process ID.
**tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.
Output argument:
**msg**: return message. If back trace is successful, the call stack information is returned through **msg**.| +| DfxDumpCatcher | bool DumpCatch(const int pid, const int tid, std::string& msg) | Return value:
- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.
- **false**: Dumping of stack information has failed.
Input arguments:
- **pid**: target process ID.
- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.
Output arguments:
- **msg**: If back trace is successful, call stack information is returned through **msg**.| +| DfxDumpCatcher | bool DumpCatchMix(const int pid, const int tid, std::string& msg) | Return value:
- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.
- **false**: Dumping of stack information has failed.
Input arguments:
**pid**: target process ID.
- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.
Output arguments:
- **msg**: If back trace is successful, hybrid stack information is returned through **msg**.| +| DfxDumpCatcher | bool DumpCatchFd(const int pid, const int tid, std::string& msg, int fd) | Return value:
- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.
- **false**: Dumping of stack information has failed.
Input arguments:
**pid**: target process ID.
- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.
- **fd**: handle of the file to be written.
Output parameters:
- **msg**: If back trace is successful, call stack information is returned through **msg**.| +| DfxDumpCatcher | bool DumpCatchMultiPid(const std::vector\ pidV, std::string& msg) | Return value:
- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.
- **false**: Dumping of stack information has failed.
Input arguments:
- **pidV**: target process ID list.
Output arguments:
- **msg**: If back trace is successful, call stack information is returned through **msg**.| -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
-> If the PID that calls this API is different from the target PID, the caller must be the **system** or **root** user. To capture the call stack of a process that does not belong to the current user group, ensure that you have permissions to read **/proc/pid/maps** and implement **ptrace** on the peer process. +> **NOTE** +> If the PID that calls this API is different from the target PID, the caller must be the **system** or **root** user. -### Development Example +### How to Develop + +You can use DumpCatcher to obtain call stack information for the specified process (thread) of an application. The following uses the **dumpcatcherdemo** module as an example to describe how to use the DumpCatcher APIs to obtain the call stack information. -You can use DumpCatcher to obtain the call stack of a specified process (thread) in your applications. The following uses the **dumpcatcherdemo** module as an example to describe how to use the DumpCatcher API to obtain the call stack. +1. Add the DumpCatcher dependency to the build file. Take /base/hiviewdfx/faultloggerd/example/BUILD.gn as an example. Add the **dump_catcher.h** file path to **include_dirs** and add the required **//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher** module to **deps**. -1. Add the DumpCatcher dependency to the build file. Take /base/hiviewdfx/faultloggerd/example/BUILD.gn as an example. Add the **dfx_dump_catcher.h** file path to **include_dirs** and add the required **//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher** module to **deps**. - ``` import("//base/hiviewdfx/faultloggerd/faultloggerd.gni") import("//build/ohos.gni") - + config("dumpcatcherdemo_config") { visibility = [ ":*" ] - + include_dirs = [ ".", "//utils/native/base/include", "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher/include/", # Add the path of the dump_catcher header file. ] } - - ohos_executable("dumpcatcherdemo") { sources = [ "dump_catcher_demo.cpp" ] configs = [ ":dumpcatcherdemo_config" ] deps = [ "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher", # Add the DumpCatcher module dependency. "//utils/native/base:utils", ] external_deps = [ "hilog_native:libhilog" ] install_enable = true part_name = "faultloggerd" subsystem_name = "hiviewdfx" + + ohos_executable("dumpcatcherdemo") { + sources = [ "dump_catcher_demo.cpp" ] + configs = [ ":dumpcatcherdemo_config" ] + deps = [ + "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher", # Add the DumpCatcher module dependency. + "//utils/native/base:utils", + ] + external_deps = [ "hilog_native:libhilog" ] + install_enable = true + part_name = "faultloggerd" + subsystem_name = "hiviewdfx" } ``` 2. Define the header file. Take **/base/hiviewdfx/faultloggerd/example/dump_catcher_demo.h** as an example. In the sample code, the function of the stack depth test is called to construct a call stack with a specified depth. - + ``` #ifndef DUMP_CATCHER_DEMO_H #define DUMP_CATCHER_DEMO_H - + #include - + #define NOINLINE __attribute__((noinline)) - + // Define the macro function to automatically generate a function call chain. #define GEN_TEST_FUNCTION(FuncNumA, FuncNumB) \ __attribute__((noinline)) int TestFunc##FuncNumA() \ { \ return TestFunc##FuncNumB(); \ } - + // Call the function of the stack depth test. int TestFunc0(void); int TestFunc1(void); @@ -118,33 +131,33 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread) int TestFunc8(void); int TestFunc9(void); int TestFunc10(void); - + #endif // DUMP_CATCHER_DEMO_H ``` 3. Call the **DumpCatch** API in the source file. Take **/base/hiviewdfx/faultloggerd/example/dump_catcher_demo.cpp** as an example. Include the **dfx_dump_catcher.h** file, declare the **DfxDumpCatcher** object, use the macro function to construct a function call chain, call the **DumpCatch** method, and pass the required process ID and thread ID of the call stack into this method. - + ``` #include "dump_catcher_demo.h" - + #include #include #include // Include the dfx_dump_catcher.h file. #include "dfx_dump_catcher.h" using namespace std; - + NOINLINE int TestFunc10(void) { OHOS::HiviewDFX::DfxDumpCatcher dumplog; string msg = ""; - bool ret = dumplog.DumpCatch(getpid(), gettid(), msg); // Call the DumpCatch API to obtain the call stack. + bool ret = dumplog.DumpCatch(getpid(), gettid(), msg); // Call the DumpCatch API to obtain the call stack information. if (ret) { cout << msg << endl; } return 0; } - + // Use the macro function to automatically generate a function call chain. GEN_TEST_FUNCTION(0, 1) GEN_TEST_FUNCTION(1, 2) @@ -156,7 +169,7 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread) GEN_TEST_FUNCTION(7, 8) GEN_TEST_FUNCTION(8, 9) GEN_TEST_FUNCTION(9, 10) - + int main(int argc, char *argv[]) { TestFunc0(); @@ -165,55 +178,57 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread) ``` -## Using ProcessDump to Obtain the Call Stack +## Using DumpCatcher Commands to Obtain Call Stack Information ### Tool Description -ProcessDump is a command line interface (CLI) based tool for capturing call stacks on OpenHarmony. It uses the **-p** and **-t** parameters to specify the process and thread. After the command is executed, the thread stack information of the specified process is displayed in the CLI window. +DumpCatcher Command Tool is a command line interface (CLI)-based tool for capturing call stack information on OpenHarmony. It uses the **-p** and **-t** parameters to specify the process and thread. After the command is executed, the thread stack information of the specified process is displayed in the CLI window. By specifying the **-m** parameter, you can also capture the JS and Native hybrid stack information of an application process. - **Table 3** Usage of the CLI-based ProcessDump + **Table 3** Usage of the DumpCatcher Command Tool -| Tool| Path| Command| Description| +| Tool| Path| Command| Description| | -------- | -------- | -------- | -------- | -| processdump | /system/bin | - processdump -p [pid]
- processdump -p [pid] -t [tid] | **Arguments:**
**- -p [pid]**: prints stack information for all threads of the specified process.
**- -p [pid] -t [tid]**: prints information for the specified thread of the specified process.
**Return value:**
If the stack information is parsed successfully, the information is displayed in the standard output. If the stack information fails to be parsed, error information is displayed.| - +| dumpcatcher | /system/bin | - dumpcatcher -p [pid]
- dumpcatcher -p [pid] -t [tid]
- dumpcatcher -m -p [pid]
- dumpcatcher -m -p [pid] -t [tid]
| **Description:**
- **-p [pid]**: prints all thread stack information of the specified process.
- **-p [pid] -t [tid]**: prints stack information for the specified thread of the specified process.
- **-m -p [pid]**: prints hybrid stack information for all threads of the specified process.
- **-m -p [pid] -t [tid]**: prints hybrid stack information for the specified thread of the specified process.
**Return value:**
If the stack information is parsed successfully, the information is displayed in the standard output. If the stack information fails to be parsed, error information is displayed.| -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
-> This tool must be used by the **root** user, or the caller must have the permission to ptrace the target process and read the smaps of the target process. +### Development Example -### Example +Print call stack information of the **hiview** process. -Use ProcessDump to print the call stack of the **hiview** process. - ``` -# ps -A | grep hiview - 114 ? 00:00:00 hiview -# processdump -p 114 -t 114 -Tid:114, Name:hiview -#00 pc 0000000000089824(00000000b6f44824) /system/lib/ld-musl-arm.so.1(ioctl+68) -#01 pc 000000000002a709(00000000b6c56709) /system/lib/libipc_core.z.so(_ZN4OHOS15BinderConnector11WriteBinderEmPv+16) -#02 pc 000000000002ba75(00000000b6c57a75) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker18TransactWithDriverEb+224) -#03 pc 000000000002bb37(00000000b6c57b37) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker13StartWorkLoopEv+22) -#04 pc 000000000002c211(00000000b6c58211) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker10JoinThreadEb+36) -#05 pc 0000000000038d07(00000000004bcd07) /system/bin/hiview(_ZNSt3__h6vectorINS_9sub_matchINS_11__wrap_iterIPKcEEEENS_9allocatorIS6_EEE8__appendEj+596) -#06 pc 0000000000028655(00000000004ac655) /system/bin/hiview -#07 pc 00000000000c2b08(00000000b6f7db08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116) -#08 pc 00000000000285f4(00000000004ac5f4) /system/bin/hiview -#09 pc 0000000000028580(00000000004ac580) /system/bin/hiview +# ps -ef |grep hiview +hiview 240 1 0 17:01:49 ? 00:00:14 hiview +root 1822 1560 7 20:56:36 pts/0 00:00:00 grep hiview +# dumpcatcher -p 240 -t 240 +Result: 0 ( no error ) +Timestamp:2017-08-05 20:56:43.000 +Pid:240 +Uid:1201 +Process name:/system/bin/hiview +Tid:240, Name:hiview +#00 pc 00098f8c /system/lib/ld-musl-arm.so.1(ioctl+68) +#01 pc 0000e2a1 /system/lib/chipset-pub-sdk/libipc_single.z.so +#02 pc 0000ed59 /system/lib/chipset-pub-sdk/libipc_single.z.so +#03 pc 0000ee1f /system/lib/chipset-pub-sdk/libipc_single.z.so +#04 pc 0000f745 /system/lib/chipset-pub-sdk/libipc_single.z.so +#05 pc 00037577 /system/bin/hiview +#06 pc 00025973 /system/bin/hiview +#07 pc 000db210 /system/lib/ld-musl-arm.so.1 +#08 pc 000258d8 /system/bin/hiview +#09 pc 0002587c /system/bin/hiview ``` -## Locating Faults Based on Crash Logs +## Locating Faults Based on the Crash Log -You can locate faults based on the crash stack logs generated by FaultLoggerd. This section describes how to use the addr2line tool to locate a crash fault. +You can locate faults based on the crash stack logs generated by Faultloggerd. This section describes how to use the addr2line tool to locate a crash fault. 1. Find a program crash or construct a crash. For example, insert the following code into your code to trigger an invalid memory access fault (SIGSEGV). - + ``` NOINLINE int TriggerSegmentFaultException() { @@ -228,40 +243,41 @@ You can locate faults based on the crash stack logs generated by FaultLoggerd. T 2. Obtain the crash function call stack log. The process generates a temporary log file in the** /data/log/faultlog/temp** directory due to an exception that is not handled. The naming rule of the temporary log file is as follows: - + ``` cppcrash-pid-time ``` - The generated call stack is as follows: + The generated call stack information is as follows: + - ``` + Timestamp:2017-08-05 17:35:03.000 Pid:816 Uid:0 - Process name:./crasher + Process name:./crasher_c Reason:Signal:SIGSEGV(SEGV_ACCERR)@0x0042d33d Fault thread Info: Tid:816, Name:crasher + #00 pc 0000332c /data/crasher(TriggerSegmentFaultException+15)(8bc37ceb8d6169e919d178fdc7f5449e) + #01 pc 000035c7 /data/crasher(ParseAndDoCrash+277)(8bc37ceb8d6169e919d178fdc7f5449e) + #02 pc 00003689 /data/crasher(main+39)(8bc37ceb8d6169e919d178fdc7f5449e) + #03 pc 000c3b08 /system/lib/ld-musl-arm.so.1(__libc_start_main+116) + #04 pc 000032f8 /data/crasher(_start_c+112)(8bc37ceb8d6169e919d178fdc7f5449e) + #05 pc 00003284 /data/crasher(_start+32)(8bc37ceb8d6169e919d178fdc7f5449e) + Registers: r0:0042d33d r1:0000000b r2:1725d4c4 r3:b6f9fa84 r4:bec97e69 r5:b6fc0268 r6:0042d661 r7:bec97d60 r8:00000000 r9:00000000 r10:00000000 fp:bec97d20 ip:00000020 sp:bec97cd0 lr:b6f9fae4 pc:0042d32c - - #00 pc 000000000000332c(000000000042d32c) /data/crasher(TriggerSegmentFaultException+15) - #01 pc 00000000000035c7(000000000042d5c7) /data/crasher(ParseAndDoCrash+277) - #02 pc 0000000000003689(000000000042d689) /data/crasher(main+39) - #03 pc 00000000000c3b08(00000000b6fbbb08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116) - #04 pc 00000000000032f8(000000000042d2f8) /data/crasher(_start_c+112) - #05 pc 0000000000003284(000000000042d284) /data/crasher(_start+32) ``` -3. Use the addr2line tool to analyze the call stack. +3. Use the addr2line tool to analyze the call stack information. Then, parse the line number based on the offset address. - + ``` - root:~/OpenHarmony/out/hi3516dv300/exe.unstripped/hiviewdfx/faultloggerd$ addr2line -e crasher 000332c + root:~/OpenHarmony/out/hi3516dv300/exe.unstripped/hiviewdfx/faultloggerd$ addr2line -e crasher 0000332c base/hiviewdfx/faultloggerd/tools/crasher/dfx_crasher.c:57 ``` diff --git a/en/device-dev/subsystems/subsys-dfx-hicollie.md b/en/device-dev/subsystems/subsys-dfx-hicollie.md index 90bb652a9a0f678b8a413b187bfd3bbd41d13e26..321bc54040002845d5c94b3d1964af165526d68b 100644 --- a/en/device-dev/subsystems/subsys-dfx-hicollie.md +++ b/en/device-dev/subsystems/subsys-dfx-hicollie.md @@ -1,185 +1,101 @@ -# HiCollie Development +# HiCollie Development -## Overview -HiCollie provides the software watchdog function. It provides a unified framework for fault detection and fault log generation to help you locate software timeout faults resulting from system service deadlock, application main thread blocking, and service process timeout. - -## Available APIs - -**Table 1** Description of C++ APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Class

-

API

-

Description

-

XCollieChecker

-

virtual void CheckBlock()

-

Provides the callback of the suspension detection result.

-

Input arguments: none

-

Output arguments: none

-

Return value: none

-

XCollieChecker

-

virtual void CheckThreadBlock()

-

Provides the callback of the thread suspension detection result.

-

Input arguments: none

-

Output arguments: none

-

Return value: none

-

XCollie

-

void RegisterXCollieChecker(const sptr<XCollieChecker> &checker, unsigned int type)

-

Registers the callback of the thread suspension detection result.

-

Input arguments:

-
  • checker: Indicates the pointer to the XCollieChecker instance.
  • type: Indicates the suspension detection type. Set it to XCOLLIE_THREAD.
-

Output arguments: none

-

Return value: none

-

XCollie

-

int SetTimer(const std::string &name, unsigned int timeout, std::function<void (void *)> func, void *arg, unsigned int flag)

-

Adds timers.

-

Input arguments:

-
  • name: Indicates the timer name.
  • timeout: Indicates the timeout duration, in seconds.
  • func: Indicates the timeout callback.
  • arg: Indicates the pointer to the timeout callback.
  • flag: Indicates the timer operation type.

    XCOLLIE_FLAG_DEFAULT // Indicates the default flag, which is the combination of the other three options.

    -

    XCOLLIE_FLAG_NOOP // Calls only the timeout callback.

    -

    XCOLLIE_FLAG_LOG // Generates a timeout fault log.

    -

    XCOLLIE_FLAG_RECOVERY // Exits the process.

    -
-

Output arguments: none

-

Return value: Returns the timer ID if the operation is successful; returns -1 otherwise.

-

XCollie

-

bool UpdateTimer(int id, unsigned int timeout)

-

Updates timers.

-

Input arguments:

-
  • id: Indicates the timer ID.
  • timeout: Indicates the timeout duration, in seconds.
-

Output arguments: none

-

Return value: Returns true if the operation is successful; returns false otherwise.

-

XCollie

-

void CancelTimer(int id)

-

Cancels timers.

-

Input arguments:

-

id: Indicates the timer ID.

-

Output arguments: none

-

Return value: none

-
- -## Example - -Print logs. - -``` -timeout: TimeoutTimer start at 1611040305 to check 1s ago - -----------StacktraceCatcher CurrentTime:2021-01-19 15:11:45 Unexecuted(-1)(LogType:Stacktrace Pid:27689 Process:XCollieTimeoutModuleTest)---------- - - ------ pid 27689 at 2021-01-19 15:11:45 ----- -Cmd line: ./XCollieTimeoutModuleTest -ABI: 'arm64' - -"XCollieTimeoutM" sysTid=27689 - #01 pc 00000000000174cc /data/test/XCollieTimeoutModuleTest -``` - -## How to Develop - -### C++ - -### Thread Suspension Monitoring - -This function requires you to implement two callback functions: **CheckBlock** and **CheckThreadBlock** of the **XCollieChecker** class. After the callbacks are implemented, you need to use the **RegisterXCollieChecker** function of the **XCollie** class to register their instances. The suspension monitoring thread periodically executes all successfully registered callbacks, checks the thread logic completion flag, and determines whether the service logic of any registered thread is suspended. - -1. Develop the source code. - - Include the **xcollie** header file in the source file. - - ``` - #include "xcollie.h" - ``` - - Add the following code to the service code: - - ``` - void MyXCollieChecker::CheckLock() - { - /* time consuming job */ - } - - void MyXCollieChecker::CheckThreadBlock() - { - /* time consuming job */ - } - - sptr checker = new MyXCollieChecker("MyXCollieChecker"); - XCollie::GetInstance().RegisterXCollieChecker(checker, - (XCOLLIE_LOCK | XCOLLIE_THREAD)); - ... - ``` - -2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. - - ``` - external_deps = [ "hiviewdfx:libxcollie" ] - ``` - - -### Timeout Monitoring - -You can add a maximum of 128 timers for a single process by using the **SetTimer** function. Adding timers will fail if the number of timers has reached the upper limit. - -1. Develop the source code. - - Include the **xcollie** header file in the source file. - - ``` - #include "xcollie.h" - ``` - - Add the code to add, update, and cancel timers. - - ``` - std::function callback = [](void *args) - { - /* dump helpful information */ - }; - - int id = XCollie::GetInstance().SetTimer("MyXCollieTimer", 10, callback ,nullptr, XCOLLIE_FLAG_LOG); - /* time consuming job */ - XCollie::GetInstance().UpdateTimer(id, 5); - /* time consuming job */ - XCollie::GetInstance().CancelTimer(id); - ... - ``` +## Overview -2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. - - ``` - external_deps = [ "hiviewdfx:libxcollie" ] - ``` +HiCollie provides the software watchdog function. It provides a unified framework for fault detection and fault log generation to help you locate software timeout faults resulting from system service deadlock, application main thread blocking, and service process timeout. +## Available APIs + + **Table 1** Description of XCollieChecker APIs + +| API| Description| +| -------- | -------- | +| virtual void CheckBlock() | Provides the callback of the suspension detection result.
Input arguments: none
Output arguments: none
Return value: none| +| virtual void CheckThreadBlock() | Provides the callback of the thread suspension detection result.
Input arguments: none
Output arguments: none
Return value: none| + + + **Table 2** Description of XCollie APIs + +| API| Description| +| -------- | -------- | +| void RegisterXCollieChecker(const sptr<XCollieChecker> &checker, unsigned int type) | Registers the callback of the thread suspension detection result.
Input arguments:
- **checker**: pointer to the XCollieChecker instance.
- **type**: suspension detection type. Set it to **XCOLLIE_THREAD**.
Output arguments: none
Return value: none| +| int SetTimer(const std::string &name, unsigned int timeout, std::function<void(void*)> func, void *arg, unsigned int flag) | Adds timers.
Input arguments:
- **name**: timer name.
- **timeout**: timeout duration, in seconds.
- **func**: timeout callback.
- **arg**: pointer to the timeout callback.
- **flag**: timer operation type.
- **XCOLLIE_FLAG_DEFAULT**: default flag, which is the combination of the other three options.
- **XCOLLIE_FLAG_NOOP**: Calls only the timeout callback.
- **XCOLLIE_FLAG_LOG**: Generates a timeout fault log.
- **XCOLLIE_FLAG_RECOVERY**: Exits the process.
Output arguments: none
Return value: timer ID if the operation is successful; **-1** otherwise.| +| bool UpdateTimer(int id, unsigned int timeout) | Updates timers.
Input arguments:
- **id**: timer ID.
- **timeout**: timeout duration, in seconds.
Output arguments: none
Return value: **true** if the operation is successful; **false** otherwise.| +| void CancelTimer(int id) | Cancels a timer.
Input arguments:
- **id**: timer ID.
Output arguments: none
Return value: none| + + +## How to Develop + + +### Thread Suspension Monitoring + +This function requires you to implement two callback functions: **CheckBlock** and **CheckThreadBlock** of the **XCollieChecker** class. After the callbacks are implemented, you need to use the **RegisterXCollieChecker** function of the **XCollie** class to register their instances. The suspension monitoring thread periodically executes all successfully registered callbacks, checks the thread logic completion flag, and determines whether the service logic of any registered thread is suspended. + +1. Develop the source code. + Include the **xcollie** header file in the source file. + + ``` + #include "xcollie.h" + ``` + + Add the following code to the service code: + + + ``` + void MyXCollieChecker::CheckLock() + { + /* time consuming job */ + } + + void MyXCollieChecker::CheckThreadBlock() + { + /* time consuming job */ + } + + sptr checker = new MyXCollieChecker("MyXCollieChecker"); + XCollie::GetInstance().RegisterXCollieChecker(checker, + (XCOLLIE_LOCK | XCOLLIE_THREAD)); + ...... + ``` + +2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. + + ``` + external_deps = [ "hiviewdfx:libxcollie" ] + ``` + + +### Timeout Monitoring + +You can add a maximum of 128 timers for a single process by using the **SetTimer** function. Adding timers will fail if the number of timers has reached the upper limit. + +1. Develop the source code. + Include the **xcollie** header file in the source file. + + ``` + #include "xcollie.h" + ``` + + Add the code to add, update, and cancel timers. + + ``` + std::function callback = [](void *args) + { + /* dump helpful information */ + }; + + int id = XCollie::GetInstance().SetTimer("MyXCollieTimer", 10, callback ,nullptr, XCOLLIE_FLAG_LOG); + /* time consuming job */ + XCollie::GetInstance().UpdateTimer(id, 5); + /* time consuming job */ + XCollie::GetInstance().CancelTimer(id); + ...... + ``` + +2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. + + ``` + external_deps = [ "hiviewdfx:libxcollie" ] + ``` diff --git a/en/device-dev/subsystems/subsys-dfx-hidumper.md b/en/device-dev/subsystems/subsys-dfx-hidumper.md index 1060ab1dea8b06c80da014baf179278a140c8ff1..5c6bc09ecf931c46bb458e6d1c19111431bf0ddb 100644 --- a/en/device-dev/subsystems/subsys-dfx-hidumper.md +++ b/en/device-dev/subsystems/subsys-dfx-hidumper.md @@ -1,21 +1,18 @@ -# HiDumper Development +# HiDumper ## Overview - -### Introduction - HiDumper is a tool provided by OpenHarmony for developers, testers, and IDE tool engineers to obtain system information necessary for analyzing and locating faults. This section applies only to the standard system. -### Source Code Directories +## Source Code Directories ``` /base/hiviewdfx/hidumper ├── frameworks # Framework code │ ├── native # Core function code -│ │ │── include # Header files +│ │ │── include # Header files │ │ │── src # Source files │ │ │── common # Common function code │ │ │── executor # Process executor code @@ -34,14 +31,14 @@ HiDumper is a tool provided by OpenHarmony for developers, testers, and IDE tool ``` -## Usage +# Usage -### Command-Line Options +## Command-Line Options **Table 1** HiDumper command-line options -| Option| Description| +| Option| **Description**| | -------- | -------- | | -h | Shows the help Information.| | -t [timeout] | Specifies the timeout period, in seconds. The default value is **30**. Value **0** indicates no timeout limit.| @@ -56,14 +53,14 @@ HiDumper is a tool provided by OpenHarmony for developers, testers, and IDE tool | --net | Exports network information.| | --storage | Exports storage information.| | -p | Exports the process list and all process information.| -| -p [pid] | Exports all information about a specified process.| -| --cpuusage [pid] | Exports the CPU usage information based on **pid**.| +| -p [pid] | Exports all information about the specified process.| +| --cpuusage [pid] | Exports the CPU usage information. If **pid** is specified, the CPU usage of the corresponding process is exported.| | --cpufreq | Exports the actual CPU frequency.| -| --mem [pid] | Exports the memory usage information based on **pid**.| +| --mem [pid] | Export memory usage information. If **pid** is specified, the memory usage of the corresponding process is exported.| | --zip | Compresses the exported information to a specified folder.| -### Development Example +## Development Example HiDumper helps you export basic system information to locate and analyze faults. Complex parameters passed to sub-services and abilities must be enclosed in double quotation marks. @@ -118,7 +115,7 @@ The procedure is as follows: hidumper -s 3008 ``` -9. Run the **hidumper -e** command to obtain the crash information generated by the FaultLogger module. +9. Run the **hidumper -e** command to obtain the crash information generated by the FaultLoger module. ``` hidumper -e @@ -148,7 +145,7 @@ The procedure is as follows: hidumper -p 1024 ``` -14. Run the **hidumper --cpuusage [pid]** command to obtain the CPU usage information of the process whose PID has been specified. +14. Run the **hidumper --cpuusage [pid]** command to obtain the CPU usage information. If the PID of a process is specified, only the CPU usage of the process is returned. ``` hidumper --cpuusage @@ -161,7 +158,7 @@ The procedure is as follows: hidumper --cpufreq ``` -16. Run the **hidumper --mem [pid]** command to obtain all memory usage information of the process whose PID has been specified. +16. Run the **hidumper --mem [pid]** command to obtain all memory usage information. If the PID of a process is specified, only the memory usage of the process is returned. ``` hidumper --mem [pid] diff --git a/en/device-dev/subsystems/subsys-dfx-hitracechain.md b/en/device-dev/subsystems/subsys-dfx-hitracechain.md index 9b9b85b66a457a0653b12f7d450f13f7aaef2a4f..d217a0512143e4e3275d2a846d705d978beb6faf 100644 --- a/en/device-dev/subsystems/subsys-dfx-hitracechain.md +++ b/en/device-dev/subsystems/subsys-dfx-hitracechain.md @@ -2,530 +2,240 @@ ## Overview -HiTraceChain tracks the call chain with the same **traceid** throughout the inter-device, inter-process, and inter-thread service processes. It associates and displays the call relationship and various output information during the entire process, helping you analyze and locate faults and optimize the system. +HiTraceChain tracks the call chain with the same **traceid** throughout the inter-device, inter-process, and inter-thread service processes. It associates and displays the call relationship and various output information during the entire process, helping you analyze and locate faults and optimize the system. -## Use Cases + +## When to Use HiTraceChain can be used for the following purposes: -- Associates and reports service process information \(such as logs and events\) on the device. +- Associates and reports service process information (such as logs and events) on the device. - Displays and analyzes reported information on the cloud to facilitate fault location. -- Works with the IDE to debug the detailed service process and time consumption distribution for system optimization. +- Works with the IDE to debug the detailed service process and time consumption distribution for system optimization. + + **Figure 1** Use cases of HiTraceChain - **Figure 1** Use cases of HiTraceChain - ![](figures/use-cases-of-hitrace.png "use-cases-of-hitrace") ### Usage Example -**Figure 2** Service calling process \(inter-device and inter-process synchronous call\) + **Figure 2** Service calling process \(inter-device and inter-process synchronous call\) -![](figures/service-calling-process-(inter-device-and-inter-process-synchronous-call).png "service-calling-process-(inter-device-and-inter-process-synchronous-call)") + ![](figures/service-calling-process-(inter-device-and-inter-process-synchronous-call).png "service-calling-process-(inter-device-and-inter-process-synchronous-call)") 1. Display the call relationship in the service process, analyze key paths and function dependency, and determine the time consumption and call frequency at each call point to detect performance bottlenecks. - **Figure 3** Service calling process - - ![](figures/service-calling-process.png "service-calling-process") - - **Figure 4** Time delay in the service calling process + **Figure 3** Service calling process - ![](figures/time-delay-in-the-service-calling-process.png "time-delay-in-the-service-calling-process") + ![](figures/service-calling-process.png "service-calling-process") -2. Add **traceid** to logs and events automatically to facilitate comprehensive analysis and quick fault location. -## Available APIs - -HiTraceChain provides C++ and C APIs. The upper-layer services mainly use HiTraceChain to start and stop call chain tracing. + **Figure 4** Time delay in the service calling process -HiTraceChain is implemented at layer C. It works by transferring **traceid** throughout the service calling process. Before service processing, HiTraceChain sets **traceid** in the thread local storage \(TLS\) of the calling thread. During service processing, HiTraceChain obtains **traceid** from the contextual TLS of the calling thread and automatically adds it to the log and event information. After service processing is complete, HiTraceChain clears **traceid** from the TLS of the calling thread. - -### Java, C++, and C APIs + ![](figures/time-delay-in-the-service-calling-process.png "time-delay-in-the-service-calling-process") -**Table 1** Description of C++ and C APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  

C++

-

C

-

Class

-

API

-

API

-

HiTraceChain

-

-

-

-

-

-

-

-

HiTraceId Begin(const std::string& name, int flags)

-

HiTraceIdStruct HiTraceChainBegin(const char* name, int flags)

-

void End(const HiTraceId& id)

-

void HiTraceChainEnd(const HiTraceIdStruct* pId)

-

HiTraceId GetId();

-

HiTraceIdStruct HiTraceChainGetId()

-

void SetId(const HiTraceId& id)

-

void HiTraceChainSetId(const HiTraceIdStruct* pId)

-

void ClearId()

-

void HiTraceChainClearId()

-

HiTraceId CreateSpan()

-

HiTraceIdStruct HiTraceChainCreateSpan()

-

void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

-

void HiTraceChainTracepoint(HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...)

-

void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

-

void HiTraceChainTracepointEx(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...)

-

HiTraceId

-

-

-

-

-

-

-

-

-

-

-

-

-

-

HiTraceId();

-

void HiTraceChainInitId(HiTraceIdStruct* pId)

-

HiTraceId(const uint8_t* pIdArray, int len)

-

HiTraceIdStruct HiTraceChainBytesToId(const uint8_t* pIdArray, int len)

-

bool IsValid()

-

int HiTraceChainIsValid(const HiTraceIdStruct* pId)

-

bool IsFlagEnabled(HiTraceFlag flag)

-

int HiTraceChainIsFlagEnabled(const HiTraceIdStruct* pId, HiTraceFlag flag)

-

void EnableFlag(HiTraceFlag flag)

-

void HiTraceChainEnableFlag(HiTraceIdStruct* pId, HiTraceFlag flag)

-

int GetFlags()

-

int HiTraceChainGetFlags(const HiTraceIdStruct* pId)

-

void SetFlags(int flags)

-

void HiTraceChainSetFlags(HiTraceIdStruct* pId, int flags)

-

uint64_t GetChainId()

-

uint64_t HiTraceChainGetChainId(const HiTraceIdStruct* pId)

-

void SetChainId(uint64_t chainId)

-

void HiTraceChainSetChainId(HiTraceIdStruct* pId, uint64_t chainId)

-

uint64_t GetSpanId()

-

uint64_t HiTraceChainGetSpanId(const HiTraceIdStruct* pId)

-

void SetSpanId(uint64_t spanId)

-

void HiTraceChainSetSpanId(HiTraceIdStruct* pId, uint64_t spanId)

-

uint64_t GetParentSpanId()

-

uint64_t HiTraceChainGetParentSpanId(const HiTraceIdStruct* pId)

-

void SetParentSpanId(uint64_t parentSpanId)

-

void HiTraceChainSetParentSpanId(HiTraceIdStruct* pId, uint64_t parentSpanId)

-

int ToBytes(uint8_t* pIdArray, int len)

-

int HiTraceChainIdToBytes(const HiTraceIdStruct* pId, uint8_t* pIdArray, int len)

-
+2. Add **traceid** to logs and events automatically to facilitate comprehensive analysis and quick fault location. -### Parameters of C++ APIs -**Table 2** Parameters of C++ APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Class

-

API

-

Description

-

HiTraceChain

-

-

-

-

-

-

-

-

HiTraceId Begin(const std::string& name, int flags)

-

Starts HiTraceChain, generates a HiTraceId object, and sets it in the TLS of the calling thread.

-

Input arguments:

-
  • name: Indicates the name of the service process.
  • flags: Indicates tracing flags, which can be used in combination.
    • HITRACE_FLAG_INCLUDE_ASYNC: Traces both synchronous and asynchronous calls. By default, only synchronous calls are traced.
    • HITRACE_FLAG_DONOT_CREATE_SPAN: Do not create a span. By default, a span is created.
    • HITRACE_FLAG_TP_INFO: Outputs the tracepoint information. By default, the information is not output.
    • HITRACE_FLAG_NO_BE_INFO: Do not output the start and end information. By default, the information is output.
    • HITRACE_FLAG_DONOT_ENABLE_LOG: Do not associate logs for output. By default, logs are associated for output.
    • HITRACE_FLAG_FAULT_TRIGGER: Triggers tracing by fault. By default, tracing is triggered normally.
    • HITRACE_FLAG_D2D_TP_INFO: Outputs the device-to-device tracepoint information. By default, the information is not output.
    • HITRCE_FLAG_DEFAULT: Indicates the default flag.
    -
  • Output arguments: none
  • Return value: Returns a valid HiTraceId object if call chain tracing is triggered successfully; returns an invalid object otherwise.
-

Note: In nested tracing mode, an invalid object will be returned if tracing is started at the nested layer.

-

void End(const HiTraceId& id)

-

Stops HiTraceChain based on the HiTraceId object returned by the Begin API, and clears the HiTraceId object in the TLS of the calling thread.

-

Input arguments:

-
  • id: Indicates the HiTraceId object.
-

Output arguments: none

-

Return value: none

-

HiTraceId GetId();

-

Obtains the HiTraceId object from the TLS of the calling thread.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the HiTraceId object in the contextual TLS of the calling thread.

-

void SetId(const HiTraceId& id)

-

Purpose: Sets the HiTraceId object in the TLS of the calling thread.

-

Input arguments:

-
  • id: Indicates the HiTraceId object.
-

Output arguments: none

-

Return value: none

-

void ClearId()

-

Clears the HiTraceId object in the TLS of the current thread.

-

Input arguments: none

-

Output arguments: none

-

Return value: none

-

HiTraceId CreateSpan()

-

Obtains the span ID from the current HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the current span ID.

-

void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

-

Outputs HiTraceChain call chain information based on the information type. The information includes the timestamp and HiTraceId object information of the span.

-

Input arguments:

-
  • type: Indicates the information type. The options are as follows:
    • HITRACE_TP_CS: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.
    • HITRACE_TP_SR: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.
    • HITRACE_TP_SS: Server Send, which indicates the response messages sent by the server in synchronous communication.
    • HITRACE_TP_CR: Client Receive, which indicates the response messages received by the synchronous communication client.
    • HITRACE_TP_GENERAL: Indicates the common output information.
    -
  • id: Indicates the ID of the current span.
  • fmt: Indicates the string describing the format variable parameter.
  • args: Indicates the variable parameter.
-

Output arguments: none

-

Return value: none

-

void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

-

Outputs HiTraceChain call chain information based on the communication mode and information type. The information includes the timestamp and HiTraceId object information of the span.

-

Input arguments:

-
  • mode: Indicates the communication mode. The options are as follows:
    • HITRACE_CM_DEFAULT: default communication mode used when no communication mode is specified
    • HITRACE_CM_THREAD: inter-thread communication
    • HITRACE_CM_PROCESS: inter-process communication
    • HITRACE_CM_DEVICE: inter-device communication
    -
  • type: Indicates the information type. The options are as follows:
    • HITRACE_TP_CS: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.
    • HITRACE_TP_SR: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.
    • HITRACE_TP_SS: Server Send, which indicates the response messages sent by the server in synchronous communication.
    • HITRACE_TP_CR: Client Receive, which indicates the response messages received by the synchronous communication client.
    • HITRACE_TP_GENERAL: Indicates the common output information.
    -
  • id: Indicates the ID of the current span.
  • fmt: Indicates the string describing the format variable parameter.
  • args: Indicates the variable parameter.
-

Output arguments: none

-

Return value: none

-

HiTraceId

-

-

-

-

-

-

-

-

-

-

-

-

-

-

HiTraceId();

-

Represents the default constructor used to generate an invalid HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: none

-

HiTraceId(const uint8_t* pIdArray, int len)

-

Represents the constructor used to create a HiTraceId object based on the specified byte array.

-
Input arguments:
  • pIdArray: Indicates the pointer to a byte array.
  • len: Indicates the length of the byte array.
-
-

Output arguments: none

-

Return value: none

-

bool IsValid()

-

Checks whether the HiTraceId object is valid.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns true if the HiTraceId object is valid; returns false otherwise.

-

bool IsFlagEnabled(HiTraceFlag flag)

-

Checks whether the tracing flag of the HiTraceId object is enabled.

-

Input arguments:

-
  • flag: Indicates the tracing flag. For details, see the description in the Begin function.
-

Output arguments: none

-

Return value: Returns true if the tracing flag is enabled; returns false otherwise.

-

void EnableFlag(HiTraceFlag flag)

-

Enables the tracing flag of the HiTraceId object.

-

Input arguments:

-
  • flag: Indicates the tracing flag. For details, see the description in the Begin function.
-

Output arguments: none

-

Return value: none

-

int GetFlags()

-

Obtains the tracing flag set in the HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the combination of tracing flags. For details, see the description in the Begin function.

-

void SetFlags(int flags)

-

Sets a tracing flag in the HiTraceId object.

-

Input arguments:

-
  • flags: Indicates the combination of tracing flags. For details, see the description in the Begin function.
-

Output arguments: none

-

Return value: none

-

uint64_t GetChainId()

-

Obtains the call chain ID.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the call chain ID.

-

void SetChainId(uint64_t chainId)

-

Sets the call chain ID in the HiTraceId object.

-

Input arguments:

-
  • chainId: Indicates the call chain ID.
-

Output arguments: none

-

Return value: none

-

uint64_t GetSpanId()

-

Obtains the span ID from the current HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the current span ID.

-

void SetSpanId(uint64_t spanId)

-

Sets the span ID in the HiTraceId object.

-

Input arguments:

-
  • spanId: Indicates the span ID.
-

Output arguments: none

-

Return value: none

-

uint64_t GetParentSpanId()

-

Obtains the parent span ID from the current HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the parent span ID.

-

void SetParentSpanId(uint64_t parentSpanId)

-

Sets the parent span ID in the HiTraceId object.

-

Input arguments:

-
  • parentSpanId: Indicates the parent span ID.
-

Output arguments: none

-

Return value: none

-

int ToBytes(uint8_t* pIdArray, int len)

-

Converts the HiTraceId object into a byte array to facilitate caching or communication transfer.

-

Input arguments:

-
  • pIdArray: Indicates the pointer to a byte array. The minimum length of the byte array is HITRACE_ID_LEN.
  • len: Indicates the length of the byte array.
-

Output arguments

-
  • pIdArray: Indicates the pointer to a byte array. If the object is valid, the object data after conversion is stored.
-

Return value: Returns a value greater than 0 (indicating a valid array of object data) if the conversion is successful; returns 0 otherwise.

-
- -## Call Chain Processing - -Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. **HiTraceChain** requires transfer of **traceid** in the communication mechanism. - -Some built-in communication mechanisms \(such as ZIDL\) of OpenHarmony already support the transfer of **traceid**. - -The following figure shows the process of transferring **traceid** in synchronous call. The process of transferring **traceid** in asynchronous call is similar. - -Extended communication mechanisms can also follow this implementation. - -**Figure 5** Call chain tracing in synchronous communication - -![](figures/call-chain-tracing-in-synchronous-communication.png "call-chain-tracing-in-synchronous-communication") +## Available APIs -The process is as follows: +HiTraceChain provides C++ and C APIs. The upper-layer services mainly use HiTraceChain to start and stop call chain trace. -1. The service module on the client calls the **begin\(\)** function to start call chain tracing. -2. The service module on the client synchronously calls the **transact** function to the communication component on the client. -3. The communication component on the client performs the following: - 1. Obtains **traceid** from the TLS of the calling thread. - 2. Generates child **traceid**. - 3. Writes child **traceid** into the transaction data \(synchronous communication data\). - 4. Performs Client Send \(CS\) tracing. - 5. Sends communication data to the communication component on the server. - -4. On receiving the communication data, the communication component on the server performs the following: - 1. Obtains **traceid** from the data message package. - 2. Sets **traceid** in the TLS of the calling thread. - 3. Performs Server Receive \(SR\) tracing. - 4. Synchronously call the **onTransact** callback to the service module on the server. - -5. The service module on the server processes the service and sends the transact reply message carrying the processing result to the communication component. -6. The communication component on the server performs the following: - 1. Performs Server Send \(SS\) tracing. - 2. Sends communication data to the communication component on the client. - 3. Clears **traceid** from the TLS of the calling thread. - -7. On receiving the communication data, the communication component on the client performs the following: - 1. Performs Client Receive \(CR\) tracing. - 2. Sends a transact reply response to the service module on the client. - -8. The service module on the client processes the transact reply response. -9. When the process ends, the service module on the client calls the **end\(\)** function to stop call chain tracing. +HiTraceChain is implemented at layer C. It works by transferring **traceid** throughout the service calling process. Before service processing, HiTrace sets **traceid** in the thread local storage (TLS) of the calling thread. During service processing, HiTrace obtains **traceid** from the contextual TLS of the calling thread and automatically adds it to the log and event information. After service processing is complete, HiTrace clears **traceid** from the TLS of the calling thread. -## How to Develop -### C++ +### Java, C++, and C APIs -1. Develop the source code. + **Table 1** Description of C++ and C APIs + +| | **C++** | **C** | +| -------- | -------- | -------- | +| **Class**| **Function**| **Function**| +| HiTraceChain | HiTraceId Begin(const std::string& name, int flags) | HiTraceIdStruct HiTraceChainBegin(const char* name, int flags) | +| | void End(const HiTraceId& id) | void HiTraceChainEnd(const HiTraceIdStruct* pId) | +| | HiTraceId GetId(); | HiTraceIdStruct HiTraceChainGetId() | +| | void SetId(const HiTraceId& id) | void HiTraceChainSetId(const HiTraceIdStruct* pId) | +| | void ClearId() | void HiTraceChainClearId() | +| | HiTraceId CreateSpan() | HiTraceIdStruct HiTraceChainCreateSpan() | +| | void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | void HiTraceChainTracepoint(HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...) | +| | void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | void HiTraceChainTracepointEx(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...) | +| HiTraceId | HiTraceId(); | void HiTraceChainInitId(HiTraceIdStruct* pId) | +| | HiTraceId(const uint8_t* pIdArray, int len) | HiTraceIdStruct HiTraceChainBytesToId(const uint8_t* pIdArray, int len) | +| | bool IsValid() | int HiTraceChainIsValid(const HiTraceIdStruct* pId) | +| | bool IsFlagEnabled(HiTraceFlag flag) | int HiTraceChainIsFlagEnabled(const HiTraceIdStruct* pId, HiTraceFlag flag) | +| | void EnableFlag(HiTraceFlag flag) | void HiTraceChainEnableFlag(HiTraceIdStruct* pId, HiTraceFlag flag) | +| | int GetFlags() | int HiTraceChainGetFlags(const HiTraceIdStruct* pId) | +| | void SetFlags(int flags) | void HiTraceChainSetFlags(HiTraceIdStruct* pId, int flags) | +| | uint64_t GetChainId() | uint64_t HiTraceChainGetChainId(const HiTraceIdStruct* pId) | +| | void SetChainId(uint64_t chainId) | void HiTraceChainSetChainId(HiTraceIdStruct* pId, uint64_t chainId) | +| | uint64_t GetSpanId() | uint64_t HiTraceChainGetSpanId(const HiTraceIdStruct* pId) | +| | void SetSpanId(uint64_t spanId) | void HiTraceChainSetSpanId(HiTraceIdStruct* pId, uint64_t spanId) | +| | uint64_t GetParentSpanId() | uint64_t HiTraceChainGetParentSpanId(const HiTraceIdStruct* pId) | +| | void SetParentSpanId(uint64_t parentSpanId) | void HiTraceChainSetParentSpanId(HiTraceIdStruct* pId, uint64_t parentSpanId) | +| | int ToBytes(uint8_t* pIdArray, int len) | int HiTraceChainIdToBytes(const HiTraceIdStruct_ pId, uint8_t* pIdArray, int len) | - Include the **hitracechain** header file in the class definition header file or class implementation source file. For example: - ``` - #include "hitrace/tracechain.h" - ``` +### Parameters of C++ APIs - Add the code to start and stop call chain tracing in the class implementation source file. + **Table 2** Trace flag combination types + +| **Name**| **Value**| **Description**| +| -------- | -------- | -------- | +| HITRACE_FLAG_DEFAULT | 0 | Default flag. | +| HITRACE_FLAG_INCLUDE_ASYNC | 1 | Asynchronous call flag. By default, only synchronous calls are traced. If this flag is set, both synchronous and asynchronous calls will be traced. | +| HITRACE_FLAG_DONOT_CREATE_SPAN | 1 << 1 | No span flag. By default, spans are created within a trace of synchronous and asynchronous service calls. If this flag is set, no spans are created. | +| HITRACE_FLAG_TP_INFO | 1 << 2 | Trace point flag. By default, no trace point is added when trace is enabled. This flag is used for debugging. If this flag is set, trace points will be automatically added on the TX and RX sides of synchronous and asynchronous calls to output trace point and timestamp information. Trace points are classified into four types: client send (CS), server receive (SR), server send (SS), and client receive (CR). For a synchronous call, the output trace points are CS, SR, SS, and CR; for an asynchronous call, the output trace points are CS, SR, and SS. | +| HITRACE_FLAG_NO_BE_INFO | 1 << 3 | No begin/end flag. By default, information about the start and end of the trace task is printed. If this flag is set, information about the start and end of the trace task will not be printed.| +| HITRACE_FLAG_DONOT_ENABLE_LOG | 1 << 4 | Log association flag. If this flag is set, information about the trace task will not be printed. | +| HITRACE_FLAG_FAULT_TRIGGER | 1 << 5 | Failure trigger flag. This flag is reserved for future use. | +| HITRACE_FLAG_D2D_TP_INFO | 1 << 6 | Device-to-device trace point flag. It is a subset of **TP_INFO**. If this flag is set, trace points are added only for call chain trace between devices.| + + **Table 3** Trace point types + +| **Name**| **Value**| **Description**| +| -------- | -------- | -------- | +| HITRACE_TP_CS | 0 | CS trace point. | +| HITRACE_TP_CR | 1 | CR trace point. | +| HITRACE_TP_SS | 2 | SS trace point. | +| HITRACE_TP_SR | 3 | SR trace point. | +| HITRACE_TP_GENERAL | 4 | General trace points except CS, CR, SS, and SR.| + + **Table 4** Communication modes + +| **Name**| **Value**| **Description**| +| -------- | -------- | -------- | +| HITRACE_CM_DEFAULT | 0 | Default communication mode. | +| HITRACE_CM_THREAD | 1 | Inter-thread communication. | +| HITRACE_CM_PROCESS | 2 | Inter-process communication. | +| HITRACE_CM_DEVICE | 3 | Inter-device communication. | + + **Table 5** Description of C++ APIs + +| **Class**| **API**| **Description**| +| -------- | -------- | -------- | +| HiTraceChain | HiTraceId Begin(const std::string& name, int flags) | Starts HiTraceChain, generates a **HiTraceId** object, and sets it in the TLS of the calling thread.
Input arguments:
- **name**: name of the service process.
- **flags**: trace flags, which can be used in combination. For details, see Table 2.
Output arguments: none
Return value: a valid **HiTraceId** object if call chain trace is triggered successfully; returns an invalid object otherwise.
Note: In nested trace mode, an invalid object will be returned if trace is started at the nested layer.| +| | void End(const HiTraceId& id) | Stops HiTraceChain based on the **HiTraceId** object returned by the **Begin** API, and clears the **HiTraceId** object in the TLS of the calling thread.
Input arguments:
- **id**: **HiTraceId** object.
Output arguments: none
Return value: none| +| | HiTraceId GetId(); | Obtains the **HiTraceId** object from the TLS of the calling thread.
Input arguments: none
Output arguments: none
Return value: **HiTraceId** object in the contextual TLS of the calling thread.| +| | void SetId(const HiTraceId& id) | Purpose: Sets the **HiTraceId** object in the TLS of the calling thread.
Input arguments:
- **id**: **HiTraceId** object.
Output arguments: none
Return value: none| +| | void ClearId() | Clears the **HiTraceId** object in the TLS of the calling thread.
Input arguments: none
Output arguments: none
Return value: none| +| | HiTraceId CreateSpan() | Obtains the span ID from the current **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: current span ID.| +| | void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | Outputs HiTraceChain trace point information based on the information type. The information includes the timestamp and **HiTraceId** object of the span.
Input arguments:
- **type**: trace point type. For details, see Table 3.
- **id**: ID of the current span.
- **fmt**: string describing the format variable parameter.
- **args**: variable parameter.
Output arguments: none
Return value: none| +| | void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | Outputs HiTraceChain trace point information based on the communication mode and information type. The information includes the timestamp and **HiTraceId** object of the span.
Input arguments:
- **mode**: communication mode. For details, see Table 4.
- **type**: trace point type. For details, see Table 3.
- **id**: ID of the current span.
- **fmt**: string describing the format variable parameter.
- **args**: variable parameter.
Output arguments: none
Return value: none| +| HiTraceId | HiTraceId(); | Represents the default constructor used to generate an invalid **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: none| +| | HiTraceId(const uint8_t* pIdArray, int len) | Represents the constructor used to create a **HiTraceId** object based on the specified byte array.
Input arguments:
- **pIdArray**: pointer to a byte array.
- **len**: length of the byte array.
Output arguments: none
Return value: none| +| | bool IsValid() | Checks whether the **HiTraceId** object is valid.
Input arguments: none
Output arguments: none
Return value: **true** if the **HiTraceId** object is valid; **false** otherwise.| +| | bool IsFlagEnabled(HiTraceFlag flag) | Checks whether the trace flag of the **HiTraceId** object is enabled.
Input arguments:
- **flag**: trace flag. For details, see the description in the **Begin** function.
Output arguments: none
Return value: **true** if the trace flag is enabled; **false** otherwise.| +| | void EnableFlag(HiTraceFlag flag) | Enables the trace flag of the **HiTraceId** object.
Input arguments:
- **flag**: trace flag. For details, see the description in the **Begin** function.
Output arguments: none
Return value: none| +| | int GetFlags() | Obtains the trace flag set in the **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: Returns the combination of trace flags. For details, see the description in the **Begin** function.| +| | void SetFlags(int flags) | Sets a trace flag in the **HiTraceId** object.
Input arguments:
- **flags**: combination of trace flags. For details, see the description in the **Begin** function.
Output arguments: none
Return value: none| +| | uint64_t GetChainId() | Obtains the call chain ID.
Input arguments: none
Output arguments: none
Return value: call chain ID.| +| | void SetChainId(uint64_t chainId) | Sets the call chain ID in the **HiTraceId** object.
Input arguments:
- **chainId**: call chain ID.
Output arguments: none
Return value: none| +| | uint64_t GetSpanId() | Obtains the span ID from the current **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: current span ID.| +| | void SetSpanId(uint64_t spanId) | Sets the span ID in the **HiTraceId** object.
Input arguments:
- **spanId**: span ID.
Output arguments: none
Return value: none| +| | uint64_t GetParentSpanId() | Obtains the parent span ID from the current **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: parent span ID.| +| | void SetParentSpanId(uint64_t parentSpanId) | Sets the parent span ID in the **HiTraceId** object.
Input arguments:
- **parentSpanId**: parent span ID.
Output arguments: none
Return value: none| +| | int ToBytes(uint8_t* pIdArray, int len) | Converts the **HiTraceId** object into a byte array to facilitate caching or communication transfer.
Input arguments:
- **pIdArray**: pointer to a byte array. The minimum length of the byte array is **HITRACE_ID_LEN**.
- **len**: length of the byte array.
Output parameters:
- **pIdArray**: pointer to a byte array. If the object is valid, the object data after conversion is stored.
Return value: a value greater than **0** (indicating a valid array of object data) if the conversion is successful; **0** otherwise.| + + +### Call Chain Processing + +Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. HiTraceChain requires transfer of **traceid** in the communication mechanism. + +Some built-in communication mechanisms (such as ZIDL) of OpenHarmony already support the transfer of **traceid**. + +The following figure shows the process of transferring **traceid** in synchronous call. The process of transferring **traceid** in asynchronous call is similar. + + Extended communication mechanisms can also follow this implementation. + + **Figure 5** Call chain trace in synchronous communication + + ![](figures/call-chain-trace-in-synchronous-communication.png "call-chain-trace-in-synchronous-communication") - ``` - using namespace OHOS::HiviewDFX; - auto traceId = HiTraceChain::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT); - ... - HiTraceChain::End(traceId); - ``` +The process is as follows: -2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. +1. The service module on the client calls the **begin()** function to start call chain trace. - ``` - external_deps = [ "hiviewdfx:libhitracechain" ] - ``` +2. The service module on the client synchronously calls the **transact** function to the communication component on the client. +3. The communication component on the client performs the following: + 1. Obtains **traceid** from the TLS of the calling thread. + 2. Generates child **traceid**. + 3. Writes child **traceid** into the transaction data (synchronous communication data). + 4. Performs CS trace. + 5. Sends communication data to the communication component on the server. -### C +4. On receiving the communication data, the communication component on the server performs the following: + 1. Obtains **traceid** from the data message package. + 2. Sets **traceid** in the TLS of the calling thread. + 3. Performs SR trace. + 4. Synchronously calls the **onTransact** callback to the service module on the server. -1. Develop the source code. +5. The service module on the server processes the service and sends the transact reply message carrying the processing result to the communication component. - Include the **hitracechain** header file in the source file. +6. The communication component on the server performs the following: + 1. Performs SS trace. + 2. Sends communication data to the communication component on the client. + 3. Clears **traceid** from the TLS of the calling thread. - ``` - #include "hitrace/tracechain.h" - ``` +7. On receiving the communication data, the communication component on the client performs the following: + 1. Performs CR trace. + 2. Sends a transact reply response to the service module on the client. - Add the code to start and stop call chain tracing in the class implementation source file. +8. The service module on the client processes the transact reply response. - ``` - HiTraceIdStruct traceId = HiTraceChainBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT); - ... - HiTraceChainEnd(traceId); - ``` +9. When the process ends, the service module on the client calls the **end()** function to stop call chain trace. -2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. - ``` - external_deps = [ "hiviewdfx:libhitracechain" ] - ``` +## How to Develop +### **C++** + +1. Develop the source code. + Include the **hitracechain** header file in the class definition header file or class implementation source file. For example: + + ``` + #include "hitrace/tracechain.h" + ``` + + Add the code to start and stop call chain trace in the class implementation source file. + + ``` + using namespace OHOS::HiviewDFX; + auto traceId = HiTraceChain::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT); + ...... + HiTraceChain::End(traceId); + ``` + +2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. + + ``` + external_deps = [ "hiviewdfx:libhitracechain" ] + ``` + + +### **C** + +1. Develop the source code. + Include the **hitracechain** header file in the source file. + + ``` + #include "hitrace/tracechain.h" + ``` + + Add the code to start and stop call chain trace in the class implementation source file. + + ``` + HiTraceIdStruct traceId = HiTraceChainBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT); + ...... + HiTraceChainEnd(traceId); + ``` + +2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. + + ``` + external_deps = [ "hiviewdfx:libhitracechain" ] + ``` diff --git a/en/device-dev/subsystems/subsys-dfx-hitracemeter.md b/en/device-dev/subsystems/subsys-dfx-hitracemeter.md index 0a71a05955014984d157f75b2f7e9b8c0b2d757d..bb609b7369d03ae82b7782421c3ec96344bcc840 100644 --- a/en/device-dev/subsystems/subsys-dfx-hitracemeter.md +++ b/en/device-dev/subsystems/subsys-dfx-hitracemeter.md @@ -2,16 +2,17 @@ ## Introduction -HiTraceMeter is the OpenHarmony subsystem that provides APIs to implement call chain trace throughout a service process. With HiTraceMeter, you can quickly obtain the run log specific to the call chain of a service process and locate faults in inter-device, inter-process, or inter-thread communications. HiTraceMeter supports event logging in user mode and can collect trace data in user mode and kernel mode for performance tracing and analysis. +HiTraceMeter is the OpenHarmony subsystem that provides APIs to implement call chain trace throughout a service process. With HiTraceMeter, you can quickly obtain the run log specific to the call chain of a service process and locate faults in inter-device, inter-process, or inter-thread communications. HiTraceMeter supports event logging in user mode and can collect trace data in user mode and kernel mode for performance trace and analysis. ## Basic Concepts The HiTraceMeter subsystem consists of three parts: + - JS/C++ HiTraceMeter APIs for application logging - hitrace CLI tool for data collection - smartperf tool for graphical data analysis -Wherein, HiTraceMeter APIs and the hitrace CLI tool run on the device side, and the smartperf tool runs on the PC side. HiTraceMeter APIs are provided in C++ and JS for event logging, which aims to generate the trace data necessary for performance tracing and analysis during the development process. +Wherein, HiTraceMeter APIs and the hitrace CLI tool run on the device side, and the smartperf tool runs on the PC side. HiTraceMeter APIs are provided in C++ and JS for event logging, which aims to generate the trace data necessary for performance trace and analysis during the development process. The hitrace CLI tool is used to collect trace data. It captures trace data flows and saves the data as a text file. @@ -80,14 +81,13 @@ HiTraceMeter provides the hitrace CLI tool for capturing trace data in user mode - ## Constraints - The implementation of HiTraceMeter functions and APIs depends on the ftrace functionality, a framework provided by the kernel. It enables developers to add more trace functions via plug-ins. Therefore, make sure that ftrace is enabled before you use HiTraceMeter. - For most Linux kernels, ftrace is enabled by default. For details, see the ftrace documentation you may obtain. + For most Linux kernels, ftrace is enabled by default. For details, see the ftrace documentation you may obtain. - HiTraceMeter is available only for the mini system and standard system. - - + + # HiTraceMeter Development @@ -95,7 +95,6 @@ HiTraceMeter development focuses on two parts: JS/C++ event logging APIs and the - ## When to Use You may encounter unexpected issues like app freezing during app development or need to view the code's call chain during code debugging. With the APIs provided by HiTraceMeter, you'll be able to trace the application delay and call chain to identify performance problems. @@ -106,20 +105,19 @@ Only C++ APIs are now open for system developers. If you're developing a JS app, **Table 1** Sync APIs -| Sync trace | Function |Parameter Description | -| :----------------------------------------------------------- | ------------- |------------- | -| void StartTrace(uint64_t label, const std::string& value, float limit = -1); | Starts a synchronous trace.|**label**: trace category.
**value**: trace data that indicates the specific status, such as the memory size and queue length.| -| void FinishTrace(uint64_t label); | Stops a synchronous trace.|**label**: trace category.| - +| Sync trace | Function | Parameter Description | +|:---------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------- | +| void StartTrace(uint64_t label, const std::string& value, float limit = -1); | Starts a synchronous trace.| **label**: trace category.
**value**: trace data that indicates the specific status, such as the memory size and queue length.| +| void FinishTrace(uint64_t label); | Stops a synchronous trace.| **label**: trace category. | **StartTrace** and **FinishTrace** must be used in pairs, and **FinishTrace** matches the latest **StartTrace**. The two APIs can be used in nested mode. The stack data structure is used for matching during trace data parsing. The **limit** parameter is used for flow control, and you are advised to use the default value. **Table 2** Async APIs -| Async trace | Function |Parameter Description | -| ------------------------------------------------------------ | ------------- |------------- | +| Async trace | Function | Parameter Description | +| ------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------- | | void StartAsyncTrace(uint64_t label, const std::string& value, int32_t taskId, float limit = -1); | Starts an asynchronous trace.| **label**: trace category.
**value**: trace data that indicates the specific status, such as the memory size and queue length.
**taskId**: ID used to indicate the association of APIs in an asynchronous trace.| -| void FinishAsyncTrace(uint64_t label, const std::string& value, int32_t taskId); | Stops an asynchronous trace.| **label**: trace category.
**value**: trace data that indicates the specific status, such as the memory size and queue length.
**taskId**: ID used to indicate the association of APIs in an asynchronous trace.| +| void FinishAsyncTrace(uint64_t label, const std::string& value, int32_t taskId); | Stops an asynchronous trace.| **label**: trace category.
**value**: trace data that indicates the specific status, such as the memory size and queue length.
**taskId**: ID used to indicate the association of APIs in an asynchronous trace.| @@ -127,145 +125,144 @@ The trace data of **StartAsyncTrace** and **FinishAsyncTrace** is matched based **Table 3** Counter APIs -| Counter Trace | Function |Parameter Description | -| ------------------------------------------------------------ | --------- |--------- | -| void CountTrace(uint64_t label, const std::string& name, int64_t); | Count trace.|**label**: trace category.
**name**: trace name displayed in the IDE.| - +| Counter Trace | Function | Parameter Description | +| ------------------------------------------------------------------ | ------- | -------------------------------------------------------------- | +| void CountTrace(uint64_t label, const std::string& name, int64_t); | Count trace.| **label**: trace category.
**name**: trace name displayed in the IDE.| ## How to Develop + 1. Add the build dependencies to the build configuration file **base\hiviewdfx\hitrace\cmd\BUILD.gn**. + + ``` + external_deps = [ "hitrace_native:hitrace_meter"] + ``` - ``` - external_deps = [ "hitrace_native:hitrace_meter"] - ``` 2. Add the header file dependencies. - - ```cpp - #include "hitrace_meter.h"// Header file for defining APIs - ``` + + ```cpp + #include "hitrace_meter.h"// Header file for defining APIs + ``` 3. When calling an API, pass the trace value as an input parameter. The trace tags currently supported are listed in **hitrace_meter.h**. Assume that the trace tag is **OHOS** and trace data of **func1** and **func2** needs to be captured. After the hitrace command is executed in the shell, the trace data is automatically captured. The captured data includes the function call process and the memory and time consumed during this process. You can use the data to analyze the call process to identify performance problems. - - -```cpp -#include "hitrace_meter.h" // Include hitrace_meter.h -using namespace std; - -int main() -{ - uint64_t label = BYTRACE_TAG_OHOS; - sleep(1); - CountTrace(label, "count number", 2000); // Integer trace - - StartTrace(label, "func1Trace", -1); // Trace start point of func1Start - sleep(1); - StartTrace(label, "func2Trace", -1); // Trace start point of func2Start - sleep(2); - FinishTrace (label); // Trace end point of func2Trace - sleep(1); - FinishTrace(label); // Trace end point of func1Trace - - StartAsyncTrace(label, "asyncTrace1", 1234); // Trace start point of asyncTrace1 - FinishAsyncTrace(label, "asyncTrace1", 1234); // Trace end point of asyncTrace2 - - return 0; - } - ``` + + ```cpp + #include "hitrace_meter.h" // Include hitrace_meter.h + using namespace std; + + int main() + { + uint64_t label = BYTRACE_TAG_OHOS; + sleep(1); + CountTrace(label, "count number", 2000); // Integer trace + + StartTrace(label, "func1Trace", -1); // Trace start point of func1Start + sleep(1); + StartTrace(label, "func2Trace", -1); // Trace start point of func2Start + sleep(2); + FinishTrace (label); // Trace end point of func2Trace + sleep(1); + FinishTrace(label); // Trace end point of func1Trace + + StartAsyncTrace(label, "asyncTrace1", 1234); // Trace start point of asyncTrace1 + FinishAsyncTrace(label, "asyncTrace1", 1234); // Trace end point of asyncTrace1 + + return 0; + } + ``` 4. On completion of HiTraceMeter building and deployment, start a trace. After you run the application in the shell on the device, trace data will be captured automatically. - - ``` - hdc_std shell hitrace -t 10 ohos > .\myapp_demo.ftrace - ``` - - You can open the captured data by clicking **Open trace file** in the smartperf tool or dragging the data to the graphics area. For details, see [smartperf](https://toscode.gitee.com/openharmony-sig/smartperf). - + + ``` + hdc_std shell hitrace -t 10 ohos > .\myapp_demo.ftrace + ``` + + You can open the captured data by clicking **Open trace file** in the smartperf tool or dragging the data to the graphics area. For details, see [smartperf](https://toscode.gitee.com/openharmony-sig/smartperf). ## Verification The following is a demo debugging process, where the **StartTrace** and **FinishTrace** APIs are used in synchronization mode. 1. Write the test code file [hitrace_example.cpp](https://gitee.com/openharmony/hiviewdfx_hitrace/blob/master/cmd/example/hitrace_example.cpp) by adding the **StartTrace** and **FinishTrace** APIs to the code. - - ```cpp - int main() - { - thread t1(ThreadFunc1); - t1.join(); - - StartTrace(LABEL, "testStart"); - sleep(SLEEP_ONE_SECOND); - - StartTrace(LABEL, "funcAStart", SLEEP_ONE_SECOND); // Trace start point - FuncA(); - FinishTrace(LABEL); - sleep(SLEEP_TWO_SECOND); - - thread t2(ThreadFunc2); - t2.join(); - - StartTrace(LABEL, "funcBStart", SLEEP_TWO_SECOND); - FuncB(); - FinishTrace(LABEL);// Trace end point - sleep(SLEEP_TWO_SECOND); - - sleep(SLEEP_ONE_SECOND); - FinishTrace(LABEL); - FuncC(); - - return 0; - } - ``` + + ```cpp + int main() + { + thread t1(ThreadFunc1); + t1.join(); + + StartTrace(LABEL, "testStart"); + sleep(SLEEP_ONE_SECOND); + + StartTrace(LABEL, "funcAStart", SLEEP_ONE_SECOND); // Trace start point + FuncA(); + FinishTrace(LABEL); + sleep(SLEEP_TWO_SECOND); + + thread t2(ThreadFunc2); + t2.join(); + + StartTrace(LABEL, "funcBStart", SLEEP_TWO_SECOND); + FuncB(); + FinishTrace(LABEL);// Trace end point + sleep(SLEEP_TWO_SECOND); + + sleep(SLEEP_ONE_SECOND); + FinishTrace(LABEL); + FuncC(); + + return 0; + } + ``` 2. Modify the **base\hiviewdfx\hitrace\cmd\BUILD.gn** file, and start building. - - ``` - ohos_executable("hitrace_example") { - sources = [ "example/hitrace_example.cpp" ] - - external_deps = [ "hitrace_native:hitrace_meter" ] - - subsystem_name = "hiviewdfx" - part_name = "hitrace_native" - } - - group("hitrace_target") { - deps = [ - ":hitrace", - ":hitrace_example", - ] - } - ``` + + ``` + ohos_executable("hitrace_example") { + sources = [ "example/hitrace_example.cpp" ] + + external_deps = [ "hitrace_native:hitrace_meter" ] + + subsystem_name = "hiviewdfx" + part_name = "hitrace_native" + } + + group("hitrace_target") { + deps = [ + ":hitrace", + ":hitrace_example", + ] + } + ``` 3. Place the **hitrace_example** executable file in the **/system/bin** directory of the device, and run the following commands in sequence in the shell: - - ```shell - hitrace --trace_begin ohos - hitrace_exampe - hitrace --trace_dump - ``` - + + ```shell + hitrace --trace_begin ohos + hitrace_exampe + hitrace --trace_dump + ``` + If the expected trace value is present in the trace data, the capture of trace data is successful. For example: - - ``` - <...>-1651 (-------) [002] .... 327.194136: tracing_mark_write: S|1650|H:testAsync 111 - <...>-1650 (-------) [001] .... 332.197640: tracing_mark_write: B|1650|H:testStart - <...>-1650 (-------) [001] .... 333.198018: tracing_mark_write: B|1650|H:funcAStart - <...>-1650 (-------) [001] .... 334.198507: tracing_mark_write: E|1650| - <...>-1654 (-------) [003] .... 341.201673: tracing_mark_write: F|1650|H:testAsync 111 - <...>-1650 (-------) [001] .... 341.202168: tracing_mark_write: B|1650|H:funcBStart - <...>-1650 (-------) [001] .... 343.202557: tracing_mark_write: E|1650| - <...>-1650 (-------) [001] .... 346.203178: tracing_mark_write: E|1650| - <...>-1650 (-------) [001] .... 346.203457: tracing_mark_write: C|1650|H:count number 1 - <...>-1650 (-------) [001] .... 347.203818: tracing_mark_write: C|1650|H:count number 2 - <...>-1650 (-------) [001] .... 348.204207: tracing_mark_write: C|1650|H:count number 3 - <...>-1650 (-------) [001] .... 349.204473: tracing_mark_write: C|1650|H:count number 4 - <...>-1650 (-------) [001] .... 350.204851: tracing_mark_write: C|1650|H:count number 5 - <...>-1655 (-------) [001] .... 365.944658: tracing_mark_write: trace_event_clock_sync: realtime_ts=1502021460925 - <...>-1655 (-------) [001] .... 365.944686: tracing_mark_write: trace_event_clock_sync: parent_ts=365.944641 - ``` - - + + ``` + <...>-1651 (-------) [002] .... 327.194136: tracing_mark_write: S|1650|H:testAsync 111 + <...>-1650 (-------) [001] .... 332.197640: tracing_mark_write: B|1650|H:testStart + <...>-1650 (-------) [001] .... 333.198018: tracing_mark_write: B|1650|H:funcAStart + <...>-1650 (-------) [001] .... 334.198507: tracing_mark_write: E|1650| + <...>-1654 (-------) [003] .... 341.201673: tracing_mark_write: F|1650|H:testAsync 111 + <...>-1650 (-------) [001] .... 341.202168: tracing_mark_write: B|1650|H:funcBStart + <...>-1650 (-------) [001] .... 343.202557: tracing_mark_write: E|1650| + <...>-1650 (-------) [001] .... 346.203178: tracing_mark_write: E|1650| + <...>-1650 (-------) [001] .... 346.203457: tracing_mark_write: C|1650|H:count number 1 + <...>-1650 (-------) [001] .... 347.203818: tracing_mark_write: C|1650|H:count number 2 + <...>-1650 (-------) [001] .... 348.204207: tracing_mark_write: C|1650|H:count number 3 + <...>-1650 (-------) [001] .... 349.204473: tracing_mark_write: C|1650|H:count number 4 + <...>-1650 (-------) [001] .... 350.204851: tracing_mark_write: C|1650|H:count number 5 + <...>-1655 (-------) [001] .... 365.944658: tracing_mark_write: trace_event_clock_sync: realtime_ts=1502021460925 + <...>-1655 (-------) [001] .... 365.944686: tracing_mark_write: trace_event_clock_sync: parent_ts=365.944641 + ``` + + # Using the hitrace CLI Tool @@ -273,71 +270,82 @@ The hitrace CLI tool is an executable binary program. On an OpenHarmony-powered **Table 4** Command list -| Option | Description | -| ------------------------------ | ------------------------------------------------------------ | +| Option | Description | +| ----------------------------- | -------------------------------------------------------- | | -h, --help | Views the help Information. | -| -b *n*, --buffer_size *n* | Sets the buffer size for trace data in KB. The default value is **2048**. | -| -t *n*, --time *n* | Sets the trace uptime in seconds, which depends on the time required for analysis.| -| --trace_clock clock | Sets the type of the clock for adding a timestamp to a trace. The value can be **boot** (default), **global**, **mono**, **uptime**, or **perf**.| -| --trace_begin | Starts capturing trace data. | -| --trace_dump | Dumps trace data to the specified position. The default position is the console. | -| --trace_finish | Stops capturing trace data and dumps trace data to the specified position. The default position is the console. | -| -l, --list_categories | Lists the trace categories supported by the device. | -| --overwrite | Sets the action to take when the buffer is full. If this option is used, the latest trace data is discarded. If this option is not used, the earliest trace data is discarded (default). | -| -o *filename*, --output *filename*| Outputs trace data to the specified file. | -| -z | Compresses the trace data. | +| -b *n*, --buffer_size *n* | Sets the buffer size for trace data in KB. The default value is **2048**. | +| -t *n*, --time *n* | Sets the trace uptime in seconds, which depends on the time required for analysis. | +| --trace_clock clock | Sets the type of the clock for adding a timestamp to a trace. The value can be **boot** (default), **global**, **mono**, **uptime**, or **perf**.| +| --trace_begin | Starts capturing trace data. | +| --trace_dump | Dumps trace data to the specified position. The default position is the console. | +| --trace_finish | Stops capturing trace data and dumps trace data to the specified position. The default position is the console. | +| -l, --list_categories | Lists the trace categories supported by the device. | +| --overwrite | Sets the action to take when the buffer is full. If this option is used, the latest trace data is discarded. If this option is not used, the earliest trace data is discarded (default). | +| -o *filename*, --output *filename*| Outputs trace data to the specified file. | +| -z | Compresses the trace data. | Examples: - Query supported labels. - + ``` + hitrace -l + ``` - + Alternatively, run the following command: - + ``` + hitrace --list_categories + ``` - - Trace ability information for 10 seconds and store the trace data in a buffer of 4 MB. - + ``` + hitrace -b 4096 -t 10 --overwrite ability > /data/log/mytrace.ftrace + ``` - - Set the clock type to **mono**. - + ``` + hitrace --trace_clock mono -b 4096 -t 10 --overwrite ability > /data/log/mytrace.ftrace + ``` - - Compress the trace data. - + ``` + hitrace -z -b 4096 -t 10 --overwrite ability > /data/log/mytrace.ftrace + ``` - - + + # FAQs ### Incomplete or Empty Data Captured by hitrace -#### Symptom +#### Symptom + +The data captured by running the hitrace command is incomplete or no data is captured. + +#### **Root Cause** - The data captured by running the hitrace command is incomplete or no data is captured. +The value of **-t** or **-b** buffer is too small, leading to data loss. -#### Solution +#### Solution - Check the value of the **-t** and **-b** parameters. If the value is too small, data loss will occur. You are advised to set **-t** to **60** and **-b** to **204800** to increase the trace capture time and buffer, respectively. +You can set **-t** to **60** and **-b** to **204800** to increase the trace time and buffer size. # Reference -For details about HiTraceMeter, see [hiviewdfx_hitrace: A Lightweight Distributed Tracing](https://gitee.com/openharmony/hiviewdfx_hitrace). +For details about HiTraceMeter, see [hiviewdfx_hitrace: Lightweight Distributed Trace](https://gitee.com/openharmony/hiviewdfx_hitrace). diff --git a/en/device-dev/subsystems/subsys-dfx-overview.md b/en/device-dev/subsystems/subsys-dfx-overview.md index 791e7343b0f57c5c43667ba68027bb836c5f5929..623ed60d365a662b8e11bb6b8489128481eabe2f 100644 --- a/en/device-dev/subsystems/subsys-dfx-overview.md +++ b/en/device-dev/subsystems/subsys-dfx-overview.md @@ -1,39 +1,51 @@ -# DFX Overview +# DFX Overview -[Design for X](https://en.wikipedia.org/wiki/Design_for_X) \(DFX\) refers to the software design that aims to improve the quality attributes in OpenHarmony. It mainly consists of two parts: design for reliability \(DFR\) and design for testability \(DFT\). + +## Introduction + +[Design for X](https://en.wikipedia.org/wiki/Design_for_X) \(DFX\) refers to the software design that aims to improve the quality attributes in OpenHarmony. It mainly consists of two parts: design for reliability \(DFR\) and design for testability \(DFT\). The DFX subsystem provides the following functions: -- HiLog: implements the logging function. It is applicable to mini-system devices \(reference memory ≥ 128 KiB\), small-system devices \(reference memory ≥ 1 MiB\), and standard-system devices \(reference memory ≥ 128 MB\). -- HiTraceChain: implements distributed call chain tracing. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). +- HiLog: implements the logging function. It is applicable to mini-system devices \(reference memory ≥ 128 KiB\), small-system devices \(reference memory ≥ 1 MiB\), and standard-system devices \(reference memory ≥ 128 MiB\). + +- HiTraceChain: implements distributed call chain trace. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - HiTraceMeter: implements performance trace. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - HiCollie: implements thread suspension detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - HiSysEvent: implements system event logging. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - HiDumper: exports system information. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). -- FaultLogger: implements crash detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + +- Faultlogger: implements crash detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - Hiview: implements device maintenance across different platforms. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). -- HiAppEvent and HiChecker are only hap developer oriented。 + +- HiAppEvent and HiChecker are applicable only for HAP developers. ![dfx features overview](figure/dfx-overview.png) -## Basic Concepts +## Basic Concepts **Logging** Logging means to record the log information generated during system running so you can understand the running process and status of the system or applications. -**Distributed call chain tracing** +**Distributed call chain trace** -In a distributed system, the initiation of a service may involve multiple software modules, with control commands and data transmitted over intra-process, inter-process, and inter-device communication interfaces. To help you understand such complex communication processes and locate service faults efficiently, the DFX subsystem provides a distributed call chain tracing framework. +In a distributed system, the initiation of a service may involve multiple software modules, with control commands and data transmitted over intra-process, inter-process, and inter-device communication interfaces. To help you understand such complex communication processes and locate service faults efficiently, the DFX subsystem provides a distributed call chain trace framework. **Thread suspension detection** -If a thread is trapped in an infinite loop or the kernel state \(for example, Uninterruptable Sleep, Traced, Zombie, or synchronous wait\) when it is running, the thread cannot respond to normal service requests and cannot detect and recover from faults by itself. To detect and locate this type of faults, the DFX subsystem provides a simple watchdog mechanism by inserting detection probes to the process nodes that are prone to suspension. This ensures that suspension faults can be detected and logs can be collected. +If a thread is trapped in an infinite loop or the kernel state (for example, Uninterruptable Sleep, Traced, Zombie, or synchronous wait) when it is running, the thread cannot respond to normal service requests and cannot detect and recover from faults by itself. To detect and locate this type of faults, the DFX subsystem provides a simple watchdog mechanism by inserting detection probes to the process nodes that are prone to suspension. This ensures that suspension faults can be detected and logs can be collected. -**Event logging** +**Logging** Event logging means to collect and log events reported during system running. The log information will help you better analyze the product usage. **System event** A system event is an indication of the system status at a given time point during system running. You can use these events to analyze the status change of the system. +