SMS

API Reference

This file contains data structures and prototypes definitions for high level SMS APIs.

SMS is a common way to communicate in the M2M world.

It's an easy, fast way to send a small amount of data (e.g., sensor values for gas telemetry). Usually, the radio module requests small power resources to send or receive a message. It's often a good way to wake-up a device that was disconnected from the network or that was operating in low power mode.

IPC interfaces binding

All the functions of this API are provided by the modemService.

Here's a code sample binding to modem services: 

bindings:
{
   clientExe.clientComponent.le_sms -> modemService.le_sms
}

Creating a Message object

There are 3 kinds of supported messages: text messages, binary messages, and PDU messages.

You must create a Message object by calling le_sms_Create() before using the message APIs. It automatically allocates needed resources for the Message object, which is referenced by le_sms_MsgRef_t type.

When the Message object is no longer needed, call le_sms_Delete() to free all allocated resources associated with the object.

Deleting a Message object

To delete a Message object, call le_sms_Delete(). This frees all the resources allocated for the Message object. If several users own the Message object (e.g., several handler functions registered for SMS message reception), the Message object will be deleted only after the last user deletes the Message object.

Sending a message

To send a message, create an le_sms_MsgRef_t object by calling the le_sms_Create() function. Then, set all the needed parameters for the message:

  • Destination telephone number with le_sms_SetDestination();
  • Text content with le_sms_SetText(), the total length are set as well with this API, maximum 160 characters as only the 7-bit alphabet is supported.
  • Binary content with le_sms_SetBinary(), total length is set with this API, maximum 140 bytes.
  • PDU content with le_sms_SetPDU(), total length is set with this API, max 36 (header) + 140 (payload) bytes long.
  • UCS2 content (16-bit format) with le_sms_SetUCS2(), total length is set with this API, maximum 70 characters (140 bytes).

When the Msg object is ready, call le_sms_Send() to transmit it.

le_sms_Send() is a blocking function with a maximum timeout set to 240 seconds, it will return once the Modem has given back a positive or negative answer to the sending operation. The return of le_sms_Send() API provides definitive status of the sending operation. TP-Validity-Period(TP-VP) parameter value indicates the time period for which the short message is valid, i.e. for how long the Service Center (SC) shall guarantee its existence in the SC memory before delivery to the recipient has been carried out. The default validity period(TP-VP) is set to 7 days for MO SMS.

When a message sending has failed and returned LE_FAULT, call le_sms_GetErrorCode() to retrieve the 3GPP message error code or le_sms_Get3GPP2ErrorCode() to retrieve the 3GPP2 message error code. If LE_SMS_ERROR_3GPP_PLATFORM_SPECIFIC or LE_SMS_ERROR_3GPP2_PLATFORM_SPECIFIC values is returned, call le_sms_GetPlatformSpecificErrorCode() to retrieve the platform specific error code.

Please refer to Platform specific error codes for platform specific error code description.

Please refer to Sample code for Mobile Originated SMS message page to get an example of SMS message sending.

Sending asynchronously a message

To send an asynchronous message, le_sms_SendAsync() API can be called instead of le_sms_Send(). le_sms_SendAsync() is a non-blocking function, it queues the message to the SMS pool and returns immediatly. Then, Legato will internally attempt to send the SMS with a maximum timeout set to 240 seconds for each SMS in the pool. This function is usefull to stack a set of messages without blocking the user application. Moreover, a handler can be specified to le_sms_SendAsync() API in order to keep track of the transmission status.

The default validity period(TP-VP) is set to 7 days for MO SMS.

A text message can be sent with one simple function: le_sms_SendText(). You only have to pass the three following parameters:

  • the destination telephone number.
  • the text message, the total length are set as well with this function, maximum 160 characters as only the 7-bit alphabet is supported.
  • the callback function to get a notification indicating the sending result: LE_SMS_SENT, LE_SMS_SENDING_FAILED or LE_SMS_SENDING_TIMEOUT. The default validity period(TP-VP) is set to 7 days for MO SMS.

A PDU message can be sent using the le_sms_SendPdu() functions. The parameters to give are:

  • the PDU content, total length is set with this API, maximum 176 bytes long = 36 (header) + 140 (payload).
  • the callback function to get a notification indicating the sending result: LE_SMS_SENT, LE_SMS_SENDING_FAILED or LE_SMS_SENDING_TIMEOUT. The default validity period(TP-VP) is set to 7 days for MO SMS.

When a message sending has failed, call le_sms_GetErrorCode() to retrieve the 3GPP message error code or le_sms_Get3GPP2ErrorCode() to retrieve the 3GPP2 message error code. If LE_SMS_ERROR_3GPP_PLATFORM_SPECIFIC or LE_SMS_ERROR_3GPP2_PLATFORM_SPECIFIC values is returned, call le_sms_GetPlatformSpecificErrorCode() to retrieve the platform specific error code.

