3rd-party customer applications need to access to SMS messages at anytime without worrying how the resources are managed.

Legato provides an SMS Inbox service to allow apps to receive SMS messages through their own, private message box, without:

having to manage SIM or modem memory;
conflicting with other applications that also receive SMS messages;
missing messages while being updated or restarted.

The SMS Inbox Service handles the resource arbitration for the user app: the message reception is always guaranteed, for example the user app doesn't have to worried about freeing space in the SIM (or device's storage area) when it is full.

In fact, at device's startup or when a SIM is inserted, the SIM content is copied into the "Inbox Message Storage" folder allocated in the root file system of the device. Then, the process frees automatically the SIM content. Moreover, every new received SMS message is automatically copied into the "Inbox Message Storage" folder and deleted from the SIM. This mechanism keeps the SIM always empty in order to guarantee the reception of SMS messages.

This process is the same when the SMS message storage is the device's storage area (ME - Mobile Equipment).

The message box is a persistent storage area. All files are saved into the file system in the directory /mnt/flash/smsInbox.

The creation of SMS inboxes is done based on the message box configuration settings (cf. Configuration tree section). This way, the message box contents will be kept up to date automatically by the SMS Inbox Service, even when the user app is slow to start, is stopped while it is being updated, or is being restarted to recover from a fault.

A message box works as a circular buffer, when the message box is filled, the older messages are deleted to free space for new messages. But, the application can also explicitly delete messages if it doesn't need them anymore.

IPC interfaces binding

All the functions of this API are provided by the smsInboxService application service.

Here's a code sample binding to SMS Inbox services:

bindings:
{
   clientExe.clientComponent.le_smsInbox1 -> smsInboxService.le_smsInbox1
}

Note: By default, smsInboxService starts manually. To start it automatically, the user can remove the option from the smsInboxService.adef file.

A second message box (named le_smsInbox2) can be used by another application. These 2 message boxes are used independently. All functions of this second message box are prefixed by le_smsInbox2 (instead of le_msmInbox1). The user can implement other message boxes based on le_smsInbox1 and le_smsInbox2 model.

Initialise a message box

Use the API le_smsInbox1_Open() to open a message box for access.

Receiving a message

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

The handler must satisfy the following prototype:

typedef void (*le_smsInbox1_RxMessageHandlerFunc_t)
(
  uint32_t msgId,
  void*    contextPtr
)

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

Uninstall the handler function by calling le_smsInbox1_RemoveRxMessageHandler().

Note: le_smsInbox1_RemoveRxMessageHandler() function does not delete the Message Object. The caller has to delete it with le_smsInbox1_DeleteMsg().

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

le_smsInbox1_GetImsi() - get the IMSI of the message receiver SIM if it applies.
le_smsInbox1_GetFormat() - determine if it is a binary or a text message.
le_smsInbox1_GetSenderTel() - get the sender's Telephone number.
le_smsInbox1_GetTimeStamp() - get the timestamp sets by the Service Center.
le_smsInbox1_GetMsgLen() - get the message content length.
le_smsInbox1_GetText() - get the message text.
le_smsInbox1_GetBinary() - get the message binary content.
le_smsInbox1_GetPdu() - get the PDU message content.

Note: For incoming SMS Inbox, format returned by le_smsInbox1_GetFormat() is never LE_SMSINBOX1_FORMAT_PDU.

Getting received messages

Call le_smsInbox1_GetFirst() to get the first message from the inbox folder, and then call le_smsInbox1_GetNext() to get the next message.

Call le_smsInbox1_IsUnread() to know whether the message has been read or not. The message is marked as "read" when one of those APIs is called: le_smsInbox1_GetImsi(), le_smsInbox1_GetFormat(), le_smsInbox1_GetSenderTel(), le_smsInbox1_GetTimeStamp(), le_smsInbox1_GetMsgLen(), le_smsInbox1_GetText(), le_smsInbox1_GetBinary(), le_smsInbox1_GetPdu().

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

Note: The message status is tied to the client app.

Deleting a message

le_smsInbox1_DeleteMsg() deletes the message from the folder. Message is identified with le_smsInbox1_MsgRef_t object. The function returns an error if the message is not found.

Close a message box

Use the API le_smsInbox1_Close() to close a message box (the message box is still exist and can be re-opened and retrieve later all the messages).