js-apis-sms.md 17.2 KB
Newer Older
Z
zengyawen 已提交
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
# 短信服务

-   [导入模块](#导入模块)
-   [sms.createMessage](#sms.createMessage-callback)
-   [sms.createMessage](#sms.createMessage-promise)
-   [sms.sendMessage](#sms.sendMessage)
-   [sms.getDefaultSmsSlotId<sup>7+</sup>](#sms.getDefaultSmsSlotId-callback)
-   [sms.getDefaultSmsSlotId<sup>7+</sup>](#sms.getDefaultSmsSlotId-promise)
-   [sms.setSmscAddr<sup>7+</sup>](#sms.setSmscAddr-callback)
-   [sms.setSmscAddr<sup>7+</sup>](#sms.setSmscAddr-promise)
-   [sms.getSmscAddr<sup>7+</sup>](#sms.getSmscAddr-callback)
-   [sms.getSmscAddr<sup>7+</sup>](#sms.getSmscAddr-promise)
-   [ShortMessage](#ShortMessage)
-   [ShortMessageClass](#ShortMessageClass)
-   [SendMessageOptions](#SendMessageOptions)
-   [ISendShortMessageCallback](#ISendShortMessageCallback)
-   [IDeliveryShortMessageCallback](#IDeliveryShortMessageCallback)
-   [SendSmsResult](#SendSmsResult)
C
clevercong 已提交
19 20 21

>**说明:** 
>
Z
zengyawen 已提交
22 23 24
>- 从 API Version 6 开始支持。
>
>- 标记<sup>7+</sup>的接口从API Version 7开始支持。
C
clevercong 已提交
25

Z
zengyawen 已提交
26
## 导入模块
C
clevercong 已提交
27 28 29 30 31

```
import sms from '@ohos.telephony.sms';
```

Z
zengyawen 已提交
32
## sms.createMessage<a name=sms.createMessage-callback></a>
C
clevercong 已提交
33 34 35 36 37 38 39

createMessage\(pdu: Array<number\>, specification: string, callback: AsyncCallback<ShortMessage\>\): void

根据协议数据单元(PDU)和指定的短信协议创建短信实例,使用callback方式作为异步方法。

- 参数

Z
zengyawen 已提交
40 41 42 43 44
  | 参数名        | 类型                                               | 必填 | 说明                                                         |
  | ------------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ |
  | pdu           | Array&lt;number&gt;                                | 是   | 协议数据单元,从收到的信息中获取。                           |
  | specification | string                                             | 是   | 短信协议类型。<br/>- 3gpp表示GSM/UMTS/LTE SMS<br/>- 3gpp2表示CDMA SMS |
  | callback      | AsyncCallback&lt;[ShortMessage](#ShortMessage)&gt; | 是   | 回调函数。                                                   |
C
clevercong 已提交
45 46 47 48 49 50 51 52 53 54 55 56

-   示例

    ```
    let specification = '3gpp';
    let pdu = [0x08, 0x91, ...];
    sms.createMessage(pdu, specification, (err, data) => {
        console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`);
    });
    ```


Z
zengyawen 已提交
57
## sms.createMessage<a name=sms.createMessage-promise></a>
C
clevercong 已提交
58 59 60 61 62

createMessage\(pdu: Array<number\>, specification: string\): Promise<ShortMessage\>

根据协议数据单元(PDU)和指定的短信协议创建短信实例,使用Promise方式作为异步方法。

Z
zengyawen 已提交
63 64 65 66 67 68 69 70 71 72 73 74
- 参数

  | 参数名        | 类型                | 必填 | 说明                                                         |
  | ------------- | ------------------- | ---- | ------------------------------------------------------------ |
  | pdu           | Array&lt;number&gt; | 是   | 协议数据单元,从收到的信息中获取。                           |
  | specification | string              | 是   | 短信协议类型。<br/>- 3gpp表示GSM/UMTS/LTE SMS<br/>- 3gpp2表示CDMA SMS |

- 返回值

  | 类型                                         | 说明                              |
  | -------------------------------------------- | --------------------------------- |
  | Promise&lt;[ShortMessage](#ShortMessage)&gt; | 以Promise形式返回创建的短信实例。 |
C
clevercong 已提交
75 76 77 78 79 80 81 82 83 84 85 86 87 88

-   示例

    ```
    let specification = '3gpp';
    let pdu = [0x08, 0x91, ...];
    let promise = sms.createMessage(pdu, specification);
    promise.then(data => {
        console.log(`createMessage success, promise: data->${JSON.stringify(data)}`);
    }).catch(err => {
        console.error(`createMessage fail, promise: err->${JSON.stringify(err)}`);
    });
    ```

Z
zengyawen 已提交
89
## sms.sendMessage
C
clevercong 已提交
90

Z
zengyawen 已提交
91
sendMessage(options: SendMessageOptions): void
C
clevercong 已提交
92 93 94

发送短信。

Z
zengyawen 已提交
95
需要ohos.permission.SEND_MESSAGES权限。
C
clevercong 已提交
96

Z
zengyawen 已提交
97
- 参数
C
clevercong 已提交
98

Z
zengyawen 已提交
99 100 101
  | 参数名  | 类型                                      | 必填 | 说明                                                         |
  | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
  | options | [SendMessageOptions](#SendMessageOptions) | 是   | 发送短信的参数和回调,参考[SendMessageOptions](#SendMessageOptions)。 |
C
clevercong 已提交
102

Z
zengyawen 已提交
103
- 示例
C
clevercong 已提交
104

Z
zengyawen 已提交
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
  ```
  let sendCallback = function (err, data) {    
      console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 
  }
  let deliveryCallback = function (err, data) {    
      console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 
  }
  let slotId = 0;
  let content = '短信内容';
  let destinationHost = '+861xxxxxxxxxx';
  let serviceCenter = '+861xxxxxxxxxx';
  let destinationPort = 1000;
  let options = {slotId, content, destinationHost, serviceCenter, destinationPort, sendCallback, deliveryCallback};
  sms.sendMessage(options);
  ```


## sms.getDefaultSmsSlotId<sup>7+</sup><a name=sms.getDefaultSmsSlotId-callback></a>
C
clevercong 已提交
123 124 125 126 127

getDefaultSmsSlotId\(callback: AsyncCallback<number\>\): void

获取发送短信的默认SIM卡槽ID,使用callback方式作为异步方法。

Z
zengyawen 已提交
128 129 130 131 132
- 参数

  | 参数名   | 类型                        | 必填 | 说明                                     |
  | -------- | --------------------------- | ---- | ---------------------------------------- |
  | callback | AsyncCallback&lt;number&gt; | 是   | 回调函数。<br/>- 0:卡槽1<br/>- 1:卡槽2 |
C
clevercong 已提交
133 134 135 136 137 138 139 140 141 142

-   示例

    ```
    sms.getDefaultSmsSlotId((err, data) => {
        console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`);
    });
    ```


Z
zengyawen 已提交
143
## sms.getDefaultSmsSlotId<sup>7+</sup><a name=sms.getDefaultSmsSlotId-promise></a>
C
clevercong 已提交
144 145 146 147 148

getDefaultSmsSlotId\(\): Promise<number\>

获取发送短信的默认SIM卡槽ID,使用Promise方式作为异步方法。

Z
zengyawen 已提交
149 150 151 152 153
- 返回值

  | 类型            | 说明                                                         |
  | --------------- | ------------------------------------------------------------ |
  | Promise<number> | 以Promise形式返回发送短信的默认SIM卡:<br/>- 0:卡槽1<br/>- 1:卡槽2 |
C
clevercong 已提交
154 155 156 157 158 159 160 161 162 163 164 165 166

-   示例

    ```
    let promise = call.getDefaultSmsSlotId();
    promise.then(data => {
        console.log(`getDefaultSmsSlotId success, promise: data->${JSON.stringify(data)}`);
    }).catch(err => {
        console.error(`getDefaultSmsSlotId fail, promise: err->${JSON.stringify(err)}`);
    });
    ```


Z
zengyawen 已提交
167
## sms.setSmscAddr<sup>7+</sup><a name=sms.setSmscAddr-callback></a>
C
clevercong 已提交
168 169 170 171 172 173 174

setSmscAddr\(slotId: number, smscAddr: string, callback: AsyncCallback<void\>\): void

设置短信服务中心(SMSC)地址,使用callback方式作为异步方法。

需要ohos.permission.SET\_TELEPHONY\_STATE权限,该权限为系统权限。

Z
zengyawen 已提交
175 176 177 178 179 180 181
- 参数

  | 参数名   | 类型                      | 必填 | 说明                                      |
  | -------- | ------------------------- | ---- | ----------------------------------------- |
  | slotId   | number                    | 是   | SIM卡槽ID:<br/>- 0:卡槽1<br/>- 1:卡槽2 |
  | smscAddr | string                    | 是   | 短信服务中心地址。                        |
  | callback | AsyncCallback&lt;void&gt; | 是   | 回调函数。                                |
C
clevercong 已提交
182 183 184 185 186 187 188 189 190 191 192 193

-   示例

    ```
    let slotId = 0;
    let smscAddr = '+861xxxxxxxxxx';
    sms.setSmscAddr(slotId, smscAddr, (err,data) => {
          console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`);
    });
    ```


Z
zengyawen 已提交
194
## sms.setSmscAddr<sup>7+</sup><a name=sms.setSmscAddr-promise></a>
C
clevercong 已提交
195 196 197 198 199 200 201

setSmscAddr\(slotId: number, smscAddr: string\): Promise<void\>

设置短信服务中心(SMSC)地址,使用Promise方式作为异步方法。

需要ohos.permission.SET\_TELEPHONY\_STATE权限,该权限为系统权限。

Z
zengyawen 已提交
202 203 204 205 206 207 208 209 210 211 212 213
- 参数

  | 参数名   | 类型   | 必填 | 说明                                      |
  | -------- | ------ | ---- | ----------------------------------------- |
  | slotId   | number | 是   | SIM卡槽ID:<br/>- 0:卡槽1<br/>- 1:卡槽2 |
  | smscAddr | string | 是   | 短信服务中心地址。                        |

- 返回值

  | 类型                | 说明                            |
  | ------------------- | ------------------------------- |
  | Promise&lt;void&gt; | 以Promise形式异步返回设置结果。 |
C
clevercong 已提交
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228

-   示例

    ```
    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 => {
        console.error(`setSmscAddr fail, promise: err->${JSON.stringify(err)}`);
    });
    ```


Z
zengyawen 已提交
229
## sms.getSmscAddr<sup>7+</sup><a name=sms.getSmscAddr-callback></a>
C
clevercong 已提交
230 231 232 233 234 235 236

getSmscAddr\(slotId: number, callback: AsyncCallback<string\>\): void

获取短信服务中心(SMSC)地址,使用callback方式作为异步方法。

需要ohos.permission.GET\_TELEPHONY\_STATE权限,该权限为系统权限。

Z
zengyawen 已提交
237 238 239 240 241 242
- 参数

  | 参数名   | 类型                        | 必填 | 说明                                      |
  | -------- | --------------------------- | ---- | ----------------------------------------- |
  | slotId   | number                      | 是   | SIM卡槽ID:<br/>- 0:卡槽1<br/>- 1:卡槽2 |
  | callback | AsyncCallback&lt;string&gt; | 是   | 回调函数。                                |
C
clevercong 已提交
243 244 245 246 247 248 249 250 251 252 253

-   示例

    ```
    let slotId = 0;
    sms.getSmscAddr(slotId, (err, data) => {
          console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`);
    });
    ```


Z
zengyawen 已提交
254
## sms.getSmscAddr<sup>7+</sup><a name=sms.getSmscAddr-promise></a>
C
clevercong 已提交
255 256 257 258 259 260 261

getSmscAddr\(slotId: number\): Promise<string\>

获取短信服务中心(SMSC)地址,使用Promise方式作为异步方法。

需要ohos.permission.GET\_TELEPHONY\_STATE权限,该权限为系统权限。

Z
zengyawen 已提交
262 263 264 265 266 267 268 269 270 271 272
- 参数

  | 参数名 | 类型   | 必填 | 说明                                      |
  | ------ | ------ | ---- | ----------------------------------------- |
  | slotId | number | 是   | SIM卡槽ID:<br/>- 0:卡槽1<br/>- 1:卡槽2 |

- 返回值

  | 类型                  | 说明                                          |
  | --------------------- | --------------------------------------------- |
  | Promise&lt;string&gt; | 以Promise形式返回获取短信服务中心地址的结果。 |
C
clevercong 已提交
273 274 275 276 277 278 279 280 281 282 283 284 285 286

-   示例

    ```
    let slotId = 0;
    let promise = sms.getSmscAddr(slotId);
    promise.then(data => {
        console.log(`getSmscAddr success, promise: data->${JSON.stringify(data)}`);
    }).catch(err => {
        console.error(`getSmscAddr fail, promise: err->${JSON.stringify(err)}`);
    });
    ```


Z
zengyawen 已提交
287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
## ShortMessage<a name=ShortMessage></a>

短信实例。

| 变量                     | 类型                                    | 说明                                                         |
| ------------------------ | --------------------------------------- | ------------------------------------------------------------ |
| emailAddress             | string                                  | 电子邮件地址。                                               |
| emailMessageBody         | string                                  | 电子邮件正文。                                               |
| hasReplyPath             | boolean                                 | 收到的短信是否包含“TP-Reply-Path”,默认为false。<br/>“TP-Reply-Path”:移动电话根据发送SMS消息的短消息中心进行回复。 |
| isEmailMessage           | boolean                                 | 收到的短信是否为电子邮件。                                   |
| isReplaceMessage         | boolean                                 | 收到的短信是否为“替换短信”,默认为false。<br/>“替换短信”有关详细信息,参见 “3GPP TS 23.040 9.2.3.9”。 |
| isSmsStatusReportMessage | boolean                                 | 当前消息是否为“短信状态报告”,默认为false。<br/>“短信状态报告”是一种特定格式的短信,被用来从Service Center到Mobile Station传送状态报告。 |
| messageClass             | [ShortMessageClass](#ShortMessageClass) | 短信类型。                                                   |
| pdu                      | Array&lt;number&gt;                     | SMS消息中的协议数据单元 (PDU)。                            |
|protocolId|number|发送短信时使用的协议标识。|
|scAddress|string|短消息服务中心(SMSC)地址。|
|scTimestamp|number|SMSC时间戳。|
|status|number|SMS-STATUS-REPORT消息中的短信状态指示短信服务中心(SMSC)发送的短信状态。|
|userRawData|Array&lt;number&gt;|除数据头外的用户数据。|
|visibleMessageBody|string|短信正文。|
|visibleRawAddress|string|发送者地址。|


## ShortMessageClass<a name=ShortMessageClass></a>
C
clevercong 已提交
311 312 313

短信类型。

Z
zengyawen 已提交
314 315 316 317 318 319 320 321 322 323
| 变量             | 值   | 说明                                     |
| ---------------- | ---- | ---------------------------------------- |
| UNKNOWN          | 0    | 未知类型。                               |
| INSTANT_MESSAGE  | 1    | 即时消息,收到后立即显示。               |
| OPTIONAL_MESSAGE | 2    | 存储在设备或SIM卡上的短信。              |
| SIM_MESSAGE      | 3    | 包含SIM卡信息的短信,需要存储在SIM卡中。 |
| FORWARD_MESSAGE  | 4    | 要转发到另一台设备的短信。               |


## SendMessageOptions<a name=SendMessageOptions></a>
C
clevercong 已提交
324 325 326 327 328

发送短信的参数和回调。

根据SendMessageOptions中的可选参数content的值判断短信类型。

Z
zengyawen 已提交
329 330 331 332 333 334 335 336 337 338 339 340
| 参数名           | 类型                                                         | 必填 | 说明                                                         |
| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| slotId           | number                                                       | 是   | 用于发送短信的SIM卡槽ID:<br/>- 0:卡槽1<br/>- 1:卡槽2      |
| destinationHost  | string                                                       | 是   | 短信的发送地址。                                             |
| content          | string \| Array&lt;number&gt;                                | 是   | 如果内容是字符串,则这是一条文本短信。如果内容是字节数组,则这是一条数据短信。 |
| serviceCenter    | string                                                       | 否   | 短信中心地址。默认使用SIM卡中的短信中心地址。                |
| destinationPort  | number                                                       | 否   | 如果发送数据消息,destinationPort 是必需的。否则是可选的。   |
| sendCallback     | AsyncCallback&lt;[ISendShortMessageCallback](#ISendShortMessageCallback)&gt; | 否   | 短信发送结果回调,返回短信发送的结果,参考[ISendShortMessageCallback](#ISendShortMessageCallback)。 |
| deliveryCallback | AsyncCallback&lt;[IDeliveryShortMessageCallback](#IDeliveryShortMessageCallback)&gt; | 否   | 短信送达结果回调,返回短信递送报告,参考[IDeliveryShortMessageCallback](#IDeliveryShortMessageCallback)。 |


## ISendShortMessageCallback<a name=ISendShortMessageCallback></a>
C
clevercong 已提交
341 342 343

回调实例。返回短信发送结果、存储已发送短信的URI和是否为长短信的最后一部分。

Z
zengyawen 已提交
344 345 346 347 348 349 350 351
| 参数名     | 类型                            | 必填 | 说明                                                         |
| ---------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| isLastPart | boolean                         | 否   | 指定这是否是长短信的最后一部分。true表示这是长短信的最后一部分,false表示不是。默认为false。 |
| result     | [SendSmsResult](#SendSmsResult) | 是   | 短信发送结果。                                               |
| url        | string                          | 是   | 存储发送短信的URI。                                          |


## IDeliveryShortMessageCallback<a name=IDeliveryShortMessageCallback></a>
C
clevercong 已提交
352 353 354

回调实例。返回短信送达报告。

Z
zengyawen 已提交
355 356 357 358 359 360
| 参数名 | 类型                | 必填 | 说明           |
| ------ | ------------------- | ---- | -------------- |
| pdu    | Array&lt;number&gt; | 是   | 短信送达报告。 |


## SendSmsResult<a name=SendSmsResult></a>
C
clevercong 已提交
361 362 363

短信发送结果。

Z
zengyawen 已提交
364 365 366 367 368 369 370
| 参数名                               | 值   | 说明                                                   |
| ------------------------------------ | ---- | ------------------------------------------------------ |
| SEND_SMS_SUCCESS                     | 0    | 发送短信成功。                                         |
| SEND_SMS_FAILURE_UNKNOWN             | 1    | 发送短信失败,原因未知。                               |
| SEND_SMS_FAILURE_RADIO_OFF           | 2    | 发送短信失败,原因为调制解调器关机。                   |
| SEND_SMS_FAILURE_SERVICE_UNAVAILABLE | 3    | 发送短信失败,原因为网络不可用、不支持发送或接收短信。 |