Message object is never deleted regardless of the sending result. Caller has to delete it. Message object once used for sending the message can not be reused to send another message regardless of success or failure. New object has to be created for new message.

Receiving a message

To receive SMS messages, register a handler function to obtain incoming messages. Use le_sms_AddRxMessageHandler() to register that handler.

The handler must satisfy the following prototype: typedef void (*le_sms_RxMessageHandlerFunc_t)(le_sms_MsgRef_t msg).

When a new incoming message is received, a Message object is automatically created and the handler is called. This Message object is Read-Only, any calls of a le_sms_SetXXX API will return a LE_NOT_PERMITTED error.

Use the following APIs to retrieve message information and data from the Message object:

Note
- If two (or more) registered handler functions exist, they are all called and get a different message object reference.
- For incoming SMS, if the returned format is LE_SMS_FORMAT_PDU, the PDU length can be retrieved by calling le_sms_GetPDULen() and the content can be read by le_sms_GetPDU().

If a succession of messages is received, a new Message object is created for each, and the handler is called for each new message.

Uninstall the handler function by calling le_sms_RemoveRxMessageHandler().

Note
le_sms_RemoveRxMessageHandler() API does not delete the Message Object. The caller has to delete it.

Please refer to Sample code for Mobile Terminated SMS message page to get an example of SMS message reception handling.

Receiving a full SMS storage indication

To receive a SMS full storage status, the application has to register a handler function. Use le_sms_AddFullStorageEventHandler() to register that handler.

The handler must satisfy the following prototype: typedef void (*le_sms_FullStorageEventFunc_t)(le_sms_Storage_t storage).

Uninstall the handler function by calling le_sms_RemoveFullStorageEventHandler().

Please refer to Sample code for Mobile Terminated SMS message page to get an example of SMS storage indication handling.

Listing messages recorded in storage area

Call le_sms_CreateRxMsgList() to create a List object that lists the received messages present in the storage area, which is referenced by le_sms_MsgListRef_t type.

If messages are not present, the le_sms_CreateRxMsgList() returns NULL.

Once the list is available, call le_sms_GetFirst() to get the first message from the list, and then call le_sms_GetNext() API to get the next message.

Call le_sms_DeleteList() to free all allocated resources associated with the List object.

Call le_sms_GetStatus() to read the status of a message (Received Read, Received Unread).

To finish, you can also modify the received status of a message with le_sms_MarkRead() and le_sms_MarkUnread().

Deleting a message from the storage area

le_sms_DeleteFromStorage() deletes the message from the storage area. Message is identified with le_sms_MsgRef_t object. The API returns an error if the deletion cannot be performed or if it is a broadcast or a non stored message.

Note
If several users own the Message object on new reception (e.g., several handler functions registered for SMS message reception), the Message will be deleted from the storage area only after the last user deletes the Message object reference (not necessary from storage). API returns always LE_OK in this case.
If one client creates a list and deletes all sms from storage, other clients won’t see sms stored If they have not created a sms list too. Sms List creation locks and delays sms deletion from storage until all references have been deleted.

SMS Cell Broadcast

The Cell Broadcast service permits a number of unacknowledged general messages to be broadcast to all receivers within a particular region. Cell Broadcast messages are broadcast to defined geographical areas known as cell broadcast areas. These areas may comprise of one or more cells, or may comprise the entire PLMN.

GSM or UMTS SMS cell broadcast service can be activated or deactivated with le_sms_ActivateCellBroadcast() and le_sms_DeactivateCellBroadcast() APIs.

CDMA cell broadcast service can be activated or deactivated with le_sms_ActivateCdmaCellBroadcast() and le_sms_DeactivateCdmaCellBroadcast() APIs.

Cell broadcast message receptions are notify by the SMS handler like a SMS message reception, but there are neither stored in SIM nor in the modem. So le_sms_DeleteFromStorage() can't be used but the message reference shall be delete with le_sms_Delete().

A sample code that implements a function for SMS Cell Broadcast reception can be found in smsCBTest.c file (please refer to Sample code for SMS Cell Broadcast reception page).

Serial Number

Cell Broadcast Serial Number parameter is a 16-bit integer which identifies a particular CBS message from the source and type indicated by the Message Identifier and is altered every time the CBS message with a given Message Identifier is changed.

