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 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_msg_Create() before using the message APIs. It automatically allocates needed resources for the Message object, which is referenced by le_sms_msg_Ref_t type.

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

Deleting a Message object

To delete a Message object, call le_sms_msg_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_msg_Ref_t object by calling the le_sms_msg_Create() function. Then, set all the needed parameters for the message:

Destination telephone number with le_sms_msg_SetDestination();
Text content with le_sms_msg_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_msg_SetBinary(), total length is set with this API, maximum 140 bytes.
PDU content with le_sms_msg_SetPDU(), total length is set with this API, max 36 (header) + 140 (payload) bytes long.

After the le_sms_msg_Ref_t object is ready, call le_sms_msg_Send().

le_sms_msg_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_msg_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_msg_Ref_t myTextMsg;

 // Create a Message Object
 myTextMsg = le_sms_msg_Create();

 // Set the telephone number
 le_sms_msg_SetDestination(myTextMsg, "+33606060708");

 // Set the message text
 le_sms_msg_SetText(myTextMsg, "Hello, this is a Legato SMS message");

 // Send the message
 le_sms_msg_Send(myTextMsg);

 // Delete the message
 le_sms_msg_Delete(myTextMsg);

Receiving a message

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

The handler must satisfy the following prototype: typedef void (*le_sms_msg_RxMessageHandlerFunc_t)(le_sms_msg_Ref_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_msg_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_msg_GetFormat() - determine if it is a PDU, a binary or a text message.
le_sms_msg_GetSenderTel() - get the sender's Telephone number.
le_sms_msg_GetTimeStamp() - get the timestamp sets by the Service Center.
le_sms_msg_GetUserdataLen() - get the message content (text or binary) length.
le_sms_msg_GetPDULen() - get the PDU message .
le_sms_msg_GetText() - get the message text.
le_sms_msg_GetBinary() - get the message binary content.
le_sms_msg_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_msg_RemoveRxMessageHandler().

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

 [...]

 // Handler function for message reception
 static void myMsgHandler(le_sms_msg_Ref_t msg)
 {
     char                tel[LE_SMS_TEL_NMBR_MAX_LEN];
     char                text[LE_SMS_TEXT_MAX_LEN];
     le_sms_msg_Format_t format;
     uint32_t len=0;

     le_sms_msg_GetFormat(msg, &format);
     if (format == LE_SMS_TEXT)
     {
         le_sms_msg_GetSenderTel(msg, tel, &len);
         le_sms_msg_GetText(msg, text, &len);

         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:

 int32_t hdlrId=-1;

 // Add an handler function to handle message reception
 hdlrId=le_sms_msg_AddRxMessageHandler(myMsgHandler);

 [...]

 // Remove Handler entry
 le_sms_msg_RemoveRxMessageHandler(hdlrId);

 [...]

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_msg_CreateRxMsgList() to create a List object that lists the received messages present in the storage area, which is referenced by le_sms_msg_ListRef_t type.

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

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

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

Call le_sms_msg_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_msg_MarkRead() and le_sms_msg_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_msg_DeleteFromStorage() deletes the message from the storage area. Message is identified with le_sms_msg_Ref_t object. The API returns an error if the message is not found in the storage area.