From 3f581915ad795452d61d6f736f3b4313284c03cc Mon Sep 17 00:00:00 2001 From: shawn_he Date: Mon, 7 Mar 2022 20:22:26 +0800 Subject: [PATCH] update docs Signed-off-by: shawn_he --- .../reference/apis/js-apis-radio.md | 247 +++++++++++++----- 1 file changed, 183 insertions(+), 64 deletions(-) diff --git a/en/application-dev/reference/apis/js-apis-radio.md b/en/application-dev/reference/apis/js-apis-radio.md index a59cb7b534..2ced677171 100644 --- a/en/application-dev/reference/apis/js-apis-radio.md +++ b/en/application-dev/reference/apis/js-apis-radio.md @@ -15,9 +15,11 @@ import radio from '@ohos.telephony.radio' getRadioTech\(slotId: number, callback: AsyncCallback<\{psRadioTech: RadioTechnology, csRadioTech: RadioTechnology\}\>\): void -Obtains the radio access technologies (RATs) used by the CS and PS domains. This function uses an asynchronous callback to return the result. +Obtains the radio access technology (RAT) used by the CS and PS domains. This function uses an asynchronous callback to return the result. -Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. +**Required permission**: ohos.permission.GET_NETWORK_INFO + +**System capability**: SystemCapability.Telephony.CoreService **Parameters** @@ -42,7 +44,9 @@ getRadioTech\(slotId: number\): Promise<\{psRadioTech: RadioTechnology, csRadioT Obtains the RAT used by the CS and PS domains. This function uses a promise to return the result. -Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. +**Required permission**: ohos.permission.GET_NETWORK_INFO + +**System capability**: SystemCapability.Telephony.CoreService **Parameters** @@ -73,15 +77,17 @@ promise.then(data => { getNetworkState\(callback: AsyncCallback\): void -Obtains the network status of the SIM card in the specified slot. This function uses an asynchronous callback to return the result. +Obtains the network status. This function uses an asynchronous callback to return the result. -Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. +**Required permission**: ohos.permission.GET_NETWORK_INFO + +**System capability**: SystemCapability.Telephony.CoreService **Parameters** | Name| Type| Mandatory| Description| | -------- | ---------------------------------------------- | ---- | ---------- | -| callback | AsyncCallback\<[NetworkState](#NetworkState)\> | Yes| Callback invoked to traverse the entries in the container.| +| callback | AsyncCallback\<[NetworkState](#NetworkState)\> | Yes| Callback used to return the result.| **Example** @@ -98,7 +104,9 @@ getNetworkState\(slotId: number, callback: AsyncCallback\): void Obtains the network status of the SIM card in the specified slot. This function uses an asynchronous callback to return the result. -Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. +**Required permission**: ohos.permission.GET_NETWORK_INFO + +**System capability**: SystemCapability.Telephony.CoreService **Parameters** @@ -123,7 +131,9 @@ getNetworkState\(slotId?: number\): Promise Obtains the network status of the SIM card in the specified slot. This function uses a promise to return the result. -Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. +**Required permission**: ohos.permission.GET_NETWORK_INFO + +**System capability**: SystemCapability.Telephony.CoreService **Parameters** @@ -156,6 +166,8 @@ getNetworkSelectionMode\(slotId: number, callback: AsyncCallback Obtains the network selection mode of the SIM card in the specified slot. This function uses a promise to return the result. +**System capability**: SystemCapability.Telephony.CoreService + **Parameters** | Name| Type| Mandatory| Description| @@ -210,12 +224,14 @@ getISOCountryCodeForNetwork\(slotId: number, callback: AsyncCallback\): Obtains the ISO country code of the network with which the SIM card in the specified slot is registered. This function uses an asynchronous callback to return the result. +**System capability**: SystemCapability.Telephony.CoreService + **Parameters** | Name| Type| Mandatory| Description| | -------- | ----------------------- | ---- | ---------------------------------------- | | slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| -| callback | AsyncCallback\ | Yes| Callback used to return the result, which is a country code, for example, **CN** (China).| +| callback | AsyncCallback\ | Yes| Callback used to return the result. which is a country code, for example, **CN** (China).| **Example** @@ -233,6 +249,8 @@ getISOCountryCodeForNetwork\(slotId: number\): Promise Obtains the ISO country code of the network with which the SIM card in the specified slot is registered. This function uses a promise to return the result. +**System capability**: SystemCapability.Telephony.CoreService + **Parameters** | Name| Type| Mandatory| Description| @@ -264,6 +282,8 @@ getSignalInformation\(slotId: number, callback: AsyncCallback\> Obtains a list of signal strengths of the network with which the SIM card in the specified slot is registered. This function uses a promise to return the result. +**System capability**: SystemCapability.Telephony.CoreService + **Parameters** | Name| Type| Mandatory| Description| @@ -316,9 +338,11 @@ promise.then(data => { isRadioOn\(callback: AsyncCallback\): void -Checks whether the radio service is enabled. This function uses an asynchronous callback to return the result. +Checks whether the radio service is enabled on the primary SIM card. This function uses an asynchronous callback to return the result. + +**Required permission**: ohos.permission.GET_NETWORK_INFO -Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. +**System capability**: SystemCapability.Telephony.CoreService **Parameters** @@ -335,13 +359,48 @@ radio.isRadioOn((err, data) => { ``` -## radio.isRadioOn7+ +## radio.isRadioOn7+ + +isRadioOn\(slotId: number, callback: AsyncCallback\): void + +Checks whether the radio service is enabled on the SIM card in the specified slot. This function uses an asynchronous callback to return the result. + +**Required permission**: ohos.permission.GET_NETWORK_INFO + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | ------------------------ | ---- | ------------------------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\ | Yes| Callback used to return the result.
- **true**: The radio service is enabled.
- **false**: The radio service is disabled.| + +**Example** + +``` +let slotId = 0; +radio.isRadioOn(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.isRadioOn7+ -isRadioOn\(\): Promise +isRadioOn\(slotId?: number\): Promise Checks whether the radio service is enabled. This function uses a promise to return the result. -Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO** permission. +**Required permission**: ohos.permission.GET_NETWORK_INFO + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | No| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2
If the slot ID is not specified, this function is defaulted to check whether the radio service is enabled on the primary SIM card.| **Return value** @@ -352,7 +411,8 @@ Before using this API, you must declare the **ohos.permission.GET\_NETWORK\_INFO **Example** ``` -let promise = radio.isRadioOn(); +let slotId = 0; +let promise = radio.isRadioOn(slotId); promise.then(data => { console.log(`isRadioOn success, promise: data->${JSON.stringify(data)}`); }).catch(err => { @@ -361,25 +421,83 @@ promise.then(data => { ``` +## radio.getOperatorName7+ + +getOperatorName\(slotId: number, callback: AsyncCallback\): void + +Obtains the carrier name. This function uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | ----------------------- | ---- | ------------------------------------------ | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| +| callback | AsyncCallback\ | Yes| Callback used to return the result, which is the carrier name, for example, China Mobile.| + +**Example** + +``` +let slotId = 0; +radio.getOperatorName(slotId, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## radio.getOperatorName7+ + +getOperatorName\(slotId: number\): Promise + +Obtains the carrier name. This function uses a promise to return the result. + +**System capability**: SystemCapability.Telephony.CoreService + +**Parameters** + +| Name| Type| Mandatory| Description| +| ------ | ------ | ---- | -------------------------------------- | +| slotId | number | Yes| Card slot ID. The options are as follows:
- **0**: slot 1
- **1**: slot 2| + +**Return value** + +| Type| Description| +| ----------------- | ------------------------------------------------------------ | +| Promise\ | Promise used t return the result, which is the carrier name, for example, China Mobile.| + +**Example** + +``` +let slotId = 0; +let promise = radio.getOperatorName(slotId); +promise.then(data => { + console.log(`getOperatorName success, promise: data->${JSON.stringify(data)}`); +}).catch(err => { + console.log(`getOperatorName fail, promise: err->${JSON.stringify(err)}`); +}); +``` + + ## RadioTechnology Enumerates the RATs. | Variable| Value| Description| | ------------------------- | ---- | ------------------------------------------------------------ | -| RADIO_TECHNOLOGY_UNKNOWN | 0 | Unknown| -| RADIO_TECHNOLOGY_GSM | 1 | Global System for Mobile Communication (GSM)| -| RADIO_TECHNOLOGY_1XRTT | 2 | Single-Carrier Radio Transmission Technology (1XRTT)| -| RADIO_TECHNOLOGY_WCDMA | 3 | Wideband Code Division Multiple Access (WCDMA)| -| RADIO_TECHNOLOGY_HSPA | 4 | High Speed Packet Access (HSPA)| -| RADIO_TECHNOLOGY_HSPAP | 5 | Evolved High Speed Packet Access (HSPA+)| -| RADIO_TECHNOLOGY_TD_SCDMA | 6 | Time Division Synchronous Code Division Multiple Access (TD-SCDMA)| -| RADIO_TECHNOLOGY_EVDO | 7 | Evolution-Data Optimized (EVDO)| -| RADIO_TECHNOLOGY_EHRPD | 8 | Evolved High Rate Package Data (EHRPD)| -| RADIO_TECHNOLOGY_LTE | 9 | Long Term Evolution (LTE)| -| RADIO_TECHNOLOGY_LTE_CA | 10 | Long Term Evolution_Carrier Aggregation (LTE_CA)| -| RADIO_TECHNOLOGY_IWLAN | 11 | Industrial Wireless LAN (IWLAN)| -| RADIO_TECHNOLOGY_NR | 12 | New Radio (NR)| +| RADIO_TECHNOLOGY_UNKNOWN | 0 | Unknown RAT
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_GSM | 1 | Global System for Mobile Communication (GSM)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_1XRTT | 2 | Single-Carrier Radio Transmission Technology (1XRTT)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_WCDMA | 3 | Wideband Code Division Multiple Access (WCDMA)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_HSPA | 4 | High Speed Packet Access (HSPA)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_HSPAP | 5 | Evolved High Speed Packet Access (HSPA+)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_TD_SCDMA | 6 | Time Division Synchronous Code Division Multiple Access (TD-SCDMA)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_EVDO | 7 | Evolution-Data Optimized (EVDO)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_EHRPD | 8 | Evolved High Rate Package Data (EHRPD)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_LTE | 9 | Long Term Evolution (LTE)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_LTE_CA | 10 | Long Term Evolution_Carrier Aggregation (LTE_CA)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_IWLAN | 11 | Industrial Wireless LAN (IWLAN)
**System capability**: SystemCapability.Telephony.CoreService| +| RADIO_TECHNOLOGY_NR | 12 | New Radio (NR)
**System capability**: SystemCapability.Telephony.CoreService| ## SignalInformation @@ -387,39 +505,40 @@ Enumerates the RATs. Defines the signal strength. | Attribute| Type| Description| -| ----------- | --------------------------- | ------------------ | -| signalType | [NetworkType](#NetworkType) | Signal strength type.| -| signalLevel | number | Signal strength level.| +| ----------- | --------------------------- | ------------------------------------------------------------ | +| signalType | [NetworkType](#NetworkType) | Signal strength type.
**System capability**: SystemCapability.Telephony.CoreService| +| signalLevel | number | Signal strength level.
**System capability**: SystemCapability.Telephony.CoreService| ## NetworkType -Network type. +Defines the network type. | Variable| Value| Description| | -------------------- | ---- | ------------------------------------------------------------ | -| NETWORK_TYPE_UNKNOWN | 0 | Unknown| -| NETWORK_TYPE_GSM | 1 | GSM network| -| NETWORK_TYPE_CDMA | 2 | CDMA network| -| NETWORK_TYPE_WCDMA | 3 | WCDMA network| -| NETWORK_TYPE_TDSCDMA | 4 | TD-SCDMA network| -| NETWORK_TYPE_LTE | 5 | LTE network| -| NETWORK_TYPE_NR | 6 | 5G NR network| +| NETWORK_TYPE_UNKNOWN | 0 | Unknown network
**System capability**: SystemCapability.Telephony.CoreService| +| NETWORK_TYPE_GSM | 1 | GSM network
**System capability**: SystemCapability.Telephony.CoreService| +| NETWORK_TYPE_CDMA | 2 | CDMA network
**System capability**: SystemCapability.Telephony.CoreService| +| NETWORK_TYPE_WCDMA | 3 | WCDMA network
**System capability**: SystemCapability.Telephony.CoreService| +| NETWORK_TYPE_TDSCDMA | 4 | TD-SCDMA network
**System capability**: SystemCapability.Telephony.CoreService| +| NETWORK_TYPE_LTE | 5 | LTE network
**System capability**: SystemCapability.Telephony.CoreService| +| NETWORK_TYPE_NR | 6 | 5G NR network
**System capability**: SystemCapability.Telephony.CoreService| ## NetworkState Defines the network registration status. | Variable| Type| Description| -| ----------------- | --------------------- | ------------------------------ | -| longOperatorName | string | Long carrier name of the registered network.| -| shortOperatorName | string | Short carrier name of the registered network.| -| plmnNumeric | string | PLMN code of the registered network.| -| isRoaming | boolean | Whether the user is roaming.| -| regState | [RegState](#RegState) | Network registration status of the device.| -| nsaState | [NsaState](#NsaState) | NSA network registration status of the device.| -| isCaActive | boolean | Whether carrier aggregation (CA) is supported.| -| isEmergency | boolean | Whether only emergency calls are allowed.| +| ----------------- | --------------------- | ------------------------------------------------------------ | +| longOperatorName | string | Long carrier name of the registered network.
**System capability**: SystemCapability.Telephony.CoreService| +| shortOperatorName | string | Short carrier name of the registered network.
**System capability**: SystemCapability.Telephony.CoreService| +| plmnNumeric | string | PLMN code of the registered network.
**System capability**: SystemCapability.Telephony.CoreService| +| isRoaming | boolean | Whether the user is roaming.
**System capability**: SystemCapability.Telephony.CoreService| +| regState | [RegState](#RegState) | Network registration status of the device.
**System capability**: SystemCapability.Telephony.CoreService| +| cfgTech8+ | [RadioTechnology](#RadioTechnology) | RAT of the device.
**System capability**: SystemCapability.Telephony.CoreService| +| nsaState | [NsaState](#NsaState) | NSA network registration status of the device.
**System capability**: SystemCapability.Telephony.CoreService| +| isCaActive | boolean | CA status.
**System capability**: SystemCapability.Telephony.CoreService| +| isEmergency | boolean | Whether only emergency calls are allowed.
**System capability**: SystemCapability.Telephony.CoreService| ## RegState @@ -427,11 +546,11 @@ Defines the network registration status. Defines the network registration status. | Variable| Value| Description| -| ----------------------------- | ---- | -------------------------- | -| REG_STATE_NO_SERVICE | 0 | The device cannot use any service.| -| REG_STATE_IN_SERVICE | 1 | The device can use services normally. | -| REG_STATE_EMERGENCY_CALL_ONLY | 2 | The device can use only the emergency call service.| -| REG_STATE_POWER_OFF | 3 | The cellular radio service is disabled.| +| ----------------------------- | ---- | ------------------------------------------------------------ | +| REG_STATE_NO_SERVICE | 0 | The device cannot use any service.
**System capability**: SystemCapability.Telephony.CoreService| +| REG_STATE_IN_SERVICE | 1 | The device can use services normally.
**System capability**: SystemCapability.Telephony.CoreService| +| REG_STATE_EMERGENCY_CALL_ONLY | 2 | The device can use only the emergency call service.
**System capability**: SystemCapability.Telephony.CoreService| +| REG_STATE_POWER_OFF | 3 | The cellular radio service is disabled.
**System capability**: SystemCapability.Telephony.CoreService| ## NsaState @@ -439,13 +558,13 @@ Defines the network registration status. Enumerates NSA network states. | Variable| Value| Description| -| -------------------------- | ---- | ---------------------------------------------------------- | -| NSA_STATE_NOT_SUPPORT | 1 | The device is in idle or connected state in an LTE cell that does not support NSA.| -| NSA_STATE_NO_DETECT | 2 | The device is in the idle state in an LTE cell that supports NSA but does not support NR coverage detection.| -| NSA_STATE_CONNECTED_DETECT | 3 | The device is connected to the LTE network in an LTE cell that supports NSA and NR coverage detection.| -| NSA_STATE_IDLE_DETECT | 4 | The device is in the idle state in an LTE cell that supports NSA and NR coverage detection.| -| NSA_STATE_DUAL_CONNECTED | 5 | The device is connected to the LTE/NR network in an LTE cell that supports NSA.| -| NSA_STATE_SA_ATTACHED | 6 | The device is idle or connected to the NG-RAN cell when being attached to the 5G Core.| +| -------------------------- | ---- | ------------------------------------------------------------ | +| NSA_STATE_NOT_SUPPORT | 1 | The device is in idle or connected state in an LTE cell that does not support NSA.
**System capability**: SystemCapability.Telephony.CoreService| +| NSA_STATE_NO_DETECT | 2 | The device is in the idle state in an LTE cell that supports NSA but does not support NR coverage detection.
**System capability**: SystemCapability.Telephony.CoreService| +| NSA_STATE_CONNECTED_DETECT | 3 | The device is connected to the LTE network in an LTE cell that supports NSA and NR coverage detection.
**System capability**: SystemCapability.Telephony.CoreService| +| NSA_STATE_IDLE_DETECT | 4 | The device is in the idle state in an LTE cell that supports NSA and NR coverage detection.
**System capability**: SystemCapability.Telephony.CoreService| +| NSA_STATE_DUAL_CONNECTED | 5 | The device is connected to the LTE/NR network in an LTE cell that supports NSA.
**System capability**: SystemCapability.Telephony.CoreService| +| NSA_STATE_SA_ATTACHED | 6 | The device is idle or connected to the NG-RAN cell when being attached to the 5G Core.
**System capability**: SystemCapability.Telephony.CoreService| ## NetworkSelectionMode @@ -453,7 +572,7 @@ Enumerates NSA network states. Enumerates network selection modes. | Variable| Value| Description| -| --------------------------- | ---- | -------------- | -| NETWORK_SELECTION_UNKNOWN | 0 | Unknown network selection mode.| -| NETWORK_SELECTION_AUTOMATIC | 1 | Automatic network selection mode.| -| NETWORK_SELECTION_MANUAL | 2 | Manual network selection mode.| +| --------------------------- | ---- | ------------------------------------------------------------ | +| NETWORK_SELECTION_UNKNOWN | 0 | Unknown network selection mode.
**System capability**: SystemCapability.Telephony.CoreService| +| NETWORK_SELECTION_AUTOMATIC | 1 | Automatic network selection mode.
**System capability**: SystemCapability.Telephony.CoreService| +| NETWORK_SELECTION_MANUAL | 2 | Manual network selection mode.
**System capability**: SystemCapability.Telephony.CoreService| -- GitLab