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.

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
}

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.

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.

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

Configuration tree

The configuration database path for the SMS Inbox Service is:

/
    smsInbox/
        apps/
            appA<uint> = <# of messages>
            appB<uint> = <# of messages>
        users/
            root<uint> = <# of messages>

Each app/user have its own inbox, containing its own list of messages. The maximum number of messages is specified for each inbox.

The application name is given by the API name provided into the Components.cdef, both must be the same.

The configuration database path for the SMS Inbox Service is:

/
    smsInbox/
        apps/
            appA<uint> = <# of messages>
            appB<uint> = <# of messages>
        users/
            root<uint> = <# of messages>

Each app/user have its own inbox, containing its own list of messages. The maximum number of messages is specified for each inbox.

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

API Reference

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 is safe to share across apps: on deletion, if several users own the Message, the Message will be actually deleted after the last user deletes the Message object reference.

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.

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_smsInbox -> smsInboxService.le_smsInbox
}

Receiving a message

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

The handler must satisfy the following prototype:

typedef void (*le_smsInbox_RxMessageHandlerFunc_t)
(
   le_smsInbox_MsgRef_t msgRef
)

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

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

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

le_smsInbox_GetImsi() - get the IMSI of the message receiver SIM if it applies.
le_smsInbox_GetFormat() - determine if it is a binary or a text message.
le_smsInbox_GetSenderTel() - get the sender's Telephone number.
le_smsInbox_GetTimeStamp() - get the timestamp sets by the Service Center.
le_smsInbox_GetMsgLen() - get the message content length.
le_smsInbox_GetText() - get the message text.
le_smsInbox_GetBinary() - get the message binary content.
le_smsInbox_GetPdu() - get the PDU message content.

Getting received messages

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

Call le_smsInbox_IsUnread() to know whether the message has been read or not.

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

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

Deleting a message

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

Configuration tree

The configuration database path for the SMS Inbox Service is:

/
    smsInbox/
        apps/
            appA<uint> = <# of messages>
            appB<uint> = <# of messages>
        users/
            root<uint> = <# of messages>

Each app/user have its own inbox, containing its own list of messages. The maximum number of messages is specified for each inbox.

The application name is given by the API name provided into the Components.cdef, both must be the same.

The configuration database path for the SMS Inbox Service is:

/
    smsInbox/
        apps/
            appA<uint> = <# of messages>
            appB<uint> = <# of messages>
        users/
            root<uint> = <# of messages>

Each app/user have its own inbox, containing its own list of messages. The maximum number of messages is specified for each inbox.

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