• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 短信服务
2
3## 场景介绍
4
5短信服务模块提供了管理短信的一些基础能力，包括创建/发送短信、获取/设置发送短信的默认SIM卡槽ID、获取/设置短信服务中心地址，以及检查当前设备是否具备短信发送和接收能力等。
6
7常见的应用场景举例如下：
8
9- 从网页拉起：
10  - 用户在网页上浏览，看到“发送短信”按钮，点击后会拉起短信应用，预先填写收件人号码、发送内容。
11- 从应用拉起：
12  - 移动应用中，用户点击“发送短信”按钮时，应用调用系统功能，拉起短信应用，预先填写收件人号码、发送内容。
13
14## 基本概念
15
16- 短信服务
17
18  即SMS（Short Messaging Service），是一种存储和转发服务。用户的移动电话可以通过它进行相互收发短信，内容以文本、数字或二进制非文本数据为主。发送方的信息通过短信服务中心进行储存并转发给接收方。
19- 短信服务中心
20
21  即SMSC（Short Message Service Center），负责在基站和移动设备间中继、储存或转发短消息。移动设备到短信服务中心的协议能传输来自移动设备或朝向移动设备的短消息，协议内容遵从GSM 03.40协议。
22- 协议数据单元
23
24  即PDU（Protocol Data Unit），PDU模式收发短信可以使用3种编码：7-bit、8-bit和UCS-2编码。7-bit编码用于发送普通的ASCII字符，8-bit编码通常用于发送数据短信，UCS-2编码用于发送Unicode字符。
25
26## 约束与限制
27
281. 仅支持在标准系统上运行。
292. 需授予发送短信权限且插入SIM卡才可成功发送短信。
30
31## 接口说明
32
33> **说明：**
34> 为了保证应用的运行效率，大部分API调用都是异步的，对于异步调用的API均提供了callback和Promise两种方式，以下示例采用callback回调方式，其他调用方式请参考[API](../reference/apis-telephony-kit/js-apis-sms.md)文档。
35
36| 接口名                                                       | 描述                                                    |
37| ------------------------------------------------------------ | ------------------------------------------------------- |
38| sendShortMessage(options: SendMessageOptions, callback: AsyncCallback\<void\>): void              | 发送文本或数据SMS消息。需要配置ohos.permission.SEND_MESSAGES权限，该权限仅系统应用可申请。      |
39| createMessage(pdu: Array\<number\>, specification: string, callback: AsyncCallback\<ShortMessage\>): void | 基于协议数据单元（PDU）和指定的SMS协议创建SMS消息实例。 |
40| getDefaultSmsSlotId(callback: AsyncCallback\<number\>): void   | 获取用于发送短信的默认SIM卡。                                                |
41| <!--DelRow-->setSmscAddr(slotId: number, smscAddr: string, callback: AsyncCallback\<void\>): void | 根据指定的插槽ID设置短信服务中心的地址。                |
42| <!--DelRow-->getSmscAddr(slotId: number, callback: AsyncCallback\<string>): void | 根据指定的插槽ID获取短信服务中心地址。                                  |
43
44<!--Del-->
45
46## 发送短信（仅供系统应用使用）
47
481. 声明接口调用所需要的权限：
49
50   - 如果是想发送短信，则调用sendShortMessage接口，需要配置ohos.permission.SEND_MESSAGES权限，权限级别为system_basic。
51   - 如果是想设置短信服务中心地址，则调用setSmscAddr接口，需要配置ohos.permission.SET_TELEPHONY_STATE权限，权限级别为system_basic。
52   - 如果是想获取短信服务中心地址，则调用getSmscAddr接口，需要配置ohos.permission.GET_TELEPHONY_STATE权限，权限级别为system_basic。
53   在申请权限前，请保证符合[权限使用的基本原则](../security/AccessToken/app-permission-mgmt-overview.md#权限使用的基本原则)。然后参考[申请应用权限](../security/AccessToken/determine-application-mode.md#system_basic等级应用申请权限的方式)声明对应权限。
542. import需要的模块。
55
563. 发送SMS消息。
57
58```ts
59// 示例代码
60import { sms } from '@kit.TelephonyKit';
61import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
62
63let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => {
64    console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`);
65}
66let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => {
67    console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`);
68}
69let slotId: number = 0;
70let content: string = '短信内容';
71let destinationHost: string = '+861xxxxxxxxxx';
72let serviceCenter: string = '+861xxxxxxxxxx';
73let destinationPort: number = 1000;
74let options: sms.SendMessageOptions = {slotId, content, destinationHost, serviceCenter, destinationPort, sendCallback, deliveryCallback};
75sms.sendShortMessage(options, (err: BusinessError) => {
76    console.log(`callback: err->${JSON.stringify(err)}`);
77});
78
79```
80
81<!--DelEnd-->
82
83## 应用内跳转到短信编辑界面
84
85发送短信的接口需要系统权限才可调用，三方应用如果有发送短信需求，需要在应用内实现跳转到短信编辑的功能，并且需要携带编辑内容和收件人号码，可以通过调用元能力startAbility接口指定号码并跳转到发送短信页面的方式实现。
86
87```ts
88// 示例代码
89import { common, Want } from '@kit.AbilityKit';
90
91const MMS_BUNDLE_NAME = "com.ohos.mms";
92const MMS_ABILITY_NAME = "com.ohos.mms.MainAbility";
93const MMS_ENTITIES = "entity.system.home";
94
95export class Contact {
96    contactsName: string;
97    telephone: number;
98
99    constructor(contactsName: string, telephone: number) {
100        this.contactsName = contactsName;
101        this.telephone = telephone;
102    }
103}
104
105@Entry
106@Component
107struct JumpMessage {
108    private context = getContext(this) as common.UIAbilityContext;
109
110    startMMSAbilityExplicit() {
111        // 这里完善联系人和号码；姓名主要是通过手机号来查询实际联系人名称，因此这种方式还是以手机号码为主。
112        let params: Array<Object> = [new Contact("张三", 133XXXXXXXX)];
113
114        let want: Want = {
115            bundleName: "com.ohos.mms",
116            abilityName: "com.ohos.mms.MainAbility",
117            parameters: {
118                contactObjects: JSON.stringify(params),
119                pageFlag: "conversation",
120                // 这里填写短信内容。
121                content: "我是短信具体内容"
122            }
123        };
124
125        this.context.startAbilityForResult(want).then((data) => {
126            console.log("Success" + JSON.stringify(data));
127        }).catch(() => {
128            console.log("error");
129        });
130    }
131
132    build() {
133        Row() {
134            Column() {
135                Button('发送短信')
136                  .onClick(() => {
137                      this.startMMSAbilityExplicit();
138                  })
139            }
140            .width('100%')
141        }
142        .height('100%')
143    }
144}
145
146```
147
148## sms方式跳转到短信编辑界面
149
150### 使用场景
151
152通过sms短信协议，可以创建指向短信收件人的超链接，方便用户通过网页或应用中的超链接直接跳转到短信应用。同时，支持在`sms:`的相关字段中定义短信的收件人、发送内容等，节省用户编辑短信的时间。
153
154### sms协议格式
155
156sms协议标准格式如下：
157
158```
159sms:106XXXXXXXXXX?body=发送短信内容
160```
161
162+ `sms:`：sms scheme，必填。
163+ `106XXXXXXXXXX：收件人号码，选填。如果存在多个地址，用英文逗号分隔。
164+ `?`：短信内容声明开始符号。如果带短信内容参数，则必填。
165+ `body-value`：发送内容参数，选填。
166
167### 拉起方开发步骤
168
169#### 从网页拉起
170
171网页中的超链接需要满足sms协议。示例如下：
172
173```
174<a href="sms:106XXXXXXXXXX?body=%E5%8F%91%E9%80%81%E7%9F%AD%E4%BF%A1%E5%86%85%E5%AE%B9">发送短信</a>
175```
176
177实际开发时，需要将收件人号码替换为真实的号码，短信内容可以根据需要进行配置。
178
179#### 从应用拉起
180
181保证sms字符串传入uri参数即可，在应用中page页面可通过 getContext(this) 获取context，在ability中可通过this.context获取context。
182
183```ts
184@Entry
185@Component
186struct Index {
187
188  build() {
189    Column() {
190      Button('发送短信')
191        .onClick(() => {
192          let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
193          let exampleUrl = "sms:106XXXXXXXXXX?body=%E5%8F%91%E9%80%81%E7%9F%AD%E4%BF%A1%E5%86%85%E5%AE%B9";
194
195          let want: Want = {
196              bundleName: 'com.ohos.mms',
197              action: 'ohos.want.action.viewData',
198              uri:exampleUrl,
199            }
200
201          context.startAbility(want).then((data) => {
202              console.log("Success" + JSON.stringify(data));
203          }).catch(() => {
204              console.log("error");
205          });
206
207        })
208    }
209  }
210}
211```
212
213## 相关实例
214
215针对短信的使用，有以下相关实例可供参考：
216
217- [短信服务（ArkTS）（Full SDK）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/SystemFeature/Telephony/Message)