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 /** @addtogroup le_smsInbox1 le_smsInbox1 API Reference
197  * @{
198  * @file le_smsInbox1_common.h
199  * @file le_smsInbox1_interface.h **/
200 //--------------------------------------------------------------------------------------------------
201 /**
202  * Type for handler called when a server disconnects.
203  */
204 //--------------------------------------------------------------------------------------------------
205 typedef void (*le_smsInbox1_DisconnectHandler_t)(void *);
206 
207 //--------------------------------------------------------------------------------------------------
208 /**
209  *
210  * Connect the current client thread to the service providing this API. Block until the service is
211  * available.
212  *
213  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
214  * called before any other functions in this API. Normally, ConnectService is automatically called
215  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
216  *
217  * This function is created automatically.
218  */
219 //--------------------------------------------------------------------------------------------------
221 (
222  void
223 );
224 
225 //--------------------------------------------------------------------------------------------------
226 /**
227  *
228  * Try to connect the current client thread to the service providing this API. Return with an error
229  * if the service is not available.
230  *
231  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
232  * called before any other functions in this API. Normally, ConnectService is automatically called
233  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
234  *
235  * This function is created automatically.
236  *
237  * @return
238  * - LE_OK if the client connected successfully to the service.
239  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
240  * bound.
241  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
242  * - LE_COMM_ERROR if the Service Directory cannot be reached.
243  */
244 //--------------------------------------------------------------------------------------------------
246 (
247  void
248 );
249 
250 //--------------------------------------------------------------------------------------------------
251 /**
252  * Set handler called when server disconnection is detected.
253  *
254  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
255  * to continue without exiting, it should call longjmp() from inside the handler.
256  */
257 //--------------------------------------------------------------------------------------------------
259 (
260  le_smsInbox1_DisconnectHandler_t disconnectHandler,
261  void *contextPtr
262 );
263 
264 //--------------------------------------------------------------------------------------------------
265 /**
266  *
267  * Disconnect the current client thread from the service providing this API.
268  *
269  * Normally, this function doesn't need to be called. After this function is called, there's no
270  * longer a connection to the service, and the functions in this API can't be used. For details, see
271  * @ref apiFilesC_client.
272  *
273  * This function is created automatically.
274  */
275 //--------------------------------------------------------------------------------------------------
277 (
278  void
279 );
280 
281 
282 //--------------------------------------------------------------------------------------------------
283 /**
284  * Reference type for referring to open message box sessions.
285  */
286 //--------------------------------------------------------------------------------------------------
287 
288 
289 //--------------------------------------------------------------------------------------------------
290 /**
291  * Handler for New Message.
292  *
293  */
294 //--------------------------------------------------------------------------------------------------
295 
296 
297 //--------------------------------------------------------------------------------------------------
298 /**
299  * Reference type used by Add/Remove functions for EVENT 'le_smsInbox1_RxMessage'
300  */
301 //--------------------------------------------------------------------------------------------------
302 
303 
304 //--------------------------------------------------------------------------------------------------
305 /**
306  * Open a message box.
307  *
308  * @return
309  * Reference on the opened message box session
310  */
311 //--------------------------------------------------------------------------------------------------
313 (
314  void
315 );
316 
317 //--------------------------------------------------------------------------------------------------
318 /**
319  * Close a previously open message box.
320  *
321  */
322 //--------------------------------------------------------------------------------------------------
324 (
325  le_smsInbox1_SessionRef_t sessionRef
326  ///< [IN] Mailbox session reference.
327 );
328 
329 //--------------------------------------------------------------------------------------------------
330 /**
331  * Add handler function for EVENT 'le_smsInbox1_RxMessage'
332  *
333  * This event provides information on new received messages.
334  *
335  */
336 //--------------------------------------------------------------------------------------------------
338 (
340  ///< [IN]
341  void* contextPtr
342  ///< [IN]
343 );
344 
345 //--------------------------------------------------------------------------------------------------
346 /**
347  * Remove handler function for EVENT 'le_smsInbox1_RxMessage'
348  */
349 //--------------------------------------------------------------------------------------------------
351 (
353  ///< [IN]
354 );
355 
356 //--------------------------------------------------------------------------------------------------
357 /**
358  * Delete a Message.
359  *
360  * @note It is valid to delete a non-existent message.
361  */
362 //--------------------------------------------------------------------------------------------------
364 (
365  uint32_t msgId
366  ///< [IN] Message identifier.
367 );
368 
369 //--------------------------------------------------------------------------------------------------
370 /**
371  * Retrieves the IMSI of the message receiver SIM if it applies.
372  *
373  * @return
374  * - LE_NOT_FOUND The message item is not tied to a SIM card, the imsi string is empty.
375  * - LE_OVERFLOW The imsiPtr buffer was too small for the IMSI.
376  * - LE_BAD_PARAMETER The message reference is invalid.
377  * - LE_FAULT The function failed.
378  * - LE_OK The function succeeded.
379  *
380  */
381 //--------------------------------------------------------------------------------------------------
383 (
384  uint32_t msgId,
385  ///< [IN] Message identifier.
386  char* imsi,
387  ///< [OUT] IMSI.
388  size_t imsiSize
389  ///< [IN]
390 );
391 
392 //--------------------------------------------------------------------------------------------------
393 /**
394  * Get the message format (text, binary or PDU).
395  *
396  * @return
397  * - Message format.
398  * - FORMAT_UNKNOWN when the message format cannot be identified or the message reference is
399  * invalid.
400  * @note For incoming SMS Inbox, format returned by le_smsInbox1_GetFormat() is never
401  * LE_SMSINBOX1_FORMAT_PDU.
402  */
403 //--------------------------------------------------------------------------------------------------
405 (
406  uint32_t msgId
407  ///< [IN] Message identifier.
408 );
409 
410 //--------------------------------------------------------------------------------------------------
411 /**
412  * Get the Sender Identifier.
413  *
414  * @return
415  * - LE_BAD_PARAMETER The message reference is invalid.
416  * - LE_OVERFLOW Identifier length exceed the maximum length.
417  * - LE_OK Function succeeded.
418  */
419 //--------------------------------------------------------------------------------------------------
421 (
422  uint32_t msgId,
423  ///< [IN] Message identifier.
424  char* tel,
425  ///< [OUT] Identifier string.
426  size_t telSize
427  ///< [IN]
428 );
429 
430 //--------------------------------------------------------------------------------------------------
431 /**
432  * Get the Message Time Stamp string (it does not apply for PDU message).
433  *
434  * @return
435  * - LE_BAD_PARAMETER The message reference is invalid.
436  * - LE_NOT_FOUND The message is a PDU message.
437  * - LE_OVERFLOW Timestamp number length exceed the maximum length.
438  * - LE_OK Function succeeded.
439  */
440 //--------------------------------------------------------------------------------------------------
442 (
443  uint32_t msgId,
444  ///< [IN] Message identifier.
445  char* timestamp,
446  ///< [OUT] Message time stamp (for text or binary
447  ///< messages). String format:
448  ///< "yy/MM/dd,hh:mm:ss+/-zz"
449  ///< (Year/Month/Day,Hour:Min:Seconds+/-TimeZone)
450  size_t timestampSize
451  ///< [IN]
452 );
453 
454 //--------------------------------------------------------------------------------------------------
455 /**
456  * Get the message Length value.
457  *
458  * @return Number of characters for text messages, or the length of the data in bytes for raw
459  * binary and PDU messages.
460  */
461 //--------------------------------------------------------------------------------------------------
463 (
464  uint32_t msgId
465  ///< [IN] Message identifier.
466 );
467 
468 //--------------------------------------------------------------------------------------------------
469 /**
470  * Get the text Message.
471  *
472  *
473  * @return
474  * - LE_BAD_PARAMETER The message reference is invalid.
475  * - LE_FORMAT_ERROR Message is not in text format.
476  * - LE_OVERFLOW Message length exceed the maximum length.
477  * - LE_OK Function succeeded.
478  */
479 //--------------------------------------------------------------------------------------------------
481 (
482  uint32_t msgId,
483  ///< [IN] Message identifier.
484  char* text,
485  ///< [OUT] Message text.
486  size_t textSize
487  ///< [IN]
488 );
489 
490 //--------------------------------------------------------------------------------------------------
491 /**
492  * Get the binary Message.
493  *
494  *
495  * @return
496  * - LE_BAD_PARAMETER The message reference is invalid.
497  * - LE_FORMAT_ERROR Message is not in binary format.
498  * - LE_OVERFLOW Message length exceed the maximum length.
499  * - LE_OK Function succeeded.
500  */
501 //--------------------------------------------------------------------------------------------------
503 (
504  uint32_t msgId,
505  ///< [IN] Message identifier.
506  uint8_t* binPtr,
507  ///< [OUT] Binary message.
508  size_t* binSizePtr
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  uint8_t* pduPtr,
531  ///< [OUT] PDU message.
532  size_t* pduSizePtr
533  ///< [INOUT]
534 );
535 
536 //--------------------------------------------------------------------------------------------------
537 /**
538  * Get the first Message object reference in the inbox message.
539  *
540  * @return
541  * - 0 No message found (message box parsing is over).
542  * - Message identifier.
543  */
544 //--------------------------------------------------------------------------------------------------
545 uint32_t le_smsInbox1_GetFirst
546 (
547  le_smsInbox1_SessionRef_t sessionRef
548  ///< [IN] Mailbox session reference.
549 );
550 
551 //--------------------------------------------------------------------------------------------------
552 /**
553  * Get the next Message object reference in the inbox message.
554  *
555  * @return
556  * - 0 No message found (message box parsing is over).
557  * - Message identifier.
558  */
559 //--------------------------------------------------------------------------------------------------
560 uint32_t le_smsInbox1_GetNext
561 (
562  le_smsInbox1_SessionRef_t sessionRef
563  ///< [IN] Mailbox session reference.
564 );
565 
566 //--------------------------------------------------------------------------------------------------
567 /**
568  * allow to know whether the message has been read or not. The message status is tied to the client
569  * app.
570  *
571  * @return True if the message is unread, false otherwise.
572  *
573  * @note If the caller is passing a bad message reference into this function, it is a fatal error,
574  * the function will not return.
575  */
576 //--------------------------------------------------------------------------------------------------
578 (
579  uint32_t msgId
580  ///< [IN] Message identifier.
581 );
582 
583 //--------------------------------------------------------------------------------------------------
584 /**
585  * Mark a message as 'read'.
586  *
587  * @note If the caller is passing a bad message reference into this function, it is a fatal error,
588  * the function will not return.
589  */
590 //--------------------------------------------------------------------------------------------------
592 (
593  uint32_t msgId
594  ///< [IN] Message identifier.
595 );
596 
597 //--------------------------------------------------------------------------------------------------
598 /**
599  * Mark a message as 'unread'.
600  *
601  * @note If the caller is passing a bad message reference into this function, it is a fatal error,
602  * the function will not return.
603  */
604 //--------------------------------------------------------------------------------------------------
606 (
607  uint32_t msgId
608  ///< [IN] Message identifier.
609 );
610 
611 //--------------------------------------------------------------------------------------------------
612 /**
613  * Set the maximum number of messages for message box.
614  *
615  * @return
616  * - LE_BAD_PARAMETER The message box name is invalid.
617  * - LE_OVERFLOW Message count exceed the maximum limit.
618  * - LE_OK Function succeeded.
619  * - LE_FAULT Function failed.
620  */
621 //--------------------------------------------------------------------------------------------------
623 (
624  uint32_t maxMessageCount
625  ///< [IN] Maximum number of messages
626 );
627 
628 //--------------------------------------------------------------------------------------------------
629 /**
630  * Get the maximum number of messages for message box.
631  *
632  * @return
633  * - LE_BAD_PARAMETER The message box name is invalid.
634  * - LE_OK Function succeeded.
635  * - LE_FAULT Function failed.
636  */
637 //--------------------------------------------------------------------------------------------------
639 (
640  uint32_t* maxMessageCountPtrPtr
641  ///< [OUT] Maximum number of messages
642 );
643 
644 /** @} **/
645 
646 #endif // LE_SMSINBOX1_INTERFACE_H_INCLUDE_GUARD
bool le_smsInbox1_IsUnread(uint32_t msgId)
struct le_smsInbox1_Session * le_smsInbox1_SessionRef_t
Definition: le_smsInbox1_common.h:52
le_result_t
Definition: le_basics.h:46
void le_smsInbox1_MarkUnread(uint32_t msgId)
struct le_smsInbox1_RxMessageHandler * le_smsInbox1_RxMessageHandlerRef_t
Definition: le_smsInbox1_common.h:60
size_t le_smsInbox1_GetMsgLen(uint32_t msgId)
uint32_t le_smsInbox1_GetNext(le_smsInbox1_SessionRef_t sessionRef)
le_result_t le_smsInbox1_GetImsi(uint32_t msgId, char *imsi, size_t imsiSize)
le_result_t le_smsInbox1_GetMaxMessages(uint32_t *maxMessageCountPtrPtr)
le_result_t le_smsInbox1_SetMaxMessages(uint32_t maxMessageCount)
void le_smsInbox1_DeleteMsg(uint32_t msgId)
void(* le_smsInbox1_DisconnectHandler_t)(void *)
Definition: le_smsInbox1_interface.h:205
le_result_t le_smsInbox1_GetTimeStamp(uint32_t msgId, char *timestamp, size_t timestampSize)
le_result_t le_smsInbox1_GetBinary(uint32_t msgId, uint8_t *binPtr, size_t *binSizePtr)
le_smsInbox1_SessionRef_t le_smsInbox1_Open(void)
uint32_t le_smsInbox1_GetFirst(le_smsInbox1_SessionRef_t sessionRef)
le_result_t le_smsInbox1_GetSenderTel(uint32_t msgId, char *tel, size_t telSize)
void le_smsInbox1_RemoveRxMessageHandler(le_smsInbox1_RxMessageHandlerRef_t handlerRef)
void le_smsInbox1_DisconnectService(void)
void le_smsInbox1_Close(le_smsInbox1_SessionRef_t sessionRef)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_smsInbox1_RxMessageHandlerRef_t le_smsInbox1_AddRxMessageHandler(le_smsInbox1_RxMessageHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_smsInbox1_GetPdu(uint32_t msgId, uint8_t *pduPtr, size_t *pduSizePtr)
le_sms_Format_t le_smsInbox1_GetFormat(uint32_t msgId)
LE_FULL_API void le_smsInbox1_SetServerDisconnectHandler(le_smsInbox1_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_smsInbox1_ConnectService(void)
le_sms_Format_t
Definition: le_sms_common.h:102
void le_smsInbox1_MarkRead(uint32_t msgId)
le_result_t le_smsInbox1_GetText(uint32_t msgId, char *text, size_t textSize)
void(* le_smsInbox1_RxMessageHandlerFunc_t)(uint32_t msgId, void *contextPtr)
Definition: le_smsInbox1_common.h:70
le_result_t le_smsInbox1_TryConnectService(void)