1# @ohos.telephony.sms (短信服务) 2 3短信服务提供了管理短信的一些基础能力,包括创建、发送短信,获取发送短信的默认SIM卡槽ID,以及检查当前设备是否具备短信发送和接收能力等。 4 5>**说明:** 6> 7>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { sms } from '@kit.TelephonyKit'; 13``` 14 15## sms.createMessage 16 17createMessage\(pdu: Array<number>, specification: string, callback: AsyncCallback\<ShortMessage\>\): void 18 19根据协议数据单元(PDU)和指定的短信协议创建短信实例。使用callback异步回调。 20 21**系统能力**:SystemCapability.Telephony.SmsMms 22 23**参数:** 24 25| 参数名 | 类型 | 必填 | 说明 | 26| ------------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | 27| pdu | Array<number> | 是 | 协议数据单元,从收到的信息中获取。 | 28| specification | string | 是 | 短信协议类型。<br/>- 3gpp:表示GSM/UMTS/LTE SMS<br/>- 3gpp2:表示CDMA SMS | 29| callback | AsyncCallback<[ShortMessage](#shortmessage)> | 是 | 获取短信实例的回调函数。 | 30 31**错误码:** 32 33以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。 34 35| 错误码ID | 错误信息 | 36| -------- | -------------------------------------------- | 37| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 38| 8300001 | Invalid parameter value. | 39| 8300002 | Operation failed. Cannot connect to service. | 40| 8300003 | System internal error. | 41| 8300999 | Unknown error code. | 42 43**示例:** 44 45```ts 46import { sms } from '@kit.TelephonyKit'; 47import { BusinessError } from '@kit.BasicServicesKit'; 48 49const specification: string = '3gpp'; 50// 以数组的形式显示协议数据单元(PDU),类型为number。 51const pdu: Array<number> = [0x01, 0x00, 0x05, 0x81, 0x01, 0x80, 0xF6, 0x00, 0x00, 0x05, 0xE8, 0x32, 0x9B, 0xFD, 0x06]; 52sms.createMessage(pdu, specification, (err: BusinessError, data: sms.ShortMessage) => { 53 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 54}); 55``` 56 57 58## sms.createMessage 59 60createMessage\(pdu: Array<number>, specification: string\): Promise\<ShortMessage\> 61 62根据协议数据单元(PDU)和指定的短信协议创建短信实例。使用Promise异步回调。 63 64**系统能力**:SystemCapability.Telephony.SmsMms 65 66**参数:** 67 68| 参数名 | 类型 | 必填 | 说明 | 69| ------------- | ------------------- | ---- | ------------------------------------------------------------ | 70| pdu | Array<number> | 是 | 协议数据单元,从收到的信息中获取。 | 71| specification | string | 是 | 短信协议类型。<br/>- 3gpp:表示GSM/UMTS/LTE SMS<br/>- 3gpp2:表示CDMA SMS | 72 73**返回值:** 74 75| 类型 | 说明 | 76| -------------------------------------------- | --------------------------------- | 77| Promise<[ShortMessage](#shortmessage)> | 以Promise形式返回创建的短信实例。 | 78 79**错误码:** 80 81以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。 82 83| 错误码ID | 错误信息 | 84| -------- | -------------------------------------------- | 85| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 86| 8300001 | Invalid parameter value. | 87| 8300002 | Operation failed. Cannot connect to service. | 88| 8300003 | System internal error. | 89| 8300999 | Unknown error code. | 90 91**示例:** 92 93```ts 94import { sms } from '@kit.TelephonyKit'; 95import { BusinessError } from '@kit.BasicServicesKit'; 96 97const specification: string = '3gpp'; 98// 以数组的形式显示协议数据单元(PDU),类型为number。 99const pdu: Array<number> = [0x01, 0x00, 0x05, 0x81, 0x01, 0x80, 0xF6, 0x00, 0x00, 0x05, 0xE8, 0x32, 0x9B, 0xFD, 0x06]; 100sms.createMessage(pdu, specification).then((data: sms.ShortMessage) => { 101 console.log(`createMessage success, promise: data->${JSON.stringify(data)}`); 102}).catch((err: BusinessError) => { 103 console.error(`createMessage failed, promise: err->${JSON.stringify(err)}`); 104}); 105``` 106 107## sms.sendMessage<sup>(deprecated)</sup> 108 109sendMessage\(options: SendMessageOptions\): void 110 111发送短信。 112 113> **说明:** 114> 115> 从 API version 6开始支持,从API version 10开始废弃。建议使用[sendShortMessage](#smssendshortmessage10)替代。 116 117**需要权限**:ohos.permission.SEND_MESSAGES(该权限仅系统应用可申请) 118 119**系统能力**:SystemCapability.Telephony.SmsMms 120 121**参数:** 122 123| 参数名 | 类型 | 必填 | 说明 | 124| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 125| options | [SendMessageOptions](#sendmessageoptions) | 是 | 发送短信的参数和回调,参考[SendMessageOptions](#sendmessageoptions)。 | 126 127**错误码:** 128 129以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。 130 131| 错误码ID | 错误信息 | 132| -------- | -------------------------------------------- | 133| 201 | Permission denied. | 134| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 135| 8300001 | Invalid parameter value. | 136| 8300002 | Operation failed. Cannot connect to service. | 137| 8300003 | System internal error. | 138| 8300999 | Unknown error code. | 139 140**示例:** 141 142```ts 143import { sms } from '@kit.TelephonyKit'; 144import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 145 146let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => { 147 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 148}; 149let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => { 150 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 151}; 152let options: sms.SendMessageOptions = { 153 slotId: 0, 154 content: '短信内容', 155 destinationHost: '+861xxxxxxxxxx', 156 serviceCenter: '+861xxxxxxxxxx', 157 destinationPort: 1000, 158 sendCallback: sendCallback, 159 deliveryCallback: deliveryCallback 160}; 161sms.sendMessage(options); 162``` 163 164## sms.sendShortMessage<sup>10+</sup> 165 166sendShortMessage\(options: SendMessageOptions, callback: AsyncCallback<void>\): void 167 168发送短信。使用callback异步回调。 169 170**需要权限**:ohos.permission.SEND_MESSAGES(该权限仅系统应用可申请) 171 172**系统能力**:SystemCapability.Telephony.SmsMms 173 174**参数:** 175 176| 参数名 | 类型 | 必填 | 说明 | 177| -------- | --------------------------- | ---- | ---------------------------------------- | 178| options | [SendMessageOptions](#sendmessageoptions) | 是 | 发送短信的参数和回调,参考[SendMessageOptions](#sendmessageoptions)。 | 179| callback | AsyncCallback<void> | 是 | 发送短信的回调函数。 | 180 181**错误码:** 182 183以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。 184 185| 错误码ID | 错误信息 | 186| -------- | -------------------------------------------- | 187| 201 | Permission denied. | 188| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 189| 8300001 | Invalid parameter value. | 190| 8300002 | Operation failed. Cannot connect to service. | 191| 8300003 | System internal error. | 192| 8300999 | Unknown error code. | 193 194**示例:** 195 196```ts 197import { sms } from '@kit.TelephonyKit'; 198import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 199 200let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => { 201 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 202}; 203let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => { 204 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 205}; 206let options: sms.SendMessageOptions = { 207 slotId: 0, 208 content: '短信内容', 209 destinationHost: '+861xxxxxxxxxx', 210 serviceCenter: '+861xxxxxxxxxx', 211 destinationPort: 1000, 212 sendCallback: sendCallback, 213 deliveryCallback: deliveryCallback 214}; 215sms.sendShortMessage(options, (err: BusinessError) => { 216 console.log(`callback: err->${JSON.stringify(err)}`); 217}); 218``` 219 220## sms.sendShortMessage<sup>10+</sup> 221 222sendShortMessage\(options: SendMessageOptions\): Promise<void> 223 224发送短信。使用Promise异步回调。 225 226**需要权限**:ohos.permission.SEND_MESSAGES(该权限仅系统应用可申请) 227 228**系统能力**:SystemCapability.Telephony.SmsMms 229 230**参数:** 231 232| 参数名 | 类型 | 必填 | 说明 | 233| -------- | --------------------------- | ---- | ---------------------------------------- | 234| options | [SendMessageOptions](#sendmessageoptions) | 是 | 发送短信的参数和回调,参考[SendMessageOptions](#sendmessageoptions)。 | 235 236**返回值:** 237 238| 类型 | 说明 | 239| --------------- | ------------------------------------------------------------ | 240| Promise<void> | 以Promise形式返回发送短信的结果。 | 241 242**错误码:** 243 244以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。 245 246| 错误码ID | 错误信息 | 247| -------- | -------------------------------------------- | 248| 201 | Permission denied. | 249| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 250| 8300001 | Invalid parameter value. | 251| 8300002 | Operation failed. Cannot connect to service. | 252| 8300003 | System internal error. | 253| 8300999 | Unknown error code. | 254 255**示例:** 256 257```ts 258import { sms } from '@kit.TelephonyKit'; 259import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 260 261let sendCallback: AsyncCallback<sms.ISendShortMessageCallback> = (err: BusinessError, data: sms.ISendShortMessageCallback) => { 262 console.log(`sendCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 263}; 264let deliveryCallback: AsyncCallback<sms.IDeliveryShortMessageCallback> = (err: BusinessError, data: sms.IDeliveryShortMessageCallback) => { 265 console.log(`deliveryCallback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 266}; 267let options: sms.SendMessageOptions = { 268 slotId: 0, 269 content: '短信内容', 270 destinationHost: '+861xxxxxxxxxx', 271 serviceCenter: '+861xxxxxxxxxx', 272 destinationPort: 1000, 273 sendCallback: sendCallback, 274 deliveryCallback: deliveryCallback 275}; 276let promise = sms.sendShortMessage(options); 277promise.then(() => { 278 console.log(`sendShortMessage success`); 279}).catch((err: BusinessError) => { 280 console.error(`sendShortMessage failed, promise: err->${JSON.stringify(err)}`); 281}); 282 283``` 284 285 286## sms.getDefaultSmsSlotId<sup>7+</sup> 287 288getDefaultSmsSlotId\(callback: AsyncCallback<number>\): void 289 290获取发送短信的默认SIM卡槽ID。使用callback异步回调。 291 292**系统能力**:SystemCapability.Telephony.SmsMms 293 294**参数:** 295 296| 参数名 | 类型 | 必填 | 说明 | 297| -------- | --------------------------- | ---- | ---------------------------------------- | 298| callback | AsyncCallback<number> | 是 | 获取发送短信的默认SIM卡槽ID的回调函数。<br/>- 0:卡槽1<br/>- 1:卡槽2 | 299 300**示例:** 301 302```ts 303import { sms } from '@kit.TelephonyKit'; 304import { BusinessError } from '@kit.BasicServicesKit'; 305 306sms.getDefaultSmsSlotId((err: BusinessError, data: number) => { 307 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 308}); 309``` 310 311 312## sms.getDefaultSmsSlotId<sup>7+</sup> 313 314getDefaultSmsSlotId\(\): Promise<number> 315 316获取发送短信的默认SIM卡槽ID。使用Promise异步回调。 317 318**系统能力**:SystemCapability.Telephony.SmsMms 319 320**返回值:** 321 322| 类型 | 说明 | 323| --------------- | ------------------------------------------------------------ | 324| Promise<number> | 以Promise形式返回发送短信的默认SIM卡:<br/>- 0:卡槽1<br/>- 1:卡槽2 | 325 326**示例:** 327 328```ts 329import { sms } from '@kit.TelephonyKit'; 330import { BusinessError } from '@kit.BasicServicesKit'; 331 332sms.getDefaultSmsSlotId().then((data: number) => { 333 console.log(`getDefaultSmsSlotId success, promise: data->${JSON.stringify(data)}`); 334}).catch((err: BusinessError) => { 335 console.error(`getDefaultSmsSlotId failed, promise: err->${JSON.stringify(err)}`); 336}); 337``` 338 339## sms.hasSmsCapability<sup>7+</sup> 340 341hasSmsCapability\(\): boolean 342 343检查当前设备是否具备短信发送和接收能力,该方法是同步方法。 344 345**系统能力**:SystemCapability.Telephony.SmsMms 346 347**返回值:** 348 349| 类型 | 说明 | 350| ------- | ------------------------------------------------------------ | 351| boolean | - true:设备具备短信发送和接收能力。<br/>- false:设备不具备短信发送和接收能力。 | 352 353```ts 354import { sms } from '@kit.TelephonyKit'; 355 356let result = sms.hasSmsCapability(); 357console.log(`hasSmsCapability: ${JSON.stringify(result)}`); 358``` 359 360## sms.getDefaultSmsSimId<sup>10+</sup> 361 362getDefaultSmsSimId\(callback: AsyncCallback<number>\): void 363 364获取发送短信的默认SIM卡ID。使用callback异步回调。 365 366**系统能力**:SystemCapability.Telephony.SmsMms 367 368**参数:** 369 370| 参数名 | 类型 | 必填 | 说明 | 371| -------- | --------------------------- | ---- | ---------------------------------------- | 372| callback | AsyncCallback<number> | 是 | 获取默认短信SIM的SIM ID的回调函数。<br/>与SIM卡绑定,从1开始递增。<br/>无卡时返回值为-1。 | 373 374**错误码:** 375 376以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。 377 378| 错误码ID | 错误信息 | 379| -------- | -------------------------------------------- | 380| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 381| 8300001 | Invalid parameter value. | 382| 8300002 | Operation failed. Cannot connect to service. | 383| 8300003 | System internal error. | 384| 8300004 | Do not have sim card. | 385| 8300999 | Unknown error code. | 386| 8301001 | SIM card is not activated. | 387 388**示例:** 389 390```ts 391import { sms } from '@kit.TelephonyKit'; 392import { BusinessError } from '@kit.BasicServicesKit'; 393 394sms.getDefaultSmsSimId((err: BusinessError, data: number) => { 395 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 396}); 397``` 398 399 400## sms.getDefaultSmsSimId<sup>10+</sup> 401 402getDefaultSmsSimId\(\): Promise<number> 403 404获取发送短信的默认SIM卡ID。使用Promise异步回调。 405 406**系统能力**:SystemCapability.Telephony.SmsMms 407 408**返回值:** 409 410| 类型 | 说明 | 411| --------------- | ------------------------------------------------------------ | 412| Promise<number> | 以Promise形式返回发送短信的默认SIM卡ID:<br/>与SIM卡绑定,从1开始递增。<br/>无卡时返回值为-1。 | 413 414**错误码:** 415 416以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。 417 418| 错误码ID | 错误信息 | 419| -------- | -------------------------------------------- | 420| 8300001 | Invalid parameter value. | 421| 8300002 | Operation failed. Cannot connect to service. | 422| 8300003 | System internal error. | 423| 8300004 | Do not have sim card. | 424| 8300999 | Unknown error code. | 425| 8301001 | SIM card is not activated. | 426 427**示例:** 428 429```ts 430import { sms } from '@kit.TelephonyKit'; 431import { BusinessError } from '@kit.BasicServicesKit'; 432 433let promise = sms.getDefaultSmsSimId(); 434promise.then((data: number) => { 435 console.log(`getDefaultSmsSimId success, promise: data->${JSON.stringify(data)}`); 436}).catch((err: BusinessError) => { 437 console.error(`getDefaultSmsSimId failed, promise: err->${JSON.stringify(err)}`); 438}); 439``` 440 441 442## ShortMessage 443 444短信实例。 445 446**系统能力**:SystemCapability.Telephony.SmsMms 447 448| 名称 | 类型 | 必填 | 说明 | 449| ------------------------ | --------------------------------------- | ---- | ------------------------------------------------------------ | 450| hasReplyPath | boolean | 是 | 收到的短信是否包含“TP-Reply-Path”,默认为false。<br/>“TP-Reply-Path”:设备根据发送SMS消息的短消息中心进行回复。 | 451| isReplaceMessage | boolean | 是 | 收到的短信是否为“替换短信”,默认为false。<br/>“替换短信”有关详细信息,参见 [“3GPP TS 23.040 9.2.3.9”](https://www.3gpp.org/ftp/specs/archive/23_series/23.040)。 | 452| isSmsStatusReportMessage | boolean | 是 | 当前消息是否为“短信状态报告”,默认为false。<br/>“短信状态报告”是一种特定格式的短信,被用来从Service Center到Mobile Station传送状态报告。| 453| messageClass | [ShortMessageClass](#shortmessageclass) | 是 | 短信类型。 | 454| pdu | Array<number> | 是 | SMS消息中的协议数据单元 (PDU)。 | 455| protocolId | number | 是 | 发送短信时使用的协议标识。 | 456| scAddress | string | 是 | 短消息服务中心(SMSC)地址。 | 457| scTimestamp | number | 是 | SMSC时间戳。 | 458| status | number | 是 | SMS-STATUS-REPORT消息中的短信状态指示短信服务中心(SMSC)发送的短信状态。 | 459| visibleMessageBody | string | 是 | 短信正文。 | 460| visibleRawAddress | string | 是 | 发送者地址。 | 461 462 463## ShortMessageClass 464 465短信类型。 466 467**系统能力**:SystemCapability.Telephony.SmsMms 468 469| 名称 | 值 | 说明 | 470| ---------------- | ---- | ---------------------------------------- | 471| UNKNOWN | 0 | 未知类型。 | 472| INSTANT_MESSAGE | 1 | 即时消息,收到后立即显示。 | 473| OPTIONAL_MESSAGE | 2 | 存储在设备或SIM卡上的短信。 | 474| SIM_MESSAGE | 3 | 包含SIM卡信息的短信,需要存储在SIM卡中。 | 475| FORWARD_MESSAGE | 4 | 要转发到另一台设备的短信。 | 476 477 478## SendMessageOptions 479 480发送短信的参数和回调。根据SendMessageOptions中的可选参数content的值判断短信类型。 481 482**系统能力**:SystemCapability.Telephony.SmsMms 483 484| 名称 | 类型 | 必填 | 说明 | 485| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 486| slotId | number | 是 | 用于发送短信的SIM卡槽ID:<br/>- 0:卡槽1<br/>- 1:卡槽2 | 487| destinationHost | string | 是 | 短信的发送地址。 | 488| content | string \| Array<number> | 是 | 如果内容是字符串,则这是一条文本短信。如果内容是字节数组,则这是一条数据短信。 | 489| serviceCenter | string | 否 | 短信中心地址。默认使用SIM卡中的短信中心地址。 | 490| destinationPort | number | 否 | 如果发送数据消息,destinationPort 是必需的。否则是可选的。 | 491| sendCallback | AsyncCallback<[ISendShortMessageCallback](#isendshortmessagecallback)> | 否 | 短信发送结果回调,返回短信发送的结果,参考[ISendShortMessageCallback](#isendshortmessagecallback)。发送数据短信时,此项必填。| 492| deliveryCallback | AsyncCallback<[IDeliveryShortMessageCallback](#ideliveryshortmessagecallback)> | 否 | 短信送达结果回调,返回短信递送报告,参考[IDeliveryShortMessageCallback](#ideliveryshortmessagecallback)。发送数据短信时,此项必填。| 493 494 495 496## ISendShortMessageCallback 497 498回调实例。返回短信发送结果、存储已发送短信的URI和是否为长短信的最后一部分。 499 500**系统能力**:SystemCapability.Telephony.SmsMms 501 502| 名称 | 类型 | 必填 | 说明 | 503| ---------- | ------------------------------- | ---- | ----------------------------------------------------------------------------------------- | 504| isLastPart | boolean | 是 | 指定这是否是长短信的最后一部分。true表示这是长短信的最后一部分,false表示不是。默认为false。 | 505| result | [SendSmsResult](#sendsmsresult) | 是 | 短信发送结果。 | 506| url | string | 是 | 存储发送短信的URI。 | 507 508 509## IDeliveryShortMessageCallback 510 511回调实例,返回短信送达报告。 512 513**系统能力**:SystemCapability.Telephony.SmsMms 514 515| 名称 | 类型 | 必填 | 说明 | 516| ---- | ------------------- | ---- | -------------- | 517| pdu | Array<number> | 是 | 短信送达报告。 | 518 519 520## SendSmsResult 521 522短信发送结果。 523 524**系统能力**:SystemCapability.Telephony.SmsMms 525 526| 名称 | 值 | 说明 | 527| ------------------------------------ | ---- | ------------------------------------------------------ | 528| SEND_SMS_SUCCESS | 0 | 发送短信成功。 | 529| SEND_SMS_FAILURE_UNKNOWN | 1 | 发送短信失败,原因未知。 | 530| SEND_SMS_FAILURE_RADIO_OFF | 2 | 发送短信失败,原因为调制解调器关机。 | 531| SEND_SMS_FAILURE_SERVICE_UNAVAILABLE | 3 | 发送短信失败,原因为网络不可用、不支持发送或接收短信。 | 532