The two bytes of the Serial Number field are divided into a 2-bit Geographical Scope (GS) indicator, a 10-bit Message Code and a 4-bit Update Number as shown below:

  • GS code (bit 14 and 15): The Geographical Scope (GS) indicates the geographical area over which the Message Code is unique, and the display mode.
  • Message Code (bit 4 to 13) : The Message Code differentiates between CBS messages from the same source and type (i.e. with the same Message Identifier). Message Codes are for allocation by PLMN operators. The Message Code identifies different message themes. For example, let the value for the Message Identifier be "Automotive Association" (= source), "Traffic Reports" (= type). Then "Crash on A1 J5" could be one value for the message code, "Cow on A32 J4" could be another, and "Slow vehicle on M3 J3" yet another.
  • Update Number (bit 0 to 3) : The Update Number indicates a change of the message content of the same CBS message, i.e. the CBS message with the same Message Identifier, Geographical Scope, and Message Code.

Serial Number fields meaning are defined in the 3GPP 23.041 (9.4.1.2.1 Serial Number).

Message Identifier

Message Identifier parameter identifies the source and type of the CBS message. For example, "Automotive Association" (= source), "Traffic Reports" (= type) could correspond to one value. A number of CBS messages may originate from the same source and/or be of the same type. These will be distinguished by the Serial Number.

Message identifier meaning ranges are defined in the 3GPP 23.041 (9.4.1.2.2 Message Identifier).

SMS Cell Broadcast configuration

GSM or UMTS Cell broadcast Message identifiers range can be added or removed with le_sms_AddCellBroadcastIds() and le_sms_RemoveCellBroadcastIds() APIs. All Message identifiers can be removed with le_sms_ClearCellBroadcastIds() API.

CDMA Cell broadcast Service categories can be added or removed with le_sms_AddCdmaCellBroadcastServices() and le_sms_RemoveCdmaCellBroadcastServices() APIs. All Service categories can be removed with le_sms_ClearCdmaCellBroadcastServices() API.

SMS Status Report

SMS Status Report may be sent by the SMS Center (SMSC) to inform the originating device about the final outcome of the message delivery.

SMS Status Report can be activated or deactivated for outgoing messages with le_sms_EnableStatusReport() and le_sms_DisableStatusReport(). The current activation state can be retrieved with le_sms_IsStatusReportEnabled().

The reception of a SMS Status Report is notified by the SMS handler like a SMS message reception, but the message is neither stored in SIM nor in the modem. So le_sms_DeleteFromStorage() can't be used, but the message reference shall be delete with le_sms_Delete(). Received SMS Status Reports are identified by a specific type: LE_SMS_TYPE_STATUS_REPORT.

The different elements of the SMS Status Report can be retrieved with the following APIs:

  • le_sms_GetTpMr() gives the Message Reference, defined in 3GPP TS 23.040 section 9.2.3.6.
  • le_sms_GetTpRa() gives the Recipient Address, defined in 3GPP TS 23.040 section 9.2.3.14, and the Recipient Address Type of Address, defined in 3GPP TS 24.011 section 8.2.5.2.
  • le_sms_GetTpScTs() gives the Service Centre Time Stamp, defined in 3GPP TS 23.040 section 9.2.3.11.
  • le_sms_GetTpDt() gives the Discharge Time, defined in 3GPP TS 23.040 section 9.2.3.13.
  • le_sms_GetTpSt() gives the Status, defined in 3GPP TS 23.040 section 9.2.3.15.

SMS configuration

Modem SMS Center Address can be set or get with le_sms_SetSmsCenterAddress() and le_sms_GetSmsCenterAddress() functions

Preferred SMS storage configuration

Preferred SMS storage for incoming messages can be set or get with le_sms_SetPreferredStorage() and le_sms_GetPreferredStorage() functions.

SMS statistics

The number of SMS successfully sent or received through the Legato API can be counted. This feature is activated by default. le_sms_GetCount() allows retrieving the message count for each SMS type (cf. le_sms_Type_t).

le_sms_StopCount() stops the message counting and le_sms_StartCount() restarts it. le_sms_ResetCount() can be used to reset the message counters.

Note
The activation state of this feature is persistent even after a reboot of the platform.

Sample codes

A sample code that implements a function for Mobile Originated SMS message can be found in smsMO.c file (please refer to Sample code for Mobile Originated SMS message page).

A sample code that implements a function for Mobile Terminated SMS message can be found in smsMT.c file (please refer to Sample code for Mobile Terminated SMS message page).

These two samples can be easily compiled and run into the sms app, to install and use this app:

$ make ar7
$ bin/instapp  build/ar7/bin/samples/sms.ar7 <ipaddress>

where ipaddress is the address of your target device.

Then on your target, just run: 

$ app start sms

The sample replies to the sender by the message "Message from <phone number> received". Where "phone number" is the sender's phone number.

Sample code for that application can be seen in the following pages:

Copyright (C) Sierra Wireless Inc.