The SMS service can be used to send/receive SMS messages and access messages from storage. SMS is an easy and fast way to communicate or transmit data between devices in a cellular network.

IPC interfaces binding

The functions of this API are provided by the tafSMSSvc application service.

The following example illustrates how to bind to the SMS service.

bindings:
{
    clientExe.clientComponent.taf_sms -> tafSMSSvc.taf_sms
}

Creating a message object

Before setting up and sending messages via these APIs, you need to create a message object by calling taf_sms_Create()

taf_sms_Create() – Creates a message object.

Deleting a message object

When a message object is no longer used, call taf_sms_Delete to free the resources and delete the object.

taf_sms_Delete() – Deletes the object.

Message object parameters configuration

taf_sms_SetDestination() – Sets the destination phone number.
taf_sms_SetCallback() – Sets the callback function to get the message send result.
taf_sms_SetPhoneId() – With dual SIMs in device, sets the source phone ID.

Message content and format configuration

There are 3 types of message formats can be assigned, either text messages (7-bit), binary messages (8-bit), or UCS2 messages (16-bit). You can directly encode messages in PDU format as well. Message data length is set with these APIs accordingly. For text messages, the maximum supported character length is 160 characters. For binary messages, the maximum supported length is 140 bytes. For UCS2 messages, the maximum supported characters is 70 characters.

taf_sms_SetText() – Sets the message content as alphabet text.
taf_sms_SetBinary() – Sets the message content as binary data.
taf_sms_SetUCS2() – Sets the message as UCS2 text.
taf_sms_SetPDU() – Sets the message with PDU format.

The following example illustrates creating, setting up, and deleting a message object.

taf_sms_MsgRef_t    tmpMsg;
char                text[TAF_SMS_TEXT_BYTES] = {0};
tmpMsg = taf_sms_Create();
if(tmpMsg)
{
    if(taf_sms_SetText(tmpMsg, "test set next") != LE_OK)
    {
        LE_ERROR("set text failed");
    }
    if(taf_sms_SetDestination(tmpMsg, "123456789") != LE_OK)
    {
        LE_ERROR("set destination failed");
    }
    if(taf_sms_SetPhoneId(tmpMsg, 1) != LE_OK);
    {
        LE_ERROR("set phone ID failed");
    }
    taf_sms_Delete(tmpMsg);
}
else
{
    LE_ERROR("tmpMsg is NULL");
}

Sending a message

When a message is ready, taf_sms_Send() can be called to send it. taf_sms_Send() is returned with modem feedback and with a maximum 10 second timeout.

A message object can only be used once for sending, no matter what the sending result is. Message objects need to be deleted by the caller.

Receiving messages

To receive incoming messages, register a handler function with taf_sms_AddRxMsgHandler() and follow the handler type definition: void (*taf_sms_RxMsgHandlerFunc_t)(taf_sms_MsgRef_t msg)

A message object is created automatically when an incoming message is received, the registered handler is triggered and further processes on the received message.

To remove the handler function, call taf_sms_RemoveRxMsgHandler(). Callers have to delete the message object when the message is no longer needed.

Getting content and information of the message object

taf_sms_GetUserdataLen() Gets the data length of the content.
taf_sms_GetText() – Gets the text content of the message.
taf_sms_GetUCS2() – Gets the UCS2 text of the message.
taf_sms_GetPDU() – Gets the PDU data of the message.
taf_sms_GetSendStatus() – Gets the sending status from the Tx message.
taf_sms_GetReadStatus() – Gets the read status from the Rx message.

Storage configuration

SMS service provides three types of storage to store messages: HLOS, SIM, and NONE. HLOS is set as the default and it encrypts received messages and stores them in the file system. SIM is for storing messages in SIM. NONE storage specifies that a message notification is provided, but not stored in the system.

TAF_SMS_STORAGE_HLOS
- Default storage strategy.
- Each message will be stored as an encrypted file in /data/le_fs/taf_sms/.
- In total, 255 message slots are available for storing messages.
- When HLOS storage reaches 90% capacity, the service will identify messages that are marked as 'read' and 'unlocked' status as 'recyclable' messages. The service will then delete 10 recyclable messages to free up more slots for new messages.
TAF_SMS_STORAGE_SIM
- The maximum number of messages that can be stored is based on the SIM card.
- When the storage is 100% full, clients can still get incoming message notifications and get the contents of new messages, but new messages will not be persistent after power cycle.
TAF_SMS_STORAGE_NONE
- Notify only.
- Clients get incoming message notifications and can get the content of new messages, but the messages will not be persistent after power cycle.

Preferred storage configuration is persistent in service config tree and can be accessed by the following APIs.

taf_sms_SetPreferredStorage() – Sets preferred storage.
taf_sms_GetPreferredStorage() – Gets preferred storage.

Receiving full storage indication

To receive storage indications, register a handler function with taf_sms_AddFullStorageEventHandler() and follow the handler type definition of taf_sms_FullStorageHandlerFunc_t

To remove the handler function, call taf_sms_RemoveFullStorageEventHandler().

Manipulating message in storage

taf_sms_DeleteFromStorage() – Deletes a message from its storage location.
taf_sms_MarkRead() – Marks a message status as read.
taf_sms_MarkUnread() – Marks a message status as unread.

HLOS storage provides more functions to maintain messsage configurations.

taf_sms_LockFromStorage() – Marks a message as locked and the marked message cannot be deleted.
taf_sms_UnlockFromStorage() – Marks a message as unlocked and the marked message can be deleted.

SMS center configuration

taf_sms_GetSmsCenterAddress() – Gets SMS center address.
taf_sms_SetSmsCenterAddress() – Sets SMS center address.

Cell broadcast configuration

taf_sms_ActivateCellBroadcast() – Activates cell broadcast.
taf_sms_DeactivateCellBroadcast() – Deactivates cell broadcast.
taf_sms_AddCellBroadcastIds() – Add cell broadcast message range of identifier.
taf_sms_GetSmsCenterAddress() – Remove cell broadcast range of message identifiers.

Typical application call flow

Message Sending

#0 – Create the message, the following manipulation will use the returned message reference from service.

#1 – Set the message content.

#2 – Set the receiver's phone number.

#3 – Set the message callback to get the sending result.

#4 – Send the message.

#5 – Delete the message object if it is not used anymore.

Message Receiving

#0 – Set preferred storage to one of the storage types.

#1 – Set the message receiving handler to be able to receive any messages sent to the application.

#2 – Get the new message notification with the message reference.

#3 – Get the PDU data with the specified message reference.

Message Retrieving from storage

#0 – Create the Rx message list for listing the messages stored in SIM and HLOS.

#1 – Get message reference of the first message from Rx message list.

#2 – Get the message reference of the next message from the Rx message list.

#3 – Delete the message with the specified message reference.

#4 – Delete the Rx message list after all manipulations are complete.