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