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.
• A specific timeout value can be used with le_sms_SetTimeout() API.

After the Msg 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.

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.

Sending asynchronously a message.

To send an asynchronous message, le_sms_SendAsync() API can be called instead of le_sms_Send() and a specific timeout value can be used with le_sms_SetTimeout() API.

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.

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.

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.

[...]

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 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.
• le_sms_GetType() - get the message type.

Note

- If two (or more) registered handler functions exist, they are all called and get a different message object reference.

- For incoming SMS, format returned by le_sms_GetFormat is never LE_SMS_FORMAT_PDU.

- 16 bit UCS2 format is not supported.

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_BYTES];
    char   text[LE_SMS_TEXT_MAX_BYTES];

    if (le_sms_GetType(msgRef) == LE_SMS_TYPE_RX)
    {
        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

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

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().

• le_sms_GetFormat() - determine if it is a binary or a text message.
• le_sms_GetUserdataLen() - get the message content (text or binary) length.
• le_sms_GetPDULen() - get the PDU message received.
• le_sms_GetText() - get the message text.
• le_sms_GetBinary() - get the message binary content.
• le_sms_GetPDU() - get the message PDU data received length.
• le_sms_GetCellBroadcastId() - get the message identifier received (3GPP 23.41).
• le_sms_GetCellBroadcastSerialNumber() get the message Serial Number received (3GPP 23.41).

Note

- Format returned by le_sms_GetFormat is never LE_SMS_FORMAT_PDU.

- 16 bit UCS2 format is not supported

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).

[...]

static void myMsgHandler
(
    le_sms_MsgRef_t msgRef,
    void* contextPtr
)
{
    char text[LE_SMS_TEXT_MAX_BYTES];
    uin8_t binary[LE_SMS_BINARY_MAX_BYTES];
    uint16_t messageId;

    if (le_sms_GetType(msgRef) == LE_SMS_TYPE_BROADCAST_RX)
    {
        if (le_sms_GetFormat(msgRef) == LE_SMS_FORMAT_TEXT)
        {
            // Get the message text
            le_sms_GetText(msgRef, text, LE_SMS_TEXT_MAX_BYTES);
        }
        else if (le_sms_GetFormat(msgRef) == LE_SMS_FORMAT_BINARY)
        {
            // Get the message binary
            le_sms_GetBinary(msgRef, binary, LE_SMS_BINARY_MAX_BYTES);
        }

        // Get the message identifier to identify the message origin
        le_sms_GetCellBroadcastId(msgRef,&messageId);

        // Delete the message
        le_sms_Delete(msgRef);
    }
    [...]
}


[...]
// 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);

[...]

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 configuration

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

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:

• Sample code for Mobile Originated SMS message
  
• Sample code for Mobile Terminated SMS message

---

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.