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  * @copydoc le_smsInbox_configdbPage_Hide
138  *
139  * <HR>
140  *
141  * Copyright (C) Sierra Wireless Inc.
142  */
143 /**
144  * @interface le_smsInbox_configdbPage_Hide
145  *
146  * The configuration database for the SMS Inbox Service is stored in the @c smsInboxService config
147  * tree:
148  * @verbatim
149  smsInboxService:/
150  smsInbox/
151  apps/
152  appA<uint> = <# of messages>
153  appB<uint> = <# of messages>
154  @endverbatim
155  *
156  * Each app have its own inbox, containing its own list of messages. The maximum number of
157  * messages is specified for each inbox. If the message box is not configured, a default number
158  * of 10 messages is applied (only for message boxes configured in le_smsInbox_mboxName[]
159  * area).
160  *
161  * The application name is given by the API name provided into the Components.cdef, both must be the
162  * same.
163  *
164  * @todo: Give an indication of memory consumption for 1 message, including the file system overhead
165  * (inode, directory entry, etc...).
166  *
167  *
168  */
169 /**
170  * @file le_smsInbox1_interface.h
171  *
172  * Legato @ref c_smsInbox include file.
173  *
174  * Copyright (C) Sierra Wireless Inc.
175  */
176 
177 #ifndef LE_SMSINBOX1_INTERFACE_H_INCLUDE_GUARD
178 #define LE_SMSINBOX1_INTERFACE_H_INCLUDE_GUARD
179 
180 
181 #include "legato.h"
182 
183 // Interface specific includes
184 #include "le_mdmDefs_interface.h"
185 #include "le_sim_interface.h"
186 #include "le_sms_interface.h"
187 
188 
189 //--------------------------------------------------------------------------------------------------
190 /**
191  * Type for handler called when a server disconnects.
192  */
193 //--------------------------------------------------------------------------------------------------
194 typedef void (*le_smsInbox1_DisconnectHandler_t)(void *);
195 
196 //--------------------------------------------------------------------------------------------------
197 /**
198  *
199  * Connect the current client thread to the service providing this API. Block until the service is
200  * available.
201  *
202  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
203  * called before any other functions in this API. Normally, ConnectService is automatically called
204  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
205  *
206  * This function is created automatically.
207  */
208 //--------------------------------------------------------------------------------------------------
210 (
211  void
212 );
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  *
217  * Try to connect the current client thread to the service providing this API. Return with an error
218  * if the service is not available.
219  *
220  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
221  * called before any other functions in this API. Normally, ConnectService is automatically called
222  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
223  *
224  * This function is created automatically.
225  *
226  * @return
227  * - LE_OK if the client connected successfully to the service.
228  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
229  * bound.
230  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
231  * - LE_COMM_ERROR if the Service Directory cannot be reached.
232  */
233 //--------------------------------------------------------------------------------------------------
235 (
236  void
237 );
238 
239 //--------------------------------------------------------------------------------------------------
240 /**
241  * Set handler called when server disconnection is detected.
242  *
243  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
244  * to continue without exiting, it should call longjmp() from inside the handler.
245  */
246 //--------------------------------------------------------------------------------------------------
248 (
249  le_smsInbox1_DisconnectHandler_t disconnectHandler,
250  void *contextPtr
251 );
252 
253 //--------------------------------------------------------------------------------------------------
254 /**
255  *
256  * Disconnect the current client thread from the service providing this API.
257  *
258  * Normally, this function doesn't need to be called. After this function is called, there's no
259  * longer a connection to the service, and the functions in this API can't be used. For details, see
260  * @ref apiFilesC_client.
261  *
262  * This function is created automatically.
263  */
264 //--------------------------------------------------------------------------------------------------
266 (
267  void
268 );
269 
270 
271 //--------------------------------------------------------------------------------------------------
272 /**
273  * Define unknown format
274  */
275 //--------------------------------------------------------------------------------------------------
276 #define LE_SMSINBOX1_FORMAT_UNKNOWN -1
277 
278 //--------------------------------------------------------------------------------------------------
279 /**
280  * Define the name of length of the message box name
281  */
282 //--------------------------------------------------------------------------------------------------
283 #define LE_SMSINBOX1_MAX_MBOX_NAME_LEN 12
284 
285 //--------------------------------------------------------------------------------------------------
286 /**
287  * Reference type for referring to open message box sessions.
288  */
289 //--------------------------------------------------------------------------------------------------
290 typedef struct le_smsInbox1_Session* le_smsInbox1_SessionRef_t;
291 
292 
293 //--------------------------------------------------------------------------------------------------
294 /**
295  * Reference type used by Add/Remove functions for EVENT 'le_smsInbox1_RxMessage'
296  */
297 //--------------------------------------------------------------------------------------------------
298 typedef struct le_smsInbox1_RxMessageHandler* le_smsInbox1_RxMessageHandlerRef_t;
299 
300 
301 //--------------------------------------------------------------------------------------------------
302 /**
303  * Handler for New Message.
304  *
305  */
306 //--------------------------------------------------------------------------------------------------
308 (
309  uint32_t msgId,
310  ///< Message identifier.
311  void* contextPtr
312  ///<
313 );
314 
315 //--------------------------------------------------------------------------------------------------
316 /**
317  * Open a message box.
318  *
319  * @return
320  * Reference on the opened message box session
321  */
322 //--------------------------------------------------------------------------------------------------
324 (
325  void
326 );
327 
328 //--------------------------------------------------------------------------------------------------
329 /**
330  * Close a previously open message box.
331  *
332  */
333 //--------------------------------------------------------------------------------------------------
335 (
336  le_smsInbox1_SessionRef_t sessionRef
337  ///< [IN] Mailbox session reference.
338 );
339 
340 //--------------------------------------------------------------------------------------------------
341 /**
342  * Add handler function for EVENT 'le_smsInbox1_RxMessage'
343  *
344  * This event provides information on new received messages.
345  *
346  */
347 //--------------------------------------------------------------------------------------------------
349 (
351  ///< [IN]
352  void* contextPtr
353  ///< [IN]
354 );
355 
356 //--------------------------------------------------------------------------------------------------
357 /**
358  * Remove handler function for EVENT 'le_smsInbox1_RxMessage'
359  */
360 //--------------------------------------------------------------------------------------------------
362 (
364  ///< [IN]
365 );
366 
367 //--------------------------------------------------------------------------------------------------
368 /**
369  * Delete a Message.
370  *
371  * @note It is valid to delete a non-existent message.
372  */
373 //--------------------------------------------------------------------------------------------------
375 (
376  uint32_t msgId
377  ///< [IN] Message identifier.
378 );
379 
380 //--------------------------------------------------------------------------------------------------
381 /**
382  * Retrieves the IMSI of the message receiver SIM if it applies.
383  *
384  * @return
385  * - LE_NOT_FOUND The message item is not tied to a SIM card, the imsi string is empty.
386  * - LE_OVERFLOW The imsiPtr buffer was too small for the IMSI.
387  * - LE_BAD_PARAMETER The message reference is invalid.
388  * - LE_FAULT The function failed.
389  * - LE_OK The function succeeded.
390  *
391  */
392 //--------------------------------------------------------------------------------------------------
394 (
395  uint32_t msgId,
396  ///< [IN] Message identifier.
397  char* imsi,
398  ///< [OUT] IMSI.
399  size_t imsiSize
400  ///< [IN]
401 );
402 
403 //--------------------------------------------------------------------------------------------------
404 /**
405  * Get the message format (text, binary or PDU).
406  *
407  * @return
408  * - Message format.
409  * - FORMAT_UNKNOWN when the message format cannot be identified or the message reference is
410  * invalid.
411  * @note For incoming SMS Inbox, format returned by le_smsInbox1_GetFormat() is never
412  * LE_SMSINBOX1_FORMAT_PDU.
413  */
414 //--------------------------------------------------------------------------------------------------
416 (
417  uint32_t msgId
418  ///< [IN] Message identifier.
419 );
420 
421 //--------------------------------------------------------------------------------------------------
422 /**
423  * Get the Sender Identifier.
424  *
425  * @return
426  * - LE_BAD_PARAMETER The message reference is invalid.
427  * - LE_OVERFLOW Identifier length exceed the maximum length.
428  * - LE_OK Function succeeded.
429  */
430 //--------------------------------------------------------------------------------------------------
432 (
433  uint32_t msgId,
434  ///< [IN] Message identifier.
435  char* tel,
436  ///< [OUT] Identifier string.
437  size_t telSize
438  ///< [IN]
439 );
440 
441 //--------------------------------------------------------------------------------------------------
442 /**
443  * Get the Message Time Stamp string (it does not apply for PDU message).
444  *
445  * @return
446  * - LE_BAD_PARAMETER The message reference is invalid.
447  * - LE_NOT_FOUND The message is a PDU message.
448  * - LE_OVERFLOW Timestamp number length exceed the maximum length.
449  * - LE_OK Function succeeded.
450  */
451 //--------------------------------------------------------------------------------------------------
453 (
454  uint32_t msgId,
455  ///< [IN] Message identifier.
456  char* timestamp,
457  ///< [OUT] Message time stamp (for text or binary
458  ///< messages). String format:
459  ///< "yy/MM/dd,hh:mm:ss+/-zz"
460  ///< (Year/Month/Day,Hour:Min:Seconds+/-TimeZone)
461  size_t timestampSize
462  ///< [IN]
463 );
464 
465 //--------------------------------------------------------------------------------------------------
466 /**
467  * Get the message Length value.
468  *
469  * @return Number of characters for text messages, or the length of the data in bytes for raw
470  * binary and PDU messages.
471  */
472 //--------------------------------------------------------------------------------------------------
474 (
475  uint32_t msgId
476  ///< [IN] Message identifier.
477 );
478 
479 //--------------------------------------------------------------------------------------------------
480 /**
481  * Get the text Message.
482  *
483  *
484  * @return
485  * - LE_BAD_PARAMETER The message reference is invalid.
486  * - LE_FORMAT_ERROR Message is not in text format.
487  * - LE_OVERFLOW Message length exceed the maximum length.
488  * - LE_OK Function succeeded.
489  */
490 //--------------------------------------------------------------------------------------------------
492 (
493  uint32_t msgId,
494  ///< [IN] Message identifier.
495  char* text,
496  ///< [OUT] Message text.
497  size_t textSize
498  ///< [IN]
499 );
500 
501 //--------------------------------------------------------------------------------------------------
502 /**
503  * Get the binary Message.
504  *
505  *
506  * @return
507  * - LE_BAD_PARAMETER The message reference is invalid.
508  * - LE_FORMAT_ERROR Message is not in binary format.
509  * - LE_OVERFLOW Message length exceed the maximum length.
510  * - LE_OK Function succeeded.
511  */
512 //--------------------------------------------------------------------------------------------------
514 (
515  uint32_t msgId,
516  ///< [IN] Message identifier.
517  uint8_t* binPtr,
518  ///< [OUT] Binary message.
519  size_t* binSizePtr
520  ///< [INOUT]
521 );
522 
523 //--------------------------------------------------------------------------------------------------
524 /**
525  * Get the PDU message.
526  *
527  * Output parameters are updated with the PDU message content and the length of the PDU message
528  * in bytes.
529  *
530  * @return
531  * - LE_BAD_PARAMETER The message reference is invalid.
532  * - LE_FORMAT_ERROR Unable to encode the message in PDU.
533  * - LE_OVERFLOW Message length exceed the maximum length.
534  * - LE_OK Function succeeded.
535  */
536 //--------------------------------------------------------------------------------------------------
538 (
539  uint32_t msgId,
540  ///< [IN] Message identifier.
541  uint8_t* pduPtr,
542  ///< [OUT] PDU message.
543  size_t* pduSizePtr
544  ///< [INOUT]
545 );
546 
547 //--------------------------------------------------------------------------------------------------
548 /**
549  * Get the first 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_GetFirst
557 (
558  le_smsInbox1_SessionRef_t sessionRef
559  ///< [IN] Mailbox session reference.
560 );
561 
562 //--------------------------------------------------------------------------------------------------
563 /**
564  * Get the next Message object reference in the inbox message.
565  *
566  * @return
567  * - 0 No message found (message box parsing is over).
568  * - Message identifier.
569  */
570 //--------------------------------------------------------------------------------------------------
571 uint32_t le_smsInbox1_GetNext
572 (
573  le_smsInbox1_SessionRef_t sessionRef
574  ///< [IN] Mailbox session reference.
575 );
576 
577 //--------------------------------------------------------------------------------------------------
578 /**
579  * allow to know whether the message has been read or not. The message status is tied to the client
580  * app.
581  *
582  * @return True if the message is unread, false otherwise.
583  *
584  * @note If the caller is passing a bad message reference into this function, it is a fatal error,
585  * the function will not return.
586  */
587 //--------------------------------------------------------------------------------------------------
589 (
590  uint32_t msgId
591  ///< [IN] Message identifier.
592 );
593 
594 //--------------------------------------------------------------------------------------------------
595 /**
596  * Mark a message as 'read'.
597  *
598  * @note If the caller is passing a bad message reference into this function, it is a fatal error,
599  * the function will not return.
600  */
601 //--------------------------------------------------------------------------------------------------
603 (
604  uint32_t msgId
605  ///< [IN] Message identifier.
606 );
607 
608 //--------------------------------------------------------------------------------------------------
609 /**
610  * Mark a message as 'unread'.
611  *
612  * @note If the caller is passing a bad message reference into this function, it is a fatal error,
613  * the function will not return.
614  */
615 //--------------------------------------------------------------------------------------------------
617 (
618  uint32_t msgId
619  ///< [IN] Message identifier.
620 );
621 
622 #endif // LE_SMSINBOX1_INTERFACE_H_INCLUDE_GUARD
le_result_t le_smsInbox1_GetPdu(uint32_t msgId, uint8_t *pduPtr, size_t *pduSizePtr)
le_result_t le_smsInbox1_GetText(uint32_t msgId, char *text, size_t textSize)
void le_smsInbox1_RemoveRxMessageHandler(le_smsInbox1_RxMessageHandlerRef_t handlerRef)
uint32_t le_smsInbox1_GetFirst(le_smsInbox1_SessionRef_t sessionRef)
le_result_t
Definition: le_basics.h:35
le_smsInbox1_SessionRef_t le_smsInbox1_Open(void)
size_t le_smsInbox1_GetMsgLen(uint32_t msgId)
uint32_t le_smsInbox1_GetNext(le_smsInbox1_SessionRef_t sessionRef)
void le_smsInbox1_DeleteMsg(uint32_t msgId)
le_smsInbox1_RxMessageHandlerRef_t le_smsInbox1_AddRxMessageHandler(le_smsInbox1_RxMessageHandlerFunc_t handlerPtr, void *contextPtr)
le_sms_Format_t
Definition: le_sms_interface.h:503
void le_smsInbox1_SetServerDisconnectHandler(le_smsInbox1_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_smsInbox1_GetImsi(uint32_t msgId, char *imsi, size_t imsiSize)
void le_smsInbox1_ConnectService(void)
le_sms_Format_t le_smsInbox1_GetFormat(uint32_t msgId)
bool le_smsInbox1_IsUnread(uint32_t msgId)
le_result_t le_smsInbox1_GetBinary(uint32_t msgId, uint8_t *binPtr, size_t *binSizePtr)
le_result_t le_smsInbox1_TryConnectService(void)
void le_smsInbox1_MarkUnread(uint32_t msgId)
struct le_smsInbox1_Session * le_smsInbox1_SessionRef_t
Definition: le_smsInbox1_interface.h:290
le_result_t le_smsInbox1_GetTimeStamp(uint32_t msgId, char *timestamp, size_t timestampSize)
void le_smsInbox1_DisconnectService(void)
void le_smsInbox1_MarkRead(uint32_t msgId)
void(* le_smsInbox1_DisconnectHandler_t)(void *)
Definition: le_smsInbox1_interface.h:194
void le_smsInbox1_Close(le_smsInbox1_SessionRef_t sessionRef)
struct le_smsInbox1_RxMessageHandler * le_smsInbox1_RxMessageHandlerRef_t
Definition: le_smsInbox1_interface.h:298
void(* le_smsInbox1_RxMessageHandlerFunc_t)(uint32_t msgId, void *contextPtr)
Definition: le_smsInbox1_interface.h:308
le_result_t le_smsInbox1_GetSenderTel(uint32_t msgId, char *tel, size_t telSize)