SMS and MMS

Introduction

The SMS and MMS module provides the capabilities of sending and receiving short message service SMS messages and encoding and decoding multimedia messaging service MMS messages for mobile data users. Its main functions include the following: GSM/CDMA SMS message receiving and sending, SMS protocol data unit PDU encoding and decoding, WAP Push message receiving and processing, cell broadcast message receiving, MMS message notification, MMS message encoding and decoding, and SIM SMS record management.

Figure 1 Architecture of the SMS and MMS module

The SMS and MMS module consists of the following parts:

• SmsInterfaceManager: provides external APIs for sending SMS messages and managing SIM SMS records. It can be used to create SmsSendManager and SmsReceiveManager objects.
• SmsSendManager: sends SMS messages and listens to IMS network status changes. It can be used to create GsmSmsSender and CdmaSmsSender objects and schedule either object based on the radio access technology RAT to send SMS messages.
• SmsReceiveManager: receives SMS messages and listens to new SMS messages from the RIL Adapter layer. It can be used to create GsmSmsReceiveHandler and CdmaSmsReceiveHandler objects as well as the SmsWapPushHandler and SmsCellBroadcastHandler objects.
• MmsPduProcessor: encodes and decodes MMS PDUs.
• ImsSmsClient: sends IMS SMS messages, and sets and obtains IMS SMS configuration information.

Directory Structure

/base/telephony/sms_mms
├─ common                       # Common code
├─ figures                      # Figures of readme files
├─ frameworks                   # Frameworks
│  ├─ js                        # JS code
│  └─ native                    # Native code
├─ interfaces                   # APIs
│  ├─ innerkits                 # Internal APIs
│  │ └─  ims                    # IMS SMS service APIs
│  └─ kits                      # External APIs (such as JS APIs)
├─ sa_profile                   # SA profile
├─ services                     # IMS service code (for SMS and MMS)
│  ├─ ims_service_interaction   # IMS service interaction (for SMS and MMS)
│  ├─ include                   # Header files
│  ├─ cdma                      # CDMA-specific source files
│  └─ gsm                       # GSM-specific source files
├─ test                         # Unit test code
│  ├─ fuzztest                  # Fuzzy test
│  ├─ gtest                     # Automated test
│  └─ unittest                  # Unit test
└─ utils                        # Utilities

Constraints

• Programming language: JavaScript
• In terms of software, this module needs to work with the telephony core service core\_service and depends on the glib.
• In terms of hardware, the accommodating device must be equipped with a modem and a SIM card capable of independent cellular communication.

Available APIs

Table 1 External APIs provided by the SMS and MMS module

API	Description	Required Permission
function sendMessage(options: SendMessageOptions): void;	Sends SMS messages, including long messages, common messages, and data messages.	SystemPermission.SEND_MESSAGES
function createMessage(pdu: Array<number>, specification: string, callback: AsyncCallback<ShortMessage>): void;	Creates and parses ShortMessage objects based on PDUs.	None

Table 2 Parameter description of SendMessageOptions

Parameter	Type	Description	Mandatory
slotId	number	SIM card slot ID	Yes
destinationHost	string	Phone number of the recipient	Yes
serviceCenter	string	SMC address	No
content	content | Array<number>	SMS content	Yes
destinationPort	number	Port number for receiving messages	Yes (for sending of data messages)
sendCallback	AsyncCallback<ISendShortMessageCallback>	Callback of the sending result	Yes
deliveryCallback	AsyncCallback<IDeliveryShortMessageCallback>	Callback of the delivery report	Yes

Table 3 Description of ISendShortMessageCallback types

Parameter	Type	Description
result	SendSmsResult	Sending result
url	string	URL
isLastPart	boolean	Whether the SMS message is the last one

Table 4 Description of SendSmsResult enum values

Name	Value	Description
SEND_SMS_SUCCESS	0	Sending succeeded.
SEND_SMS_FAILURE_UNKNOWN	1	Sending failed due to an unknown reason.
SEND_SMS_FAILURE_RADIO_OFF	2	Sending failed due to modem shutdown.
SEND_SMS_FAILURE_SERVICE_UNAVAILABLE	3	Sending failed due to unavailable network.

Table 5 Description of IDeliveryShortMessageCallback types

Parameter	Type	Description
pdu	Array<number>	PDU array

Table 6 Parameters of the createMessage API

Parameter	Type	Description
pdu	Array<number>	PDU array
specification	string	Protocol type (3GPP or 3GPP2)

Usage Guidelines

Sending SMS Messages

The function of sending a common SMS message is used as an example. The process is as follows:

1. Construct a SendMessageOptions object with required parameters. If the sending result or delivery report is expected, pass the sendCallback or deliveryCallback object.

2. Call the sendMessage API in callback or Promise mode.

3. Obtain the sending result. The sendMessage API works in asynchronous mode. The sending result is returned through the callback.

   import sms from "@ohos.telephony.sms";
   
   let msg: SendMessageOptions = {
     slotId: 1,
     destinationHost: '12312312312',
     content: 'This is an SMS message',
     sendCallback: (err, data) => {
       if (err) {
       // If the API call failed, err is not empty.
         console.error(`failed to send message because ${err.message}`);
         return;
       }
     // If the API call succeeded, err is empty.
       console.log(`success to send message: ${data.result}`);
     }
   }
   
   // Call the sendMessage API.
   sms.sendMessage(msg);
   

Creating a ShortMessage Object

The function of creating a ShortMessage object with a 3GPP PDU is used as an example. The process is as follows:

1. Construct the PDU of the SMS message, with the protocol type set to 3GPP or 3GPP2.

2. Call the createMessage API in callback or Promise mode.

3. The createMessage API works in asynchronous mode. After the API is called successfully, parse the ShortMessage object to obtain the SMS message content.

   import sms from "@ohos.telephony.sms";
   
   let pdu = [80, 80, 80]; // The array indicates the PDU of the SMS message other than a real SMS message.
   let specification = "3gpp";
   
   // Call the API in callback mode.
   sms.createMessage(pdu, specification, (err, value) => {
     if (err) {
       // If the API call failed, err is not empty.
       console.error(`failed to createMessage because ${err.message}`);
       return;
     }
     // If the API call succeeded, err is empty.
     console.log(`success to createMessage: ${value}`);
   });
   
   // Call the API in Promise mode.
   let promise = sms.createMessage(pdu, specification);
   promise.then((value) => {
     // The API call succeeded.
     console.log(`success to createMessage: ${value}`);
   }).catch((err) => {
     // The API call failed.
     console.error(`failed to createMessage because ${err.message}`);
   });
   

Repositories Involved

Telephony

telephony_sms_mms

telephony_core_service