Click here for the API reference documentation.

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

Creating a Message object
Deleting a Message object
Sending a message
Receiving a message
Listing messages recorded in storage area
Deleting a message from the storage area
SMS configuration tree
Sample codes

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.

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.

After the le_sms_MsgRef_t object is ready, call le_sms_Send().

le_sms_Send() is a blocking function, 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.

Message object is never deleted regardless of the sending result. Caller has to delete it.

[...]
le_sms_MsgRef_t myTextMsg;
// Create a Message Object
myTextMsg = le_sms_Create();
// Set the telephone number
le_sms_SetDestination(myTextMsg, "+33606060708");
// Set the message text
le_sms_SetText(myTextMsg, "Hello, this is a Legato SMS message");
// Send the message
le_sms_Send(myTextMsg);
// Delete the message
le_sms_Delete(myTextMsg);

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:

le_sms_GetFormat() - determine if it is a PDU, a binary or a text message.
le_sms_GetSenderTel() - get the sender's Telephone number.
le_sms_GetTimeStamp() - get the timestamp sets by the Service Center.
le_sms_GetUserdataLen() - get the message content (text or binary) length.
le_sms_GetPDULen() - get the PDU message .
le_sms_GetText() - get the message text.
le_sms_GetBinary() - get the message binary content.
le_sms_GetPDU() - get the message PDU data.

Note: If two (or more) registered handler functions exist, they are all called and get the same message object reference.

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.

[...]
// Handler function for message reception
static void myMsgHandler
(
     le_sms_MsgRef_t msgRef,
     void*            contextPtr*
)
{
    char   tel[LE_SMS_TEL_NMBR_MAX_LEN];
    char   text[LE_SMS_TEXT_MAX_LEN];
    if (le_sms_GetFormat(msgRef) == LE_SMS_FORMAT_TEXT)
    {
        le_sms_GetSenderTel(msgRef, tel, sizeof(tel));
        le_sms_GetText(msgRef, text, sizeof(text));
        LE_INFO(" A new text message has been received !");
        LE_INFO(" From tel.%s, text: \"%s\"", tel, text);
    }
    else
    {
        LE_INFO(" I support only text messages !");
    }
}
[...]
// In the main function:
le_sms_RxMessageHandlerRef_t HdlrRef;
// Add an handler function to handle message reception
HdlrRef=le_sms_AddRxMessageHandler(myMsgHandler);
[...]
// Remove Handler entry
le_sms_RemoveRxMessageHandler(HdlrRef);
[...]

Listing messages recorded in storage area

Note: The default SMS message storage area is the SIM card. Change the storage setting through the SMS configuration APIs (available in a future version of API specification).

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

Note: The default SMS message storage area is the SIM card. Change this setting through the SMS configuration APIs (available in a future version of API specification).

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 message is not found in the storage area.

SMS configuration tree

The configuration database path for the SMS is:

 /
     modemServices/
         sms/
             smsc<string> = <SMS Center Address>

Where 'smsc' is the SMS Center Address.

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.