diff --git a/en/application-dev/device/Readme-EN.md b/en/application-dev/device/Readme-EN.md index 6e7fd27fd4506a487faeac457371c7c015a6b771..abf5154a8caa1473367960eea7b9118598ce706a 100644 --- a/en/application-dev/device/Readme-EN.md +++ b/en/application-dev/device/Readme-EN.md @@ -1,19 +1,19 @@ # Device -- USB Service - - [USB Service Overview](usb-overview.md) - - [USB Service Development](usb-guidelines.md) - Location - [Location Service Development](location-guidelines.md) -- Sensor - - [Sensor Overview](sensor-overview.md) - - [Sensor Development](sensor-guidelines.md) -- Vibrator - - [Vibrator Overview](vibrator-overview.md) - - [Vibrator Development](vibrator-guidelines.md) - Multimodal Input - [Input Device Development](inputdevice-guidelines.md) - [Mouse Pointer Development](pointerstyle-guidelines.md) +- Sensor + - [Sensor Overview](sensor-overview.md) + - [Sensor Development](sensor-guidelines.md) - Update Service - [Sample Server Overview](sample-server-overview.md) - [Sample Server Development](sample-server-guidelines.md) +- USB Service + - [USB Service Overview](usb-overview.md) + - [USB Service Development](usb-guidelines.md) +- Vibrator + - [Vibrator Overview](vibrator-overview.md) + - [Vibrator Development](vibrator-guidelines.md) \ No newline at end of file diff --git a/en/application-dev/telephony/Readme-EN.md b/en/application-dev/telephony/Readme-EN.md index a5a60273c71f7002efa6f8cb862848c3f169de9d..20a349fabbbb47329f6f49b335315d273b3c9420 100644 --- a/en/application-dev/telephony/Readme-EN.md +++ b/en/application-dev/telephony/Readme-EN.md @@ -1,5 +1,5 @@ # Telephony - [Telephony Service Overview](telephony-overview.md) -- [Redirecting to the Dial Screen](jumping-to-the-dial-screen.md) -- [Obtaining Current Cellular Network Signal Information](cellular-network-signal-info.md) +- [Call Service Development](telephony-call.md) +- [SMS Service Development](telephony-sms.md) diff --git a/en/application-dev/telephony/cellular-network-signal-info.md b/en/application-dev/telephony/cellular-network-signal-info.md deleted file mode 100644 index 41cb90c05493cb4ce12313a9bd194cb14835f4a9..0000000000000000000000000000000000000000 --- a/en/application-dev/telephony/cellular-network-signal-info.md +++ /dev/null @@ -1,51 +0,0 @@ -# Obtaining Current Cellular Network Signal Information - - -## Use Cases - -Applications always need to obtain signal information of the registered cellular network to obtain the network quality. You can use this service to obtain the network signal information for the specified SIM card. - - -## Available APIs - -The radio module provides you with APIs to obtain network signal information. The observer module provides APIs to register or unregister the observer for cellular network status changes. The following table describes the related APIs. - -| Category| API| Description| Required Permission| -| -------- | -------- | -------- | -------- | -| Obtaining a **SignalInformation** object| radio.getSignalInformation​​() | Obtains the signal strength of the currently registered cellular network.| N/A| -| Registering the observer for signal information changes| observer.on('signalInfoChange') | Registers the observer for signal information changes.| N/A| -| Unregistering the observer for signal information changes| observer.off('signalInfoChange') | Unregisters the observer for signal information changes.| N/A| - - -## How to Develop - -1. Import required modules. - -2. Call the **getSignalInformation()** API to obtain the **SignalInformation** list. - -3. Traverse the **SignalInformation** list to obtain the signal strength for each radio access technology (RAT) indicated by **signalType**. - -4. (Optional) Register the observer for signal information changes. - - ```js - import radio from '@ohos.telephony.radio' - import observer from '@ohos.telephony.observer'; - - // Obtain the signal strength of the specified SIM card, for example, card 1. - let slotId = 0; - radio.getSignalInformation(slotId, (err, data) => { - if (!err) { - console.log("get signal information success."); - // Traverse the signal information list to obtain the signal strength for each RAT. - for (let j = 0; j < data.length; j++) { - console.log("type:" + data[j].signalType + ", level:" + data[j].signalLevel); - } - } else { - console.log("get signal information fail, err is:" + JSON.stringify(err)); - } - }); - // (Optional) Register the observer for signal information changes. - observer.on("signalInfoChange", (data) => { - console.log("signal info change, data is:" + JSON.stringify(data)); - }); - ``` diff --git a/en/application-dev/telephony/jumping-to-the-dial-screen.md b/en/application-dev/telephony/jumping-to-the-dial-screen.md deleted file mode 100644 index b314f4c138d93dbb8870f1d2098b5f5e9f10b6bc..0000000000000000000000000000000000000000 --- a/en/application-dev/telephony/jumping-to-the-dial-screen.md +++ /dev/null @@ -1,51 +0,0 @@ -# Redirecting to the Dial Screen - -You can use this service for your application to redirect users to the dial screen and display the dialed number. When the **makeCall** API is called, the device will automatically display the dial screen. On this screen, the user can choose to make an audio or video call and specify the SIM card. - - -## Available APIs - -The call module provides APIs for call management. The observer module provides APIs to register or unregister an observer for call service status changes. The following table describes the related APIs. - -| Category| API| Description| Required Permission| -| -------- | -------- | -------- | -------- | -| Checking call capabilities| call.hasVoiceCapability() | Checks whether the voice call function is supported.| N/A| -| Redirecting to the dial screen| call.makeCall() | Enables redirection to the dial screen and display of the dialed number.| N/A| -| Registering the observer for call service status changes| observer.on('callStateChange') | Registers the observer for call service status changes.| ohos.permission.READ_CALL_LOG (required for obtaining phone numbers)| -| Unregistering the observer for call service status changes| observer.off('callStateChange') | Unregisters the observer for call service status changes.| N/A| - - -## How to Develop - -1. Import required modules. - -2. Invoke the **hasVoiceCapability()** API to check whether the call function is supported. If supported, go to step 3; otherwise, calls will be rejected. - -3. Enable redirection to the dial screen and display of the dialed number. - -4. (Optional) Register the observer for call service status changes. - - ```js - // Import the required modules. - import call from '@ohos.telephony.call'; - import observer from '@ohos.telephony.observer'; - - // Check whether the voice call function is supported. - let isSupport = call.hasVoiceCapability(); - if (!isSupport) { - console.log("not support voice capability, return."); - return; - } - // If the voice call function is supported, the user will be redirected to the dial screen and the dialed number is displayed. - call.makeCall("13xxxx", (err)=> { - if (!err) { - console.log("make call success."); - } else { - console.log("make call fail, err is:" + JSON.stringify(err)); - } - }); - // (Optional) Register the observer for call service status changes. - observer.on("callStateChange", (data) => { - console.log("call state change, data is:" + JSON.stringify(data)); - }); - ``` diff --git a/en/application-dev/telephony/telephony-call.md b/en/application-dev/telephony/telephony-call.md new file mode 100644 index 0000000000000000000000000000000000000000..bbef181efb128f47ee08fd84d5adb0fd1aa031b2 --- /dev/null +++ b/en/application-dev/telephony/telephony-call.md @@ -0,0 +1,116 @@ +# Call Service Development + +## Scenario Description + +You can implement the call service in either of the following ways: +- For a system application, use the **dial** API to make a voice or video call. The call will be displayed on the application page. +- For a third-party application, use the **makecall** API to start the system call application. Users can then make calls as needed. + +## Basic Concepts + +- Call status code + A code used to report the current call status to the application, so that the application can then take appropriate logic processing. For example, if there is no ongoing call, the application allows you to make a new call. + + | Name | Value | Description | + | ------------------ | ---- | ------------------------------------------------------------ | + | CALL_STATE_UNKNOWN | -1 | The call status fails to be obtained and is unknown. | + | CALL_STATE_IDLE | 0 | No call is in progress. | + | CALL_STATE_RINGING | 1 | The call is in the ringing or waiting state. | + | CALL_STATE_OFFHOOK | 2 | At least one call is in dialing, active, or on hold, and no new incoming call is ringing or waiting.| + +## Constraints + +1. The call service is available only on standard-system devices. +2. An available SIM card must be present on the device. + + +## Available APIs + +> **NOTE** +> To maximize the application running efficiency, most API calls are called asynchronously in callback or promise mode. The following code examples use the callback mode. For details about the APIs, see [call API Reference](../reference/apis/js-apis-call.md). + +| Name | Description | +| ----------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| hasVoiceCapability(): boolean; | Checks whether the voice function is available. | +| dial(phoneNumber: string, callback: AsyncCallback): void | Makes a call. This is a system API. | +| makeCall(phoneNumber: string, callback: AsyncCallback): void | Redirects to the dial screen and displays the called number. | + +The **observer** module provides the functions of subscribing to and unsubscribing from the call service status. For details about the APIs, see [observer API Reference](../reference/apis/js-apis-observer.md). + +| Name | Description | +| ------------------------------------------------------------ | ------------------ | +| on(type: 'callStateChange', options: { slotId: number }, callback: Callback<{ state: CallState, number: string }>): void | Listens to call status changes.| + +## How to Develop + +### Making a Call by Using the **dial** API (Only for System Applications) + +1. Declare the required permission: **ohos.permission.PLACE_CALL**. +This permission is of the **system\_basic** level. Before applying for the permission, ensure that the [basic principles for permission management](../security/accesstoken-overview.md#basic-principles-for-permission-management) are met. Then, declare the corresponding permission by following instructions in [Declaring Permissions in the Configuration File](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file). +2. Import the **call** and **observer** modules. +3. Invoke the **hasVoiceCapability** API to check whether the device supports the voice call function. + If the voice call function is supported, the user will be redirected to the dial screen and the dialed number is displayed. +4. Invoke the **dial** API to make a call. +5. (Optional) Register the observer for call status changes. + ```js + // Import the required modules. + import call from '@ohos.telephony.call' + import observer from '@ohos.telephony.observer' + + // Check whether the voice call function is supported. + let isSupport = call.hasVoiceCapability(); + if (!isSupport) { + console.log("not support voice capability, return."); + return; + } + // If the device supports the voice call function, call the following API to make a call. + call.dial("13xxxx", (err, data) => { + this.output = this.output + `dial: ${JSON.stringify(data)}\n` + console.log(`callback: dial err->${JSON.stringify(err)} data->${JSON.stringify(data)}`) + }) + + // (Optional) Register the observer for call service status changes. + observer.on("callStateChange", {slotId: 0}, (data) => { + console.log("call state change, data is:" + JSON.stringify(data)); + }); + ``` + +### Making a Call by Using the makecall API + +1. Import the **call** and **observer** modules. +2. Invoke the **hasVoiceCapability** API to check whether the device supports the voice call function. + If the voice call function is supported, the user will be redirected to the dial screen and the dialed number is displayed. +3. Invoke the **makecall** API to start the system call application and make a call. +4. (Optional) Register the observer for call status changes. + + ```js + // Import the required modules. + import call from '@ohos.telephony.call' + import observer from '@ohos.telephony.observer' + + // Check whether the voice call function is supported. + let isSupport = call.hasVoiceCapability(); + if (!isSupport) { + console.log("not support voice capability, return."); + return; + } + // If the voice call function is supported, the user will be redirected to the dial screen and the dialed number is displayed. + call.makeCall("13xxxx", (err)=> { + if (!err) { + console.log("make call success."); + } else { + console.log("make call fail, err is:" + JSON.stringify(err)); + } + }); + + // (Optional) Register the observer for call service status changes. + observer.on("callStateChange", {slotId: 0}, (data) => { + console.log("call state change, data is:" + JSON.stringify(data)); + }); + ``` + +## Samples + +The following sample is provided to help you better understand how to develop the call service: + +- [Call](https://gitee.com/openharmony/applications_app_samples/tree/master/Telephony/Call) diff --git a/en/application-dev/telephony/telephony-overview.md b/en/application-dev/telephony/telephony-overview.md index 8fc3587c8c93428f1a243025a3e1743aca40bdb0..1ea731c56ba89fefb258174ca409e169dd4a5894 100644 --- a/en/application-dev/telephony/telephony-overview.md +++ b/en/application-dev/telephony/telephony-overview.md @@ -1,12 +1,17 @@ # Telephony Service Overview -The Telephony subsystem provides a series of APIs for [making calls](../reference/apis/js-apis-call.md), [obtaining current cellular network signal information](../reference/apis/js-apis-telephony-data.md) and [managing SIM cards](../reference/apis/js-apis-sim.md). +The telephony subsystem consists of the following modules that provide APIs to help you develop communication applications: -Your application can call related APIs to obtain the name of the currently registered network, network service status, signal strength, and SIM card information. For details, see [Obtaining Current Cellular Network Signal Information](cellular-network-signal-info.md). +- Call module: Allows an application to directly make a call and display the call on the application screen. A third-party application can start the system call application and redirect to the dialing screen to make a call. For details, see [Telephony Call Development](telephony-call.md). With the call module, the application can also format phone numbers and determine whether a number is an emergency number. For details, see [call API Reference](../reference/apis/js-apis-call.md). -To make calls, your application needs to declare the **ohos.permission.PLACE_CALL** permission. It is recommended that the application use **makeCall()** to redirect users to the dial screen and display the dialed number. For details, see [Redirecting to the Dial Screen](jumping-to-the-dial-screen.md). +- SMS module: Allows an application to create and send SMS messages. For details, see [Telephony SMS Development](telephony-sms.md). In addition, the the application can obtain and set the SMS service center address, and check whether the current device can send and receive SMS messages. For details, see the [sms API Reference](../reference/apis/js-apis-sms.md). +- Radio module: Allows an application to obtain the name of the currently registered network, network service status, and signal strength. For details, see [radio API Reference](../reference/apis/js-apis-radio.md). + +- Data module: Allows an application to access cellular data services. Cellular data is a wireless network communication standard that uses the packet switch technology throughout data transmission and switch to provide voice, data, and video services for mobile devices. It enables users to use applications on mobile devices or browse web pages on the mobile network. For details, see [data API Reference](../reference/apis/js-apis-telephony-data.md). + +- SIM module: Allows an application to obtain SIM card information, such as the service provider, International Organization for Standardization (ISO) country code, and home Public Land Mobile Network (PLMN) number. For details, see [sim API Reference](../reference/apis/js-apis-sim.md). ## Constraints -The accommodating device must be equipped with a modem and a SIM card capable of independent cellular communication. +Before calling telephony service APIs, ensure that the device is equipped with a modem and SIM card capable of independent cellular communication. diff --git a/en/application-dev/telephony/telephony-sms.md b/en/application-dev/telephony/telephony-sms.md new file mode 100644 index 0000000000000000000000000000000000000000..a8cf16532ae4537e2628821d2af933f7d0a0a176 --- /dev/null +++ b/en/application-dev/telephony/telephony-sms.md @@ -0,0 +1,118 @@ +# SMS Service Development + +## Scenario Description + +The Short Messaging Service (SMS) module provides basic SMS management functions. You can create and send SMS messages, and obtain the ID of the default SIM card used to send and receive SMS messages. Besides, you can obtain and set the SMSC address, and check whether the current device can send and receive SMS messages. + +## Basic Concepts + +- SMS + + A service capable of SMS message storage and forwarding. It enables mobile phones to send and receive SMS messages. The content of the SMS message can be text, digits, or binary non-text data. The information about the sender is stored in the Short Message Service Center (SMSC) and forwarded to the recipient. + +- SMSC + + An entity that relays, stores, or forwards SMS messages between base stations and mobile devices. It uses the GMS 03.40 protocol for sending SMS messages to or receiving SMS messages from mobile phones. + +- PDU + + Protocol data unit, which uses the following encoding schemes to send and receive SMS messages: 7-bit, 8-bit, and UCS-2. 7-bit encoding is used to send common ASCII characters, 8-bit encoding to send data messages, and UCS-2 encoding to send Unicode characters. + +## Constraints + +1. The SMS service is available only on standard-system devices. +2. An available SIM card must be present on the device, and the permission to send SMS messages must be granted. + + +## Available APIs + +> **NOTE** +> To maximize the application running efficiency, most API calls are called asynchronously in callback or promise mode. The following code examples use the callback mode. For details about the APIs, see [sms API Reference](../reference/apis/js-apis-sms.md). + +| Name | Description | +| ------------------------------------------------------------ | ------------------------------------------------------- | +| createMessage(pdu: Array, specification: string, callback: AsyncCallback): void | Creates an SMS message instance based on the PDU and the specified SMS protocol.| +| sendMessage(options: SendMessageOptions): void | Sends text or data SMS messages. | +| getDefaultSmsSlotId(callback: AsyncCallback): void | Obtains the ID of the default SIM card used to send SMS messages. | +| setSmscAddr(slotId: number, smscAddr: string, callback: AsyncCallback): void | Sets the SMSC address based on the specified slot ID. | +| getSmscAddr(slotId: number, callback: AsyncCallback): void | Obtains the SMSC address based on the specified slot ID. | + + +## How to Develop + +1. Declare the required permission: + - To send SMS messages, call the **sendMessage** API and declare the **ohos.permission.SEND\_MESSAGES** permission. The permission is of the **system\_basic** level. + - To set the SMSC address, call the** setSmscAddr** API and declare the **ohos.permission.SET\_TELEPHONY\_STATE** permission. The permission is of the **system\_basic** level. + - To obtain the SMSC address, call the** getSmscAddr** API and declare the **ohos.permission.GET\_TELEPHONY\_STATE** permission. The permission is of the **system\_basic** level. + Before applying for the permission, ensure that the [basic principles for permission management](../security/accesstoken-overview.md#basic-principles-for-permission-management) are met. Then, declare the corresponding permission by following instructions in [Declaring Permissions in the Configuration File](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file). + +2. Import the required modules. + +3. Create an SMS message instance based on the PDU and the specified SMS protocol. + +4. Send an SMS message. + + ```js + // Import the required modules. + import sms from '@ohos.telephony.sms' + + export default class SmsModel { + async createMessage() { + const specification = '3gpp' + const pdu = [0x08, 0x91] // Display PDUs in array format. The type is number. + const shortMessage = await sms.createMessage(pdu, specification) + Logger.info(`${TAG}, createMessageCallback: shortMessage = ${JSON.stringify(shortMessage)}`) + return shortMessage + } + + sendMessage(slotId, content, destinationHost, serviceCenter, destinationPort, handleSend, handleDelivery) { + Logger.info(`${TAG}, sendMessage start ${slotId} ${content} ${destinationHost} ${serviceCenter} ${destinationPort}`) + const options = + { + slotId: slotId, + content: content, + destinationHost: destinationHost, + serviceCenter: serviceCenter, + destinationPort: destinationPort, + sendCallback(err, data) { + Logger.info(`${TAG}, sendCallback: data = ${JSON.stringify(data)} err = ${JSON.stringify(err)}`) + handleSend(err, data) + }, + deliveryCallback(err, data) { + Logger.info(`${TAG}, deliveryCallback: data = ${JSON.stringify(data)} err = ${JSON.stringify(err)}`) + handleDelivery(err, data) + } + } + // Send an SMS message. + sms.sendMessage(options) + Logger.info(`${TAG}, sendMessage end`) + } + + // Obtain the ID of the default SIM card used to send SMS messages. + async getDefaultSmsSlotId() { + const defaultSmsSlotId = await sms.getDefaultSmsSlotId() + Logger.info(`${TAG}, getDefaultSmsSlotId: defaultSmsSlotId = ${defaultSmsSlotId}`) + return defaultSmsSlotId + } + + // Set the SMSC address based on the specified slot ID. + async setSmscAddr(slotId, smscAddr) { + const serviceCenter = await sms.setSmscAddr(slotId, smscAddr) + Logger.info(`${TAG}, setSmscAddr: serviceCenter = ${JSON.stringify(serviceCenter)}`) + return serviceCenter + } + + // Obtain the SMSC address based on the specified slot ID. + async getSmscAddr(slotId) { + const serviceCenter = await sms.getSmscAddr(slotId) + Logger.info(`${TAG}, getSmscAddr: serviceCenter = ${JSON.stringify(serviceCenter)}`) + return serviceCenter + } + } + ``` + + +## Samples + +The following sample is provided to help you better understand how to develop the SMS service: +- [SMS](https://gitee.com/openharmony/applications_app_samples/tree/master/Telephony/Message)