!14369 telephony开发指南更新

Merge pull request !14369 from 刘建东/master

!14369 telephony开发指南更新
Merge pull request !14369 from 刘建东/master
16c654fb · openharmony_ci · Gitee · 823a3c06 · 75326af0 · 16c654fb
6 changed file
--- a/zh-cn/application-dev/telephony/Readme-CN.md
+++ b/zh-cn/application-dev/telephony/Readme-CN.md
 # 电话服务

 - [电话服务开发概述](telephony-overview.md)
- [跳转拨号界面](jumping-to-the-dial-screen.md)
- [获取当前蜂窝网络信号信息](cellular-network-signal-info.md)
+- [拨打电话](telephony-call.md)
+- [短信服务](telephony-sms.md)
--- a/zh-cn/application-dev/telephony/cellular-network-signal-info.md
+++ b/zh-cn/application-dev/telephony/cellular-network-signal-info.md
-# 获取当前蜂窝网络信号信息
-
-
-## 场景介绍
-
-应用通常需要获取用户所在蜂窝网络下信号信息，以便获取当前驻网质量。开发者可以通过本业务，获取到用户指定SIM卡当前所在网络下的信号信息。
-
-
-## 接口说明
-
-radio模块提供了获取当前网络信号信息的方法。observer模块为开发者提供蜂窝网络状态订阅和取消订阅功能。具体接口说明如下表。
-
-| 功能分类 | 接口名 | 描述 | 所需权限 |
-| -------- | -------- | -------- | -------- |
-| 信号强度信息 | radio.getSignalInformation() | 获取当前注册蜂窝网络信号强度信息 | 无 |
-| 订阅蜂窝网络信号变化 | observer.on('signalInfoChange') | 订阅蜂窝网络信号变化 | 无 |
-| 取消订阅蜂窝网络信号变化 | observer.off('signalInfoChange') | 取消订阅蜂窝网络信号变化 | 无 |
-
-
-## 开发步骤
-
-1. import需要的模块。
-
-2. 调用getSignalInformation()方法，返回所有SignalInformation列表。
-
-3. 遍历SignalInformation数组，并分别根据不同的signalType得到不同制式的信号强度。
-
-4. 订阅蜂窝网络信号变化（可选）。
-   
-   ```js
-   import radio from '@ohos.telephony.radio'
-   import observer from '@ohos.telephony.observer';
-   
-   // 以获取卡1的信号强度为例
-   let slotId = 0;
-   radio.getSignalInformation(slotId, (err, data) => {
-       if (!err) {
-           console.log("get signal information success.");
-           // 遍历数组，输出不同网络制式下的信号强度
-           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));
-       }
-   });
-   // 订阅蜂窝网络信号变化（可选）
-   observer.on("signalInfoChange", (data) => {
-       console.log("signal info change, data is:" + JSON.stringify(data));
-   });
-   ```
-
-## 相关实例
-
-针对蜂窝网络数据开发，有以下相关实例可供参考：
- [`MobileNetwork`：蜂窝数据（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Telephony/MobileNetwork)
\ No newline at end of file
--- a/zh-cn/application-dev/telephony/jumping-to-the-dial-screen.md
+++ b/zh-cn/application-dev/telephony/jumping-to-the-dial-screen.md
-# 跳转拨号界面
-
-当应用需要跳转到拨号界面，并显示拨号的号码时，使用本业务。当开发者调用makeCall接口时，设备会自动跳转到拨号界面。和正常拨打电话一样，用户可以选择音频或视频呼叫，卡1或卡2拨出。
-
-
-## 接口说明
-
-call模块为开发者提供呼叫管理功能。observer模块为开发者提供订阅和取消订阅通话业务状态的功能。具体接口说明如下表。
-
-| 功能分类 | 接口名 | 描述 | 所需权限 |
-| -------- | -------- | -------- | -------- |
-| 能力获取 | call.hasVoiceCapability() | 是否具有语音功能 | 无 |
-| 跳转拨号界面 | call.makeCall() | 跳转到拨号界面，并显示拨号的号码 | 无 |
-| 订阅通话业务状态变化 | observer.on('callStateChange') | 订阅通话业务状态变化 | ohos.permission.READ_CALL_LOG&nbsp;（获取通话号码需要该权限） |
-| 取消订阅通话业务状态变化 | observer.off('callStateChange') | 取消订阅通话业务状态变化 | 无 |
-
-
-## 开发步骤
-
-1. import需要的模块。
-
-2. 调用hasVoiceCapability()接口获取当前设备呼叫能力，如果支持继续下一步；如果不支持则无法发起呼叫。
-
-3. 跳转到拨号界面，并显示拨号的号码。
-
-4. （可选）订阅通话业务状态变化。
-   
-   ```js
-   // import需要的模块
-   import call from '@ohos.telephony.call';
-   import observer from '@ohos.telephony.observer';
-   
-   // 调用查询能力接口
-   let isSupport = call.hasVoiceCapability();
-   if (!isSupport) {
-       console.log("not support voice capability, return.");
-       return;
-   }
-   // 如果设备支持呼叫能力，则继续跳转到拨号界面，并显示拨号的号码
-   call.makeCall("13xxxx", (err)=> {
-       if (!err) {
-           console.log("make call success.");
-       } else {
-           console.log("make call fail, err is:" + JSON.stringify(err));
-       }
-   });
-   // 订阅通话业务状态变化（可选）
-   observer.on("callStateChange", (data) => {
-       console.log("call state change, data is:" + JSON.stringify(data));
-   });
-   ```
--- a/zh-cn/application-dev/telephony/telephony-call.md
+++ b/zh-cn/application-dev/telephony/telephony-call.md
+# 拨打电话
+
+## 场景介绍
+
+开发者可以通过两种不同的方式实现拨打电话的功能：
+- 对于系统应用，开发者可以使用dial接口，直接进行音频/视频呼叫，在应用界面显示对应的通话。
+- 对于三方应用，开发者可以使用makecall接口，拉起系统电话应用，用户可以自行呼出通话。
+
+## 基本概念
+
+- 通话状态码
+  将当前的通话状态上报给app，可以根据当前的通话状态去做一些逻辑处理。例如在当前没有正在进行呼叫的时候，可以正常拨打新的一通电话。
+
+  | 名称               | 值   | 说明                                                         |
+  | ------------------ | ---- | ------------------------------------------------------------ |
+  | CALL_STATE_UNKNOWN | -1   | 无效状态，当获取呼叫状态失败时返回。                         |
+  | CALL_STATE_IDLE    | 0    | 表示没有正在进行的呼叫。                                     |
+  | CALL_STATE_RINGING | 1    | 表示来电正在振铃或等待。                                     |
+  | CALL_STATE_OFFHOOK | 2    | 表示至少有一个呼叫处于拨号、通话中或呼叫保持状态，并且没有新的来电振铃或等待。 |
+
+## 约束与限制
+
+1. 仅支持在标准系统上运行。
+2. 设备需插入可用的SIM卡。
+
+
+## 接口说明
+
+> **说明：**
+> 为了保证应用的运行效率，大部分API调用都是异步的，对于异步调用的API均提供了callback和Promise两种方式，以下示例均采用callback函数，更多方式可以查阅[API参考](../reference/apis/js-apis-call.md)。
+
+|                                  接口名                                             | 描述                                                         |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| hasVoiceCapability(): boolean;                                                      | 判断是否具有语音功能。                                        |
+| dial(phoneNumber: string, callback: AsyncCallback<boolean>): void                   | 拨号。该接口为系统接口。                                      |
+| makeCall(phoneNumber: string, callback: AsyncCallback<void>): void                  | 转到拨号屏幕，显示被叫号码。                                  |
+
+observer模块为开发者提供订阅和取消订阅通话业务状态的功能。具体API说明详见[接口文档](../reference/apis/js-apis-observer.md)。
+
+| 接口名                                                       | 描述               |
+| ------------------------------------------------------------ | ------------------ |
+| on(type: 'callStateChange', options: { slotId: number }, callback: Callback<{ state: CallState, number: string }>): void | 监听通话状态变化。 |
+
+## 开发步骤
+
+### 使用dial拨打电话（仅供系统应用使用）
+
+1. 声明接口调用所需要的权限：ohos.permission.PLACE_CALL
+ohos.permission.PLACE_CALL权限级别为system_basic，在申请权限前，请保证符合[权限使用的基本原则](../security/accesstoken-overview.md#权限使用的基本原则)。然后参考[配置文件权限声明指导文档](../security/accesstoken-guidelines.md#配置文件权限声明)声明对应权限。
+2. 导入call和observer模块。
+3. 调用hasVoiceCapability，确认当前设备是否支持拨号。
+   如果设备支持呼叫能力，则继续跳转到拨号界面，并显示拨号的号码。
+4. 调用dial接口，拨打电话。
+5.（可选）订阅通话业务状态变化。
+   ```js
+    // import需要的模块
+    import call from '@ohos.telephony.call'
+    import observer from '@ohos.telephony.observer'
+
+    // 调用查询能力接口
+    let isSupport = call.hasVoiceCapability();
+    if (!isSupport) {
+        console.log("not support voice capability, return.");
+        return;
+    }
+    // 如果设备支持呼叫能力，调用以下接口进行拨号
+    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)}`)
+    })
+
+    // 订阅通话业务状态变化（可选）
+    observer.on("callStateChange", {slotId: 0}, (data) => {
+        console.log("call state change, data is:" + JSON.stringify(data));
+    });
+   ```
+
+### 使用makecall拨打电话
+
+1. 导入call和observer模块。
+2. 调用hasVoiceCapability，确认当前设备是否支持拨号。
+   如果设备支持呼叫能力，则继续跳转到拨号界面，并显示拨号的号码。
+3. 调用makecall接口，拉起系统电话应用，拨打电话。
+4.（可选）订阅通话业务状态变化。
+
+   ```js
+    // import需要的模块
+    import call from '@ohos.telephony.call'
+    import observer from '@ohos.telephony.observer' 
+   
+    // 调用查询能力接口
+    let isSupport = call.hasVoiceCapability();
+    if (!isSupport) {
+        console.log("not support voice capability, return.");
+        return;
+    }
+    // 如果设备支持呼叫能力，则继续跳转到拨号界面，并显示拨号的号码
+    call.makeCall("13xxxx", (err)=> {
+        if (!err) {
+            console.log("make call success.");
+        } else {
+            console.log("make call fail, err is:" + JSON.stringify(err));
+        }
+    });
+
+    // 订阅通话业务状态变化（可选）
+    observer.on("callStateChange", {slotId: 0}, (data) => {
+        console.log("call state change, data is:" + JSON.stringify(data));
+    });
+   ```
+
+## 相关实例
+
+拨打电话有以下相关实例可供参考：
+
+- [拨打电话](https://gitee.com/openharmony/applications_app_samples/tree/master/Telephony/Call)
--- a/zh-cn/application-dev/telephony/telephony-overview.md
+++ b/zh-cn/application-dev/telephony/telephony-overview.md
 # 电话服务开发概述

-电话服务系统提供了一系列的API用于[拨打电话](../reference/apis/js-apis-call.md)、获取[无线蜂窝网络](../reference/apis/js-apis-telephony-data.md)和[SIM卡](../reference/apis/js-apis-sim.md)相关信息。
+电话服务系统提供系列API帮助开发者开发通讯类应用，包括：

-应用可以通过调用API来获取当前注册网络名称、网络服务状态、信号强度以及SIM卡的相关信息，具体可参考[获取当前蜂窝网络信号信息](cellular-network-signal-info.md)开发指导。
+- call模块（拨打电话）：系统应用可以直接拨打电话，在应用界面显示通话；三方应用可以拉起系统电话应用，跳转至拨号界面，从而实现拨打电话的功能，具体可参考[拨打电话开发指导](telephony-call.md)。除此之外，应用还可以通过call模块，实现格式化电话号码、判断是否紧急号码等功能，详情请参考[@ohos.telephony.call API参考](../reference/apis/js-apis-call.md)。

-直接拨打电话需要系统权限ohos.permission.PLACE_CALL，建议应用使用makeCall()，跳转到拨号界面，并显示拨号的号码，具体可参考[跳转拨号界面](jumping-to-the-dial-screen.md)开发指导。
+- sms模块（短信服务）：应用可以实现创建、发送短信消息的功能，具体可参考[发送短信开发指导](telephony-sms.md)。除此之外，应用还可以实现获取、设置短信服务中心地址，和检查当前设备是否具备短信发送和接收能力等功能，详情请参考[@ohos.telephony.sms API参考](../reference/apis/js-apis-sms.md)。
+- radio模块（网络搜索）：应用可以调用API获取当前注册网络名称、网络服务状态以及信号强度相关信息，详情请参考[@ohos.telephony.radio API参考](../reference/apis/js-apis-radio.md)。

+- data模块（蜂窝数据）：蜂窝数据是无线通讯技术标准的一种，从数据的传输到交换都采用分组技术（Packet Switch），能够为移动设备提供话音、数据、视频图像等业务，经常用于支持用户在智能设备上使用应用程序，以及在移动网络上浏览网页，详情请参考[@ohos.telephony.data API参考](../reference/apis/js-apis-telephony-data.md)。
+
+- sim模块（SIM卡管理）：应用可以调用API获取SIM卡相关信息，如服务提供商、ISO（International Organization for Standardization，国际标准化组织）国家码、归属PLMN（Public Land Mobile Network，公共陆地移动网络）号等，详情请参考[@ohos.telephony.sim API参考](../reference/apis/js-apis-sim.md)。

-## 约束与限制

-搭载设备需要支持以下硬件：
+## 约束与限制

-可以进行独立蜂窝通信的Modem以及SIM卡。
\ No newline at end of file
+在调用电话服务API前，请确保使用的硬件设备有可以独立蜂窝通信的Modem和SIM卡。
--- a/zh-cn/application-dev/telephony/telephony-sms.md
+++ b/zh-cn/application-dev/telephony/telephony-sms.md
+# 短信服务
+
+## 场景介绍
+
+短信服务模块提供了管理短信的一些基础能力，包括创建、发送短信，获取、设置发送短信的默认SIM卡槽ID，获取、设置短信服务中心地址，以及检查当前设备是否具备短信发送和接收能力等。
+
+## 基本概念
+
+- 短信服务
+
+  即SMS（Short Messaging Service），是一种存储和转发服务。用户的移动电话可以通过它进行相互收发短信，内容以文本、数字或二进制非文本数据为主。发送方的信息通过短信服务中心进行储存并转发给接收方。
+
+- 短信服务中心
+
+  即SMSC（Short Message Service Center），负责在基站和移动设备间中继、储存或转发短消息。移动设备到短信服务中心的协议能传输来自移动设备或朝向移动设备的短消息，协议内容遵从GMS 03.40协议。
+
+- 协议数据单元
+
+  即PDU（Protocol Data Unit），PDU模式收发短信可以使用3种编码：7-bit、8-bit和UCS-2编码。7-bit编码用于发送普通的ASCII字符，8-bit编码通常用于发送数据短信，UCS-2编码用于发送Unicode字符。
+
+## 约束与限制
+
+1. 仅支持在标准系统上运行。
+2. 需授予发送短信权限且插入SIM卡才可成功发送短信。
+
+
+## 接口说明
+
+> **说明：**
+> 为了保证应用的运行效率，大部分API调用都是异步的，对于异步调用的API均提供了callback和Promise两种方式，以下示例均采用callback函数，更多方式可以查阅[API参考](../reference/apis/js-apis-sms.md)。
+
+| 接口名                                                       | 描述                                                    |
+| ------------------------------------------------------------ | ------------------------------------------------------- |
+| createMessage(pdu: Array<number>, specification: string, callback: AsyncCallback<ShortMessage>): void | 基于协议数据单元（PDU）和指定的SMS协议创建SMS消息实例。 |
+| sendMessage(options: SendMessageOptions): void               | 发送文本或数据SMS消息。                                                      |
+| getDefaultSmsSlotId(callback: AsyncCallback<number>): void   | 获取用于发送短信的默认SIM卡。                                                |
+| setSmscAddr(slotId: number, smscAddr: string, callback: AsyncCallback<void>): void | 根据指定的插槽ID设置短信服务中心的地址。                |
+| getSmscAddr(slotId: number, callback: AsyncCallback<string>): void | 根据指定的插槽ID获取短信服务中心地址。                                  |
+
+
+## 开发步骤
+
+1. 声明接口调用所需要的权限：
+   - 如果是想发送短信，则调用sendMessage接口，需要配置ohos.permission.SEND_MESSAGES权限，权限级别为system_basic。
+   - 如果是想设置短信服务中心地址，则调用setSmscAddr接口，需要配置ohos.permission.SET_TELEPHONY_STATE权限，权限级别为system_basic。
+   - 如果是想获取短信服务中心地址，则调用getSmscAddr接口，需要配置ohos.permission.GET_TELEPHONY_STATE权限，权限级别为system_basic。
+   在申请权限前，请保证符合[权限使用的基本原则](../security/accesstoken-overview.md#权限使用的基本原则)。然后参考[配置文件权限声明指导文档](../security/accesstoken-guidelines.md#配置文件权限声明)声明对应权限。
+
+2. import需要的模块。
+
+3. 基于协议数据单元（PDU）和指定的SMS协议创建SMS消息实例。
+
+4. 发送SMS消息。
+
+   ```js
+    // import需要的模块
+    import sms from '@ohos.telephony.sms'
+   
+    export default class SmsModel {
+        async createMessage() {
+            const specification = '3gpp'
+            const pdu = [0x08, 0x91] // 以数组的形式显示协议数据单元（PDU），类型为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)
+                }
+            }
+            // 发送SMS消息
+            sms.sendMessage(options)
+            Logger.info(`${TAG}, sendMessage end`)
+        }
+   
+        // 获取用于发送短信的默认SIM卡
+        async getDefaultSmsSlotId() {
+            const defaultSmsSlotId = await sms.getDefaultSmsSlotId()
+            Logger.info(`${TAG}, getDefaultSmsSlotId: defaultSmsSlotId = ${defaultSmsSlotId}`)
+            return defaultSmsSlotId
+        }
+   
+        // 根据指定的插槽ID设置短信服务中心的地址
+        async setSmscAddr(slotId, smscAddr) {
+            const serviceCenter = await sms.setSmscAddr(slotId, smscAddr)
+            Logger.info(`${TAG}, setSmscAddr: serviceCenter = ${JSON.stringify(serviceCenter)}`)
+            return serviceCenter
+        }
+   
+        // 根据指定的插槽ID获取短信服务中心地址
+        async getSmscAddr(slotId) {
+            const serviceCenter = await sms.getSmscAddr(slotId)
+            Logger.info(`${TAG}, getSmscAddr: serviceCenter = ${JSON.stringify(serviceCenter)}`)
+            return serviceCenter
+        }
+    }
+   ```
+
+
+## 相关实例
+
+针对短信的使用，有以下相关实例可供参考：
+- [短信服务](https://gitee.com/openharmony/applications_app_samples/tree/master/Telephony/Message)