le_smsInbox1_interface.h

Go to the documentation of this file.
1 
2 
3 /*
4  * ====================== WARNING ======================
5  *
6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
7  * DO NOT MODIFY IN ANY WAY.
8  *
9  * ====================== WARNING ======================
10  */
11 
12 /**
13  * @page c_smsInbox SMS Inbox
14  *
15  * @ref le_smsInbox1_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * 3rd-party customer applications need to access to SMS messages at anytime without worrying how
20  * the resources are managed.
21  *
22  * Legato provides an SMS Inbox service to allow apps to receive SMS messages through their own,
23  * private message box, without:
24  * - having to manage SIM or modem memory;
25  * - conflicting with other applications that also receive SMS messages;
26  * - missing messages while being updated or restarted.
27  *
28  *
29  * The SMS Inbox Service handles the resource arbitration for the user app: the message
30  * reception is always guaranteed, for example the user app doesn't have to worried about freeing
31  * space in the SIM (or device's storage area) when it is full.
32  *
33  * In fact, at device's startup or when a SIM is inserted, the SIM content is copied into the "Inbox
34  * Message Storage" folder allocated in the root file system of the device. Then, the process frees
35  * automatically the SIM content.
36  * Moreover, every new received SMS message is automatically copied into the "Inbox
37  * Message Storage" folder and deleted from the SIM.
38  * This mechanism keeps the SIM always empty in order to guarantee the reception of SMS messages.
39  *
40  * This process is the same when the SMS message storage is the device's storage area (ME - Mobile
41  * Equipment).
42  *
43  * The message box is a persistent storage area. All files are saved into the file system in the
44  * directory /mnt/flash/smsInbox.
45  *
46  * The creation of SMS inboxes is done based on the message box configuration settings
47  * (cf. @subpage le_smsInbox_configdb section). This way, the message box contents will be kept up
48  * to date automatically by the SMS Inbox Service, even when the user app is slow to start, is
49  * stopped while it is being updated, or is being restarted to recover from a fault.
50  *
51  * A message box works as a circular buffer, when the message box is filled, the older messages
52  * are deleted to free space for new messages. But, the application can also explicitly delete
53  * messages if it doesn't need them anymore.
54  *
55  * @section le_smsInbox_binding IPC interfaces binding
56  *
57  * All the functions of this API are provided by the @b smsInboxService application service.
58  *
59  * Here's a code sample binding to SMS Inbox services:
60  * @verbatim
61  bindings:
62  {
63  clientExe.clientComponent.le_smsInbox1 -> smsInboxService.le_smsInbox1
64  }
65  @endverbatim
66  *
67  * @note By default, smsInboxService starts manually. To start it automatically, the user can remove
68  * the option from the smsInboxService.adef file.
69  *
70  * A second message box (named le_smsInbox2) can be used by another application. These 2 message
71  * boxes are used independently. All functions of this second message box are prefixed by
72  * le_smsInbox2 (instead of le_msmInbox1).
73  * The user can implement other message boxes based on le_smsInbox1 and le_smsInbox2 model.
74  *
75  * @section le_smsInbox_init Initialise a message box
76  * Use the API le_smsInbox1_Open() to open a message box for access.
77  *
78  * @section le_smsInbox_receiving Receiving a message
79  * To receive messages, register a handler function to obtain incoming
80  * messages. Use le_smsInbox1_AddRxMessageHandler() to register that handler.
81  *
82  * The handler must satisfy the following prototype:
83  * @code
84  * typedef void (*le_smsInbox1_RxMessageHandlerFunc_t)
85  * (
86  * uint32_t msgId,
87  * void* contextPtr
88  * )
89  * @endcode
90  *
91  * If a succession of messages is received, a new Message reference is created for each, and
92  * the handler is called for each new message.
93  *
94  * Uninstall the handler function by calling le_smsInbox1_RemoveRxMessageHandler().
95  *
96  * @note le_smsInbox1_RemoveRxMessageHandler() function does not delete the Message Object.
97  * The caller has to delete it with le_smsInbox1_DeleteMsg().
98  *
99  * Use the following APIs to retrieve message information and data from the message object:
100  * - le_smsInbox1_GetImsi() - get the IMSI of the message receiver SIM if it applies.
101  * - le_smsInbox1_GetFormat() - determine if it is a binary or a text message.
102  * - le_smsInbox1_GetSenderTel() - get the sender's Telephone number.
103  * - le_smsInbox1_GetTimeStamp() - get the timestamp sets by the Service Center.
104  * - le_smsInbox1_GetMsgLen() - get the message content length.
105  * - le_smsInbox1_GetText() - get the message text.
106  * - le_smsInbox1_GetBinary() - get the message binary content.
107  * - le_smsInbox1_GetPdu() - get the PDU message content.
108  *
109  * @note For incoming SMS Inbox, format returned by le_smsInbox1_GetFormat() is never
110  * LE_SMSINBOX1_FORMAT_PDU.
111  *
112  * @section le_smsInbox_listing Getting received messages
113  *
114  * Call le_smsInbox1_GetFirst() to get the first message from the inbox folder, and then call
115  * le_smsInbox1_GetNext() to get the next message.
116  *
117  * Call le_smsInbox1_IsUnread() to know whether the message has been read or not. The message is
118  * marked as "read" when one of those APIs is called: le_smsInbox1_GetImsi(),
119  * le_smsInbox1_GetFormat(), le_smsInbox1_GetSenderTel(), le_smsInbox1_GetTimeStamp(),
120  * le_smsInbox1_GetMsgLen(), le_smsInbox1_GetText(), le_smsInbox1_GetBinary(), le_smsInbox1_GetPdu().
121  *
122  * To finish, you can also modify the received status of a message with le_smsInbox1_MarkRead() and
123  * le_smsInbox1_MarkUnread().
124  *
125  * @note The message status is tied to the client app.
126  *
127  * @section le_smsInbox1_deleting Deleting a message
128  *
129  * le_smsInbox1_DeleteMsg() deletes the message from the folder. Message is identified with
130  * le_smsInbox1_MsgRef_t object. The function returns an error if the message is not found.
131  *
132  * @section le_smsInbox_end Close a message box
133  * Use the API le_smsInbox1_Close() to close a message box (the message box is still exist and can be
134  * re-opened and retrieve later all the messages).
135  *
136  * @section le_smsInbox_configdb Configuration tree
137  *
138  * @section le_smsInbox_MaxMessage() Messagebox Database Configuration
139  *
140  * Use le_smsInbox1_SetMaxMessages() to set the maximum number of messages for message box.
141  * Use le_smsInbox1_GetMaxMessages() to get the maximum number of messages for message box.
142  *
143  * @copydoc le_smsInbox_configdbPage_Hide
144  *
145  * <HR>
146  *
147  * Copyright (C) Sierra Wireless Inc.
148  */
149 /**
150  * @interface le_smsInbox_configdbPage_Hide
151  *
152  * The configuration database for the SMS Inbox Service is stored in the @c smsInboxService config
153  * tree:
154  * @verbatim
155  smsInboxService:/
156  smsInbox/
157  apps/
158  appA<uint> = <# of messages>
159  appB<uint> = <# of messages>
160  @endverbatim
161  *
162  * Each app have its own inbox, containing its own list of messages. The maximum number of
163  * messages is specified for each inbox. If the message box is not configured, a default number
164  * of 10 messages is applied (only for message boxes configured in le_smsInbox_mboxName[]
165  * area).
166  *
167  * The application name is given by the API name provided into the Components.cdef, both must be the
168  * same.
169  *
170  * @todo: Give an indication of memory consumption for 1 message, including the file system overhead
171  * (inode, directory entry, etc...).
172  *
173  *
174  */
175 /**
176  * @file le_smsInbox1_interface.h
177  *
178  * Legato @ref c_smsInbox include file.
179  *
180  * Copyright (C) Sierra Wireless Inc.
181  */
182 
183 #ifndef LE_SMSINBOX1_INTERFACE_H_INCLUDE_GUARD
184 #define LE_SMSINBOX1_INTERFACE_H_INCLUDE_GUARD
185 
186 
187 #include "legato.h"
188 
189 // Interface specific includes
190 #include "le_mdmDefs_interface.h"
191 #include "le_sim_interface.h"
192 #include "le_sms_interface.h"
193 
194 // Internal includes for this interface
195 #include "le_smsInbox1_common.h"
196 //--------------------------------------------------------------------------------------------------
197 /**
198  * Type for handler called when a server disconnects.
199  */
200 //--------------------------------------------------------------------------------------------------
201 typedef void (*le_smsInbox1_DisconnectHandler_t)(void *);
202 
203 //--------------------------------------------------------------------------------------------------
204 /**
205  *
206  * Connect the current client thread to the service providing this API. Block until the service is
207  * available.
208  *
209  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
210  * called before any other functions in this API. Normally, ConnectService is automatically called
211  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
212  *
213  * This function is created automatically.
214  */
215 //--------------------------------------------------------------------------------------------------
217 (
218  void
219 );
220 
221 //--------------------------------------------------------------------------------------------------
222 /**
223  *
224  * Try to connect the current client thread to the service providing this API. Return with an error
225  * if the service is not available.
226  *
227  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
228  * called before any other functions in this API. Normally, ConnectService is automatically called
229  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
230  *
231  * This function is created automatically.
232  *
233  * @return
234  * - LE_OK if the client connected successfully to the service.
235  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
236  * bound.
237  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
238  * - LE_COMM_ERROR if the Service Directory cannot be reached.
239  */
240 //--------------------------------------------------------------------------------------------------
242 (
243  void
244 );
245 
246 //--------------------------------------------------------------------------------------------------
247 /**
248  * Set handler called when server disconnection is detected.
249  *
250  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
251  * to continue without exiting, it should call longjmp() from inside the handler.
252  */
253 //--------------------------------------------------------------------------------------------------
255 (
256  le_smsInbox1_DisconnectHandler_t disconnectHandler,
257  void *contextPtr
258 );
259 
260 //--------------------------------------------------------------------------------------------------
261 /**
262  *
263  * Disconnect the current client thread from the service providing this API.
264  *
265  * Normally, this function doesn't need to be called. After this function is called, there's no
266  * longer a connection to the service, and the functions in this API can't be used. For details, see
267  * @ref apiFilesC_client.
268  *
269  * This function is created automatically.
270  */
271 //--------------------------------------------------------------------------------------------------
273 (
274  void
275 );
276 
277 
278 //--------------------------------------------------------------------------------------------------
279 /**
280  * Reference type for referring to open message box sessions.
281  */
282 //--------------------------------------------------------------------------------------------------
283 
284 
285 //--------------------------------------------------------------------------------------------------
286 /**
287  * Handler for New Message.
288  *
289  */
290 //--------------------------------------------------------------------------------------------------
291 
292 
293 //--------------------------------------------------------------------------------------------------
294 /**
295  * Reference type used by Add/Remove functions for EVENT 'le_smsInbox1_RxMessage'
296  */
297 //--------------------------------------------------------------------------------------------------
298 
299 
300 //--------------------------------------------------------------------------------------------------
301 /**
302  * Open a message box.
303  *
304  * @return
305  * Reference on the opened message box session
306  */
307 //--------------------------------------------------------------------------------------------------
308 le_smsInbox1_SessionRef_t le_smsInbox1_Open
309 (
310  void
311 );
312 
313 //--------------------------------------------------------------------------------------------------
314 /**
315  * Close a previously open message box.
316  *
317  */
318 //--------------------------------------------------------------------------------------------------
320 (
321  le_smsInbox1_SessionRef_t sessionRef
322  ///< [IN] Mailbox session reference.
323 );
324 
325 //--------------------------------------------------------------------------------------------------
326 /**
327  * Add handler function for EVENT 'le_smsInbox1_RxMessage'
328  *
329  * This event provides information on new received messages.
330  *
331  */
332 //--------------------------------------------------------------------------------------------------
333 le_smsInbox1_RxMessageHandlerRef_t le_smsInbox1_AddRxMessageHandler
334 (
335  le_smsInbox1_RxMessageHandlerFunc_t handlerPtr,
336  ///< [IN]
337  void* contextPtr
338  ///< [IN]
339 );
340 
341 //--------------------------------------------------------------------------------------------------
342 /**
343  * Remove handler function for EVENT 'le_smsInbox1_RxMessage'
344  */
345 //--------------------------------------------------------------------------------------------------
347 (
348  le_smsInbox1_RxMessageHandlerRef_t handlerRef
349  ///< [IN]
350 );
351 
352 //--------------------------------------------------------------------------------------------------
353 /**
354  * Delete a Message.
355  *
356  * @note It is valid to delete a non-existent message.
357  */
358 //--------------------------------------------------------------------------------------------------
360 (
361  uint32_t msgId
362  ///< [IN] Message identifier.
363 );
364 
365 //--------------------------------------------------------------------------------------------------
366 /**
367  * Retrieves the IMSI of the message receiver SIM if it applies.
368  *
369  * @return
370  * - LE_NOT_FOUND The message item is not tied to a SIM card, the imsi string is empty.
371  * - LE_OVERFLOW The imsiPtr buffer was too small for the IMSI.
372  * - LE_BAD_PARAMETER The message reference is invalid.
373  * - LE_FAULT The function failed.
374  * - LE_OK The function succeeded.
375  *
376  */
377 //--------------------------------------------------------------------------------------------------
379 (
380  uint32_t msgId,
381  ///< [IN] Message identifier.
382  char* imsi,
383  ///< [OUT] IMSI.
384  size_t imsiSize
385  ///< [IN]
386 );
387 
388 //--------------------------------------------------------------------------------------------------
389 /**
390  * Get the message format (text, binary or PDU).
391  *
392  * @return
393  * - Message format.
394  * - FORMAT_UNKNOWN when the message format cannot be identified or the message reference is
395  * invalid.
396  * @note For incoming SMS Inbox, format returned by le_smsInbox1_GetFormat() is never
397  * LE_SMSINBOX1_FORMAT_PDU.
398  */
399 //--------------------------------------------------------------------------------------------------
400 le_sms_Format_t le_smsInbox1_GetFormat
401 (
402  uint32_t msgId
403  ///< [IN] Message identifier.
404 );
405 
406 //--------------------------------------------------------------------------------------------------
407 /**
408  * Get the Sender Identifier.
409  *
410  * @return
411  * - LE_BAD_PARAMETER The message reference is invalid.
412  * - LE_OVERFLOW Identifier length exceed the maximum length.
413  * - LE_OK Function succeeded.
414  */
415 //--------------------------------------------------------------------------------------------------
417 (
418  uint32_t msgId,
419  ///< [IN] Message identifier.
420  char* tel,
421  ///< [OUT] Identifier string.
422  size_t telSize
423  ///< [IN]
424 );
425 
426 //--------------------------------------------------------------------------------------------------
427 /**
428  * Get the Message Time Stamp string (it does not apply for PDU message).
429  *
430  * @return
431  * - LE_BAD_PARAMETER The message reference is invalid.
432  * - LE_NOT_FOUND The message is a PDU message.
433  * - LE_OVERFLOW Timestamp number length exceed the maximum length.
434  * - LE_OK Function succeeded.
435  */
436 //--------------------------------------------------------------------------------------------------
438 (
439  uint32_t msgId,
440  ///< [IN] Message identifier.
441  char* timestamp,
442  ///< [OUT] Message time stamp (for text or binary
443  ///< messages). String format:
444  ///< "yy/MM/dd,hh:mm:ss+/-zz"
445  ///< (Year/Month/Day,Hour:Min:Seconds+/-TimeZone)
446  size_t timestampSize
447  ///< [IN]
448 );
449 
450 //--------------------------------------------------------------------------------------------------
451 /**
452  * Get the message Length value.
453  *
454  * @return Number of characters for text messages, or the length of the data in bytes for raw
455  * binary and PDU messages.
456  */
457 //--------------------------------------------------------------------------------------------------
459 (
460  uint32_t msgId
461  ///< [IN] Message identifier.
462 );
463 
464 //--------------------------------------------------------------------------------------------------
465 /**
466  * Get the text Message.
467  *
468  *
469  * @return
470  * - LE_BAD_PARAMETER The message reference is invalid.
471  * - LE_FORMAT_ERROR Message is not in text format.
472  * - LE_OVERFLOW Message length exceed the maximum length.
473  * - LE_OK Function succeeded.
474  */
475 //--------------------------------------------------------------------------------------------------
477 (
478  uint32_t msgId,
479  ///< [IN] Message identifier.
480  char* text,
481  ///< [OUT] Message text.
482  size_t textSize
483  ///< [IN]
484 );
485 
486 //--------------------------------------------------------------------------------------------------
487 /**
488  * Get the binary Message.
489  *
490  *
491  * @return
492  * - LE_BAD_PARAMETER The message reference is invalid.
493  * - LE_FORMAT_ERROR Message is not in binary format.
494  * - LE_OVERFLOW Message length exceed the maximum length.
495  * - LE_OK Function succeeded.
496  */
497 //--------------------------------------------------------------------------------------------------
499 (
500  uint32_t msgId,
501  ///< [IN] Message identifier.
502  uint8_t* binPtr,
503  ///< [OUT] Binary message.
504  size_t* binSizePtr
505  ///< [INOUT]
506 );
507 
508 //--------------------------------------------------------------------------------------------------
509 /**
510  * Get the PDU message.
511  *
512  * Output parameters are updated with the PDU message content and the length of the PDU message
513  * in bytes.
514  *
515  * @return
516  * - LE_BAD_PARAMETER The message reference is invalid.
517  * - LE_FORMAT_ERROR Unable to encode the message in PDU.
518  * - LE_OVERFLOW Message length exceed the maximum length.
519  * - LE_OK Function succeeded.
520  */
521 //--------------------------------------------------------------------------------------------------
523 (
524  uint32_t msgId,
525  ///< [IN] Message identifier.
526  uint8_t* pduPtr,
527  ///< [OUT] PDU message.
528  size_t* pduSizePtr
529  ///< [INOUT]
530 );
531 
532 //--------------------------------------------------------------------------------------------------
533 /**
534  * Get the first Message object reference in the inbox message.
535  *
536  * @return
537  * - 0 No message found (message box parsing is over).
538  * - Message identifier.
539  */
540 //--------------------------------------------------------------------------------------------------
541 uint32_t le_smsInbox1_GetFirst
542 (
543  le_smsInbox1_SessionRef_t sessionRef
544  ///< [IN] Mailbox session reference.
545 );
546 
547 //--------------------------------------------------------------------------------------------------
548 /**
549  * Get the next Message object reference in the inbox message.
550  *
551  * @return
552  * - 0 No message found (message box parsing is over).
553  * - Message identifier.
554  */
555 //--------------------------------------------------------------------------------------------------
556 uint32_t le_smsInbox1_GetNext
557 (
558  le_smsInbox1_SessionRef_t sessionRef
559  ///< [IN] Mailbox session reference.
560 );
561 
562 //--------------------------------------------------------------------------------------------------
563 /**
564  * allow to know whether the message has been read or not. The message status is tied to the client
565  * app.
566  *
567  * @return True if the message is unread, false otherwise.
568  *
569  * @note If the caller is passing a bad message reference into this function, it is a fatal error,
570  * the function will not return.
571  */
572 //--------------------------------------------------------------------------------------------------
574 (
575  uint32_t msgId
576  ///< [IN] Message identifier.
577 );
578 
579 //--------------------------------------------------------------------------------------------------
580 /**
581  * Mark a message as 'read'.
582  *
583  * @note If the caller is passing a bad message reference into this function, it is a fatal error,
584  * the function will not return.
585  */
586 //--------------------------------------------------------------------------------------------------
588 (
589  uint32_t msgId
590  ///< [IN] Message identifier.
591 );
592 
593 //--------------------------------------------------------------------------------------------------
594 /**
595  * Mark a message as 'unread'.
596  *
597  * @note If the caller is passing a bad message reference into this function, it is a fatal error,
598  * the function will not return.
599  */
600 //--------------------------------------------------------------------------------------------------
602 (
603  uint32_t msgId
604  ///< [IN] Message identifier.
605 );
606 
607 //--------------------------------------------------------------------------------------------------
608 /**
609  * Set the maximum number of messages for message box.
610  *
611  * @return
612  * - LE_BAD_PARAMETER The message box name is invalid.
613  * - LE_OVERFLOW Message count exceed the maximum limit.
614  * - LE_OK Function succeeded.
615  * - LE_FAULT Function failed.
616  */
617 //--------------------------------------------------------------------------------------------------
619 (
620  uint32_t maxMessageCount
621  ///< [IN] Maximum number of messages
622 );
623 
624 //--------------------------------------------------------------------------------------------------
625 /**
626  * Get the maximum number of messages for message box.
627  *
628  * @return
629  * - LE_BAD_PARAMETER The message box name is invalid.
630  * - LE_OK Function succeeded.
631  * - LE_FAULT Function failed.
632  */
633 //--------------------------------------------------------------------------------------------------
635 (
636  uint32_t* maxMessageCountPtrPtr
637  ///< [OUT] Maximum number of messages
638 );
639 
640 #endif // LE_SMSINBOX1_INTERFACE_H_INCLUDE_GUARD
le_smsInbox1_SessionRef_t le_smsInbox1_Open(void)
le_result_t le_smsInbox1_GetTimeStamp(uint32_t msgId, char *timestamp, size_t timestampSize)
void le_smsInbox1_DeleteMsg(uint32_t msgId)
void(* le_smsInbox1_DisconnectHandler_t)(void *)
Definition: le_smsInbox1_interface.h:201
le_result_t le_smsInbox1_GetImsi(uint32_t msgId, char *imsi, size_t imsiSize)
void le_smsInbox1_MarkRead(uint32_t msgId)
le_result_t le_smsInbox1_GetMaxMessages(uint32_t *maxMessageCountPtrPtr)
le_result_t
Definition: le_basics.h:45
le_result_t le_smsInbox1_SetMaxMessages(uint32_t maxMessageCount)
le_result_t le_smsInbox1_GetBinary(uint32_t msgId, uint8_t *binPtr, size_t *binSizePtr)
void le_smsInbox1_MarkUnread(uint32_t msgId)
le_result_t le_smsInbox1_GetSenderTel(uint32_t msgId, char *tel, size_t telSize)
le_sms_Format_t le_smsInbox1_GetFormat(uint32_t msgId)
le_result_t le_smsInbox1_TryConnectService(void)
size_t le_smsInbox1_GetMsgLen(uint32_t msgId)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_smsInbox1_GetText(uint32_t msgId, char *text, size_t textSize)
uint32_t le_smsInbox1_GetNext(le_smsInbox1_SessionRef_t sessionRef)
void le_smsInbox1_RemoveRxMessageHandler(le_smsInbox1_RxMessageHandlerRef_t handlerRef)
le_smsInbox1_RxMessageHandlerRef_t le_smsInbox1_AddRxMessageHandler(le_smsInbox1_RxMessageHandlerFunc_t handlerPtr, void *contextPtr)
LE_FULL_API void le_smsInbox1_SetServerDisconnectHandler(le_smsInbox1_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_smsInbox1_DisconnectService(void)
le_result_t le_smsInbox1_GetPdu(uint32_t msgId, uint8_t *pduPtr, size_t *pduSizePtr)
uint32_t le_smsInbox1_GetFirst(le_smsInbox1_SessionRef_t sessionRef)
bool le_smsInbox1_IsUnread(uint32_t msgId)
void le_smsInbox1_Close(le_smsInbox1_SessionRef_t sessionRef)
void le_smsInbox1_ConnectService(void)