le_smsInbox1_interface.h

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