le_sms_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_sms SMS
14  *
15  * @ref le_sms_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * This file contains data structures and prototypes definitions for high level SMS APIs.
20  *
21  * SMS is a common way to communicate in the M2M world.
22  *
23  * It's an easy, fast way to send a small amount of data (e.g., sensor values for gas telemetry).
24  * Usually, the radio module requests small power resources to send or receive a message.
25  * It's often a good way to wake-up a device that was disconnected from the network or that was
26  * operating in low power mode.
27  *
28  * @section le_sms_binding IPC interfaces binding
29  *
30  * All the functions of this API are provided by the @b modemService.
31  *
32  * Here's a code sample binding to modem services:
33  * @verbatim
34  bindings:
35  {
36  clientExe.clientComponent.le_sms -> modemService.le_sms
37  }
38  @endverbatim
39  *
40  * @section le_sms_ops_creating_msg Creating a Message object
41  * There are 3 kinds of supported messages: text messages, binary messages, and PDU messages.
42  *
43  * You must create a Message object by calling @c le_sms_Create() before using the message
44  * APIs. It automatically allocates needed resources for the Message object, which is referenced by
45  * @c le_sms_MsgRef_t type.
46  *
47  * When the Message object is no longer needed, call @c le_sms_Delete() to free all
48  * allocated resources associated with the object.
49  *
50  * @section le_sms_ops_deleting_msg Deleting a Message object
51  * To delete a Message object, call le_sms_Delete(). This frees all the
52  * resources allocated for the Message object. If several users own the Message object
53  * (e.g., several handler functions registered for SMS message reception), the
54  * Message object will be deleted only after the last user deletes the Message object.
55  *
56  * @section le_sms_ops_sending Sending a message
57  * To send a message, create an @c le_sms_MsgRef_t object by calling the
58  * @c le_sms_Create() function. Then, set all the needed parameters for the message:
59  * - Destination telephone number with le_sms_SetDestination();
60  * - Text content with le_sms_SetText(), the total length are set as well with this API, maximum
61  * 160 characters as only the 7-bit alphabet is supported.
62  * - Binary content with le_sms_SetBinary(), total length is set with this API, maximum 140 bytes.
63  * - PDU content with le_sms_SetPDU(), total length is set with this API, max 36 (header) + 140
64  * (payload) bytes long.
65  * - UCS2 content (16-bit format) with le_sms_SetUCS2(), total length is set with this API, maximum
66  * 70 characters (140 bytes).
67  *
68  * When the Msg object is ready, call @c le_sms_Send() to transmit it.
69  *
70  * @c le_sms_Send() is a blocking function with a maximum timeout set to 240 seconds, it will return
71  * once the Modem has given back a positive or negative answer to the sending operation.
72  * The return of @c le_sms_Send() API provides definitive status of the sending operation.
73  * TP-Validity-Period(TP-VP) parameter value indicates the time period for which the short message
74  * is valid, i.e. for how long the Service Center (SC) shall guarantee its existence in the SC
75  * memory before delivery to the recipient has been carried out. The default validity period(TP-VP)
76  * is set to 7 days for MO SMS.
77  *
78  * When a message sending has failed and returned LE_FAULT, call le_sms_GetErrorCode() to retrieve
79  * the 3GPP message error code or le_sms_Get3GPP2ErrorCode() to retrieve the 3GPP2 message error
80  * code. If LE_SMS_ERROR_3GPP_PLATFORM_SPECIFIC or LE_SMS_ERROR_3GPP2_PLATFORM_SPECIFIC values is
81  * returned, call le_sms_GetPlatformSpecificErrorCode() to retrieve the platform specific error
82  * code.
83  *
84  * Please refer to @ref platformConstraintsSpecificErrorCodes for platform
85  * specific error code description.
86  *
87  * Please refer to @ref c_smsSampleMO page to get an example of SMS message sending.
88  *
89  * @section le_sms_ops_async_sending Sending asynchronously a message
90  *
91  * To send an asynchronous message, le_sms_SendAsync() API can be called instead of le_sms_Send().
92  * le_sms_SendAsync() is a non-blocking function, it queues the message to the SMS pool and returns
93  * immediatly. Then, Legato will internally attempt to send the SMS with a maximum timeout set
94  * to 240 seconds for each SMS in the pool.
95  * This function is usefull to stack a set of messages without blocking the user application.
96  * Moreover, a handler can be specified to le_sms_SendAsync() API in order to keep track of the
97  * transmission status.
98  *
99  * The default validity period(TP-VP) is set to 7 days for MO SMS.
100  *
101  * A text message can be sent with one simple function: le_sms_SendText(). You only have to pass
102  * the three following parameters:
103  * - the destination telephone number.
104  * - the text message, the total length are set as well with this function, maximum 160
105  * characters as only the 7-bit alphabet is supported.
106  * - the callback function to get a notification indicating the sending result: LE_SMS_SENT,
107  * LE_SMS_SENDING_FAILED or LE_SMS_SENDING_TIMEOUT.
108  * The default validity period(TP-VP) is set to 7 days for MO SMS.
109  *
110  * A PDU message can be sent using the le_sms_SendPdu() functions. The parameters to give are:
111  * - the PDU content, total length is set with this API, maximum 176 bytes long = 36 (header) +
112  * 140 (payload).
113  * - the callback function to get a notification indicating the sending result: LE_SMS_SENT,
114  * LE_SMS_SENDING_FAILED or LE_SMS_SENDING_TIMEOUT.
115  * The default validity period(TP-VP) is set to 7 days for MO SMS.
116  *
117  * When a message sending has failed, call le_sms_GetErrorCode() to retrieve the 3GPP message error
118  * code or le_sms_Get3GPP2ErrorCode() to retrieve the 3GPP2 message error code.
119  * If LE_SMS_ERROR_3GPP_PLATFORM_SPECIFIC or LE_SMS_ERROR_3GPP2_PLATFORM_SPECIFIC values is
120  * returned, call le_sms_GetPlatformSpecificErrorCode() to retrieve the platform specific error
121  * code.
122  *
123  * Message object is never deleted regardless of the sending result. Caller has to
124  * delete it. Message object once used for sending the message can not be reused to
125  * send another message regardless of success or failure. New object has to be created
126  * for new message.
127  *
128  * @section le_sms_ops_receiving Receiving a message
129  * To receive SMS messages, register a handler function to obtain incoming
130  * messages. Use @c le_sms_AddRxMessageHandler() to register that handler.
131  *
132  * The handler must satisfy the following prototype:
133  * @c typedef void (*le_sms_RxMessageHandlerFunc_t)(le_sms_MsgRef_t msg).
134  *
135  * When a new incoming message is received, a Message object is automatically created and the
136  * handler is called. This Message object is Read-Only, any calls of a le_sms_SetXXX API will
137  * return a LE_NOT_PERMITTED error.
138  *
139  * Use the following APIs to retrieve message information and data from the Message
140  * object:
141  * - le_sms_GetFormat() - determine if it is a binary or a text message.
142  * - le_sms_GetSenderTel() - get the sender's Telephone number.
143  * - le_sms_GetTimeStamp() - get the timestamp sets by the Service Center.
144  * - le_sms_GetUserdataLen() - get the message content (text, binary or UCS2) length.
145  * - le_sms_GetPDULen() - get the PDU message length.
146  * - le_sms_GetText() - get the message text.
147  * - le_sms_GetUCS2() - get the UCS2 message content (16-bit format).
148  * - le_sms_GetBinary() - get the message binary content.
149  * - le_sms_GetPDU() - get the message PDU data.
150  * - le_sms_GetType() - get the message type.
151  *
152  * @note - If two (or more) registered handler functions exist, they are
153  * all called and get a different message object reference.
154  *
155  * @note - For incoming SMS, if the returned format is LE_SMS_FORMAT_PDU, the PDU length can be
156  * retrieved by calling le_sms_GetPDULen() and the content can be read by le_sms_GetPDU().
157  *
158  * If a succession of messages is received, a new Message object is created for each, and
159  * the handler is called for each new message.
160  *
161  * Uninstall the handler function by calling @c le_sms_RemoveRxMessageHandler().
162  * @note @c le_sms_RemoveRxMessageHandler() API does not delete the Message Object.
163  * The caller has to delete it.
164  *
165  * Please refer to @ref c_smsSampleMT page to get an example of SMS message reception handling.
166  *
167  * @section le_sms_ops_sms_storage Receiving a full SMS storage indication
168  * To receive a SMS full storage status, the application has to register a handler function.
169  * Use @c le_sms_AddFullStorageEventHandler() to register that handler.
170  *
171  * The handler must satisfy the following prototype:
172  * @c typedef void (*le_sms_FullStorageEventFunc_t)(le_sms_Storage_t storage).
173  *
174  * Uninstall the handler function by calling @c le_sms_RemoveFullStorageEventHandler().
175  *
176  * Please refer to @ref c_smsSampleMT page to get an example of SMS storage indication
177  * handling.
178  *
179  * @section le_sms_ops_listing Listing messages recorded in storage area
180  *
181  * Call @c le_sms_CreateRxMsgList() to create a List object that lists the received
182  * messages present in the storage area, which is referenced by @c le_sms_MsgListRef_t
183  * type.
184  *
185  * If messages are not present, the le_sms_CreateRxMsgList() returns NULL.
186  *
187  * Once the list is available, call @c le_sms_GetFirst() to get the first
188  * message from the list, and then call @c le_sms_GetNext() API to get the next message.
189  *
190  * Call @c le_sms_DeleteList() to free all allocated
191  * resources associated with the List object.
192  *
193  * Call @c le_sms_GetStatus() to read the status of a message (Received
194  * Read, Received Unread).
195  *
196  * To finish, you can also modify the received status of a message with
197  * @c le_sms_MarkRead() and @c le_sms_MarkUnread().
198  *
199  * @section le_sms_ops_deleting Deleting a message from the storage area
200  *
201  * @c le_sms_DeleteFromStorage() deletes the message from the storage area. Message is
202  * identified with @c le_sms_MsgRef_t object. The API returns an error if the deletion cannot be
203  * performed or if it is a broadcast or a non stored message.
204  *
205  * @note If several users own the Message object on new reception
206  * (e.g., several handler functions registered for SMS message reception), the
207  * Message will be deleted from the storage area only after the last user deletes
208  * the Message object reference (not necessary from storage). API returns always LE_OK in this case.
209  *
210  * @note If one client creates a list and deletes all sms from storage, other clients won’t see sms
211  * stored If they have not created a sms list too. Sms List creation locks and
212  * delays sms deletion from storage until all references have been deleted.
213  *
214  * @section le_sms_ops_broadcast SMS Cell Broadcast
215  *
216  * The Cell Broadcast service permits a number of unacknowledged general messages to be broadcast
217  * to all receivers within a particular region. Cell Broadcast messages are broadcast to defined
218  * geographical areas known as cell broadcast areas. These areas may comprise of one or more cells,
219  * or may comprise the entire PLMN.
220  *
221  * GSM or UMTS SMS cell broadcast service can be activated or deactivated with
222  * le_sms_ActivateCellBroadcast() and le_sms_DeactivateCellBroadcast() APIs.
223  *
224  * CDMA cell broadcast service can be activated or deactivated with
225  * le_sms_ActivateCdmaCellBroadcast() and le_sms_DeactivateCdmaCellBroadcast() APIs.
226  *
227  * Cell broadcast message receptions are notify by the SMS handler like a SMS message reception,
228  * but there are neither stored in SIM nor in the modem. So le_sms_DeleteFromStorage()
229  * can't be used but the message reference shall be delete with le_sms_Delete().
230  *
231  * - le_sms_GetFormat() - determine if it is a binary or a text message.
232  * - le_sms_GetUserdataLen() - get the message content (text, binary or UCS2) length.
233  * - le_sms_GetPDULen() - get the PDU message received length.
234  * - le_sms_GetText() - get the message text.
235  * - le_sms_GetBinary() - get the message binary content.
236  * - le_sms_GetUCS2() - get the UCS2 message content (16-bit format).
237  * - le_sms_GetPDU() - get the message PDU data received length.
238  * - le_sms_GetCellBroadcastId() - get the message identifier received (3GPP 23.41).
239  * - le_sms_GetCellBroadcastSerialNumber() get the message Serial Number received (3GPP 23.41).
240  *
241  * A sample code that implements a function for SMS Cell Broadcast reception can be found in
242  * \b smsCBTest.c file (please refer to @ref c_smsCbSample page).
243  *
244  * @b Serial @b Number
245  *
246  * Cell Broadcast Serial Number parameter is a 16-bit integer which identifies a particular
247  * CBS message from the source and type indicated by the Message Identifier and is altered every
248  * time the CBS message with a given Message Identifier is changed.
249  *
250  * The two bytes of the Serial Number field are divided into a 2-bit Geographical Scope (GS)
251  * indicator, a 10-bit Message Code and a 4-bit Update Number as shown below:
252  *
253  * - GS code (bit 14 and 15): The Geographical Scope (GS) indicates the geographical area over
254  * which the Message Code is unique, and the display mode.
255  *
256  * - Message Code (bit 4 to 13) : The Message Code differentiates between CBS messages from
257  * the same source and type (i.e. with the same Message Identifier). Message Codes are for
258  * allocation by PLMN operators. The Message Code identifies different message themes.
259  * For example, let the value for the Message Identifier be "Automotive Association" (= source),
260  * "Traffic Reports" (= type). Then "Crash on A1 J5" could be one value for the message code,
261  * "Cow on A32 J4" could be another, and "Slow vehicle on M3 J3" yet another.
262  *
263  * - Update Number (bit 0 to 3) : The Update Number indicates a change of the message content of
264  * the same CBS message, i.e. the CBS message with the same Message Identifier, Geographical
265  * Scope, and Message Code.
266  *
267  * Serial Number fields meaning are defined in the 3GPP 23.041 (9.4.1.2.1 Serial Number).
268  *
269  * @b Message @b Identifier
270  *
271  * Message Identifier parameter identifies the source and type of the CBS message. For example,
272  * "Automotive Association" (= source), "Traffic Reports" (= type) could correspond to one value.
273  * A number of CBS messages may originate from the same source and/or be of the same type.
274  * These will be distinguished by the Serial Number.
275  *
276  * Message identifier meaning ranges are defined in the 3GPP 23.041 (9.4.1.2.2 Message Identifier).
277  *
278  * @section le_sms_ops_broadcast_configuration SMS Cell Broadcast configuration
279  *
280  * GSM or UMTS Cell broadcast Message identifiers range can be added or removed with
281  * le_sms_AddCellBroadcastIds() and le_sms_RemoveCellBroadcastIds() APIs. All Message identifiers
282  * can be removed with le_sms_ClearCellBroadcastIds() API.
283  *
284  * CDMA Cell broadcast Service categories can be added or removed with
285  * le_sms_AddCdmaCellBroadcastServices() and le_sms_RemoveCdmaCellBroadcastServices() APIs. All
286  * Service categories can be removed with le_sms_ClearCdmaCellBroadcastServices() API.
287  *
288  * @section le_sms_ops_statusReport SMS Status Report
289  *
290  * SMS Status Report may be sent by the SMS Center (SMSC) to inform the originating device about the
291  * final outcome of the message delivery.
292  *
293  * SMS Status Report can be activated or deactivated for outgoing messages with
294  * le_sms_EnableStatusReport() and le_sms_DisableStatusReport(). The current activation state can
295  * be retrieved with le_sms_IsStatusReportEnabled().
296  *
297  * The reception of a SMS Status Report is notified by the SMS handler like a SMS message reception,
298  * but the message is neither stored in SIM nor in the modem. So le_sms_DeleteFromStorage()
299  * can't be used, but the message reference shall be delete with le_sms_Delete(). Received SMS
300  * Status Reports are identified by a specific type: @ref LE_SMS_TYPE_STATUS_REPORT.
301  *
302  * The different elements of the SMS Status Report can be retrieved with the following APIs:
303  * - le_sms_GetTpMr() gives the Message Reference, defined in 3GPP TS 23.040 section 9.2.3.6.
304  * - le_sms_GetTpRa() gives the Recipient Address, defined in 3GPP TS 23.040 section 9.2.3.14, and
305  * the Recipient Address Type of Address, defined in 3GPP TS 24.011 section 8.2.5.2.
306  * - le_sms_GetTpScTs() gives the Service Centre Time Stamp, defined in 3GPP TS 23.040
307  * section 9.2.3.11.
308  * - le_sms_GetTpDt() gives the Discharge Time, defined in 3GPP TS 23.040 section 9.2.3.13.
309  * - le_sms_GetTpSt() gives the Status, defined in 3GPP TS 23.040 section 9.2.3.15.
310  *
311  * @section le_sms_ops_configuration SMS configuration
312  *
313  * Modem SMS Center Address can be set or get with le_sms_SetSmsCenterAddress() and
314  * le_sms_GetSmsCenterAddress() functions
315  *
316  * @section le_sms_ops_storage_configuration Preferred SMS storage configuration
317  *
318  * Preferred SMS storage for incoming messages can be set or get with le_sms_SetPreferredStorage()
319  * and le_sms_GetPreferredStorage() functions.
320  *
321  * @section le_sms_ops_statistics SMS statistics
322  *
323  * The number of SMS successfully sent or received through the Legato API can be counted.
324  * This feature is activated by default. le_sms_GetCount() allows retrieving the message count
325  * for each SMS type (cf. @ref le_sms_Type_t).
326  *
327  * le_sms_StopCount() stops the message counting and le_sms_StartCount() restarts it.
328  * le_sms_ResetCount() can be used to reset the message counters.
329  *
330  * @note The activation state of this feature is persistent even after a reboot of the platform.
331  *
332  * @section le_sms_ops_samples Sample codes
333  * A sample code that implements a function for Mobile Originated SMS message can be found in
334  * \b smsMO.c file (please refer to @ref c_smsSampleMO page).
335  *
336  * A sample code that implements a function for Mobile Terminated SMS message can be found in
337  * \b smsMT.c file (please refer to @ref c_smsSampleMT page).
338  *
339  * These two samples can be easily compiled and run into the \b sms app, to install and use
340  * this app:
341  *
342  * @verbatim
343  $ make ar7
344  $ bin/instapp build/ar7/bin/samples/sms.ar7 <ipaddress>
345  @endverbatim
346  * where ipaddress is the address of your target device.
347  *
348  * Then on your target, just run:
349  * @verbatim
350  $ app start sms
351  @endverbatim
352  *
353  * The sample replies to the sender by the message "Message from <phone number> received". Where
354  * "phone number" is the sender's phone number.
355  *
356  * Sample code for that application can be seen in the following pages:
357  * - @subpage c_smsSampleMO <br>
358  * - @subpage c_smsSampleMT
359  *
360  * <HR>
361  *
362  * Copyright (C) Sierra Wireless Inc.
363  */
364 /**
365  * @file le_sms_interface.h
366  *
367  * Legato @ref c_sms include file.
368  *
369  * Copyright (C) Sierra Wireless Inc.
370  */
371 /**
372  * @page c_smsSampleMO Sample code for Mobile Originated SMS message
373  *
374  * @include "apps/sample/sms/smsClient/smsMO.c"
375  */
376 /**
377  * @page c_smsSampleMT Sample code for Mobile Terminated SMS message
378  *
379  * @include "apps/sample/sms/smsClient/smsMT.c"
380  */
381 /**
382  * @page c_smsCbSample Sample code for SMS Cell Broadcast reception
383  *
384  * @include "apps/test/modemServices/sms/smsIntegrationTest/smsCBTest/smsCBTest.c"
385  */
386 
387 #ifndef LE_SMS_INTERFACE_H_INCLUDE_GUARD
388 #define LE_SMS_INTERFACE_H_INCLUDE_GUARD
389 
390 
391 #include "legato.h"
392 
393 // Interface specific includes
394 #include "le_mdmDefs_interface.h"
395 
396 // Internal includes for this interface
397 #include "le_sms_common.h"
398 /** @addtogroup le_sms le_sms API Reference
399  * @{
400  * @file le_sms_common.h
401  * @file le_sms_interface.h **/
402 //--------------------------------------------------------------------------------------------------
403 /**
404  * Type for handler called when a server disconnects.
405  */
406 //--------------------------------------------------------------------------------------------------
407 typedef void (*le_sms_DisconnectHandler_t)(void *);
408 
409 //--------------------------------------------------------------------------------------------------
410 /**
411  *
412  * Connect the current client thread to the service providing this API. Block until the service is
413  * available.
414  *
415  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
416  * called before any other functions in this API. Normally, ConnectService is automatically called
417  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
418  *
419  * This function is created automatically.
420  */
421 //--------------------------------------------------------------------------------------------------
423 (
424  void
425 );
426 
427 //--------------------------------------------------------------------------------------------------
428 /**
429  *
430  * Try to connect the current client thread to the service providing this API. Return with an error
431  * if the service is not available.
432  *
433  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
434  * called before any other functions in this API. Normally, ConnectService is automatically called
435  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
436  *
437  * This function is created automatically.
438  *
439  * @return
440  * - LE_OK if the client connected successfully to the service.
441  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
442  * bound.
443  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
444  * - LE_COMM_ERROR if the Service Directory cannot be reached.
445  */
446 //--------------------------------------------------------------------------------------------------
448 (
449  void
450 );
451 
452 //--------------------------------------------------------------------------------------------------
453 /**
454  * Set handler called when server disconnection is detected.
455  *
456  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
457  * to continue without exiting, it should call longjmp() from inside the handler.
458  */
459 //--------------------------------------------------------------------------------------------------
461 (
462  le_sms_DisconnectHandler_t disconnectHandler,
463  void *contextPtr
464 );
465 
466 //--------------------------------------------------------------------------------------------------
467 /**
468  *
469  * Disconnect the current client thread from the service providing this API.
470  *
471  * Normally, this function doesn't need to be called. After this function is called, there's no
472  * longer a connection to the service, and the functions in this API can't be used. For details, see
473  * @ref apiFilesC_client.
474  *
475  * This function is created automatically.
476  */
477 //--------------------------------------------------------------------------------------------------
479 (
480  void
481 );
482 
483 
484 //--------------------------------------------------------------------------------------------------
485 /**
486  * Message Format.
487  */
488 //--------------------------------------------------------------------------------------------------
489 
490 
491 //--------------------------------------------------------------------------------------------------
492 /**
493  * Message Type.
494  */
495 //--------------------------------------------------------------------------------------------------
496 
497 
498 //--------------------------------------------------------------------------------------------------
499 /**
500  * Message Status.
501  */
502 //--------------------------------------------------------------------------------------------------
503 
504 
505 //--------------------------------------------------------------------------------------------------
506 /**
507  * CDMA Cell broadcast message languages.
508  */
509 //--------------------------------------------------------------------------------------------------
510 
511 
512 //--------------------------------------------------------------------------------------------------
513 /**
514  * CDMA Cell broadcast Service Categories.
515  */
516 //--------------------------------------------------------------------------------------------------
517 
518 
519 //--------------------------------------------------------------------------------------------------
520 /**
521  * SMS storage area.
522  */
523 //--------------------------------------------------------------------------------------------------
524 
525 
526 //--------------------------------------------------------------------------------------------------
527 /**
528  * 3GPP2 Message Error code when the message sending has failed.
529  */
530 //--------------------------------------------------------------------------------------------------
531 
532 
533 //--------------------------------------------------------------------------------------------------
534 /**
535  * Message Error code when the message sending has failed.
536  */
537 //--------------------------------------------------------------------------------------------------
538 
539 
540 //--------------------------------------------------------------------------------------------------
541 /**
542  * Declare a reference type for referring to SMS Message objects.
543  */
544 //--------------------------------------------------------------------------------------------------
545 
546 
547 //--------------------------------------------------------------------------------------------------
548 /**
549  * Opaque type for SMS Message Listing.
550  */
551 //--------------------------------------------------------------------------------------------------
552 
553 
554 //--------------------------------------------------------------------------------------------------
555 /**
556  * Handler for Sending result.
557  */
558 //--------------------------------------------------------------------------------------------------
559 
560 
561 //--------------------------------------------------------------------------------------------------
562 /**
563  * Handler for New Message.
564  *
565  */
566 //--------------------------------------------------------------------------------------------------
567 
568 
569 //--------------------------------------------------------------------------------------------------
570 /**
571  * Reference type used by Add/Remove functions for EVENT 'le_sms_RxMessage'
572  */
573 //--------------------------------------------------------------------------------------------------
574 
575 
576 //--------------------------------------------------------------------------------------------------
577 /**
578  * Handler for full storage indication.
579  *
580  */
581 //--------------------------------------------------------------------------------------------------
582 
583 
584 //--------------------------------------------------------------------------------------------------
585 /**
586  * Reference type used by Add/Remove functions for EVENT 'le_sms_FullStorageEvent'
587  */
588 //--------------------------------------------------------------------------------------------------
589 
590 
591 //--------------------------------------------------------------------------------------------------
592 /**
593  * Add handler function for EVENT 'le_sms_RxMessage'
594  *
595  * This event provides information on new received messages.
596  *
597  */
598 //--------------------------------------------------------------------------------------------------
600 (
602  ///< [IN]
603  void* contextPtr
604  ///< [IN]
605 );
606 
607 //--------------------------------------------------------------------------------------------------
608 /**
609  * Remove handler function for EVENT 'le_sms_RxMessage'
610  */
611 //--------------------------------------------------------------------------------------------------
613 (
615  ///< [IN]
616 );
617 
618 //--------------------------------------------------------------------------------------------------
619 /**
620  * Add handler function for EVENT 'le_sms_FullStorageEvent'
621  *
622  * This event provides information on full storage indication.
623  *
624  */
625 //--------------------------------------------------------------------------------------------------
627 (
629  ///< [IN]
630  void* contextPtr
631  ///< [IN]
632 );
633 
634 //--------------------------------------------------------------------------------------------------
635 /**
636  * Remove handler function for EVENT 'le_sms_FullStorageEvent'
637  */
638 //--------------------------------------------------------------------------------------------------
640 (
642  ///< [IN]
643 );
644 
645 //--------------------------------------------------------------------------------------------------
646 /**
647  * Create an SMS Message data structure.
648  *
649  * @return Reference to the new Message object.
650  *
651  * @note
652  * On failure, the process exits, so you don't have to worry about checking the returned
653  * reference for validity.
654  */
655 //--------------------------------------------------------------------------------------------------
657 (
658  void
659 );
660 
661 //--------------------------------------------------------------------------------------------------
662 /**
663  * Set the Telephone destination number.
664  *
665  * Telephone number is defined in ITU-T recommendations E.164/E.163.
666  * E.164 numbers can have a maximum of fifteen digits and are usually written with a '+' prefix.
667  *
668  * @return LE_NOT_PERMITTED Message is Read-Only.
669  * @return LE_BAD_PARAMETER Telephone destination number length is equal to zero.
670  * @return LE_OK Function succeeded.
671  *
672  * @note If telephone destination number is too long is too long (max LE_MDMDEFS_PHONE_NUM_MAX_LEN
673  * digits), it is a fatal error, the function will not return.
674  *
675  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
676  * function will not return.
677  */
678 //--------------------------------------------------------------------------------------------------
680 (
681  le_sms_MsgRef_t msgRef,
682  ///< [IN] Reference to the message object.
683  const char* LE_NONNULL dest
684  ///< [IN] Telephone number string.
685 );
686 
687 //--------------------------------------------------------------------------------------------------
688 /**
689  * This function must be called to set the Text Message content.
690  *
691  * @return LE_NOT_PERMITTED Message is Read-Only.
692  * @return LE_BAD_PARAMETER Text message length is equal to zero.
693  * @return LE_OK Function succeeded.
694  *
695  * @note Text Message is encoded in ASCII format (ISO8859-15) and characters have to exist in
696  * the GSM 23.038 7 bit alphabet.
697  *
698  * @note If message is too long (max LE_SMS_TEXT_MAX_LEN digits), it is a fatal error, the
699  * function will not return.
700  *
701  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
702  * function will not return.
703  */
704 //--------------------------------------------------------------------------------------------------
706 (
707  le_sms_MsgRef_t msgRef,
708  ///< [IN] Reference to the message object.
709  const char* LE_NONNULL text
710  ///< [IN] SMS text.
711 );
712 
713 //--------------------------------------------------------------------------------------------------
714 /**
715  * Set the binary message content.
716  *
717  * @return LE_NOT_PERMITTED Message is Read-Only.
718  * @return LE_BAD_PARAMETER Length of the data is equal to zero.
719  * @return LE_OK Function succeeded.
720  *
721  * @note If length of the data is too long (max LE_SMS_BINARY_MAX_BYTES bytes), it is a fatal
722  * error, the function will not return.
723  *
724  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
725  * function will not return.
726  */
727 //--------------------------------------------------------------------------------------------------
729 (
730  le_sms_MsgRef_t msgRef,
731  ///< [IN] Reference to the message object.
732  const uint8_t* binPtr,
733  ///< [IN] Binary data.
734  size_t binSize
735  ///< [IN]
736 );
737 
738 //--------------------------------------------------------------------------------------------------
739 /**
740  * Set the UCS2 message content (16-bit format).
741  *
742  * @return
743  * - LE_NOT_PERMITTED Message is Read-Only.
744  * - LE_BAD_PARAMETER Length of the data is equal to zero.
745  * - LE_OK Function succeeded.
746  *
747  * @note If length of the data is too long (max LE_SMS_UCS2_MAX_CHARS), it is a fatal
748  * error, the function will not return.
749  *
750  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
751  * function will not return.
752  */
753 //--------------------------------------------------------------------------------------------------
755 (
756  le_sms_MsgRef_t msgRef,
757  ///< [IN] Reference to the message object.
758  const uint16_t* ucs2Ptr,
759  ///< [IN] UCS2 message.
760  size_t ucs2Size
761  ///< [IN]
762 );
763 
764 //--------------------------------------------------------------------------------------------------
765 /**
766  * Set the PDU message content.
767  *
768  * @return LE_NOT_PERMITTED Message is Read-Only.
769  * @return LE_BAD_PARAMETER Length of the data is equal to zero.
770  * @return LE_OK Function succeeded.
771  *
772  * @note If length of the data is too long (max LE_SMS_PDU_MAX_BYTES bytes), it is a fatal error,
773  * the function will not return.
774  *
775  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
776  * function will not return.
777  */
778 //--------------------------------------------------------------------------------------------------
780 (
781  le_sms_MsgRef_t msgRef,
782  ///< [IN] Reference to the message object.
783  const uint8_t* pduPtr,
784  ///< [IN] PDU message.
785  size_t pduSize
786  ///< [IN]
787 );
788 
789 //--------------------------------------------------------------------------------------------------
790 /**
791  * Send an SMS message.
792  *
793  * Verifies first if the parameters are valid, then it checks the modem state can support
794  * message sending.
795  *
796  * @return LE_FORMAT_ERROR Message content is invalid.
797  * @return LE_FAULT Function failed to send the message.
798  * @return LE_OK Function succeeded.
799  * @return LE_TIMEOUT Timeout before the complete sending.
800  *
801  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
802  * function will not return.
803  */
804 //--------------------------------------------------------------------------------------------------
806 (
807  le_sms_MsgRef_t msgRef
808  ///< [IN] Reference to the message object.
809 );
810 
811 //--------------------------------------------------------------------------------------------------
812 /**
813  * Send an asynchronous SMS message.
814  *
815  * Verifies first if the parameters are valid, then it checks the modem state can support
816  * message sending.
817  *
818  * @return LE_FORMAT_ERROR Message content is invalid.
819  * @return LE_FAULT Function failed to send the message.
820  * @return LE_OK Function succeeded.
821  * @return LE_TIMEOUT Timeout before the complete sending.
822  *
823  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
824  * function will not return.
825  */
826 //--------------------------------------------------------------------------------------------------
828 (
829  le_sms_MsgRef_t msgRef,
830  ///< [IN] Reference to the message object.
831  le_sms_CallbackResultFunc_t handlerPtr,
832  ///< [IN] CallBack for sending result.
833  void* contextPtr
834  ///< [IN]
835 );
836 
837 //--------------------------------------------------------------------------------------------------
838 /**
839  * Get the error code when a 3GPP2 message sending has Failed.
840  *
841  * @return The error code
842  *
843  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
844  * function will not return.
845  *
846  * @note It is only applicable for 3GPP2 message sending failure, otherwise
847  * LE_SMS_ERROR_3GPP2_MAX is returned.
848  */
849 //--------------------------------------------------------------------------------------------------
851 (
852  le_sms_MsgRef_t msgRef
853  ///< [IN] Reference to the message object.
854 );
855 
856 //--------------------------------------------------------------------------------------------------
857 /**
858  * Get the Radio Protocol and the Transfer Protocol error code when a 3GPP message sending has
859  * failed.
860  *
861  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
862  * function will not return.
863  *
864  * @note It is only applicable for 3GPP message sending failure, otherwise
865  * LE_SMS_ERROR_3GPP_MAX is returned.
866  */
867 //--------------------------------------------------------------------------------------------------
869 (
870  le_sms_MsgRef_t msgRef,
871  ///< [IN] Reference to the message object.
872  le_sms_ErrorCode_t* rpCausePtr,
873  ///< [OUT] Radio Protocol cause code.
874  le_sms_ErrorCode_t* tpCausePtr
875  ///< [OUT] Transfer Protocol cause code.
876 );
877 
878 //--------------------------------------------------------------------------------------------------
879 /**
880  * Called to get the platform specific error code.
881  *
882  * Refer to @ref platformConstraintsSpecificErrorCodes for platform specific error code description.
883  *
884  * @return The platform specific error code.
885  *
886  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
887  * function will not return.
888  */
889 //--------------------------------------------------------------------------------------------------
891 (
892  le_sms_MsgRef_t msgRef
893  ///< [IN] Reference to the message object.
894 );
895 
896 //--------------------------------------------------------------------------------------------------
897 /**
898  * Create and asynchronously send a text message.
899  *
900  * @return
901  * - le_sms_Msg Reference to the new Message object pooled.
902  * - NULL Not possible to pool a new message.
903  *
904  * @note If telephone destination number is too long is too long (max LE_MDMDEFS_PHONE_NUM_MAX_LEN
905  * digits), it is a fatal error, the function will not return.
906  * @note If message is too long (max LE_SMS_TEXT_MAX_LEN digits), it is a fatal error, the
907  * function will not return.
908  */
909 //--------------------------------------------------------------------------------------------------
911 (
912  const char* LE_NONNULL destStr,
913  ///< [IN] Telephone number string.
914  const char* LE_NONNULL textStr,
915  ///< [IN] SMS text.
916  le_sms_CallbackResultFunc_t handlerPtr,
917  ///< [IN] CallBack for sending result.
918  void* contextPtr
919  ///< [IN]
920 );
921 
922 //--------------------------------------------------------------------------------------------------
923 /**
924  * Create and asynchronously send a PDU message.
925  *
926  * @return
927  * - le_sms_Msg Reference to the new Message object pooled.
928  * - NULL Not possible to pool a new message.
929  *
930  */
931 //--------------------------------------------------------------------------------------------------
933 (
934  const uint8_t* pduPtr,
935  ///< [IN] PDU message.
936  size_t pduSize,
937  ///< [IN]
938  le_sms_CallbackResultFunc_t handlerPtr,
939  ///< [IN] CallBack for sending result.
940  void* contextPtr
941  ///< [IN]
942 );
943 
944 //--------------------------------------------------------------------------------------------------
945 /**
946  * Delete a Message data structure.
947  *
948  * It deletes the Message data structure and all the allocated memory is freed. If several
949  * users own the Message object (e.g., several handler functions registered for
950  * SMS message reception), the Message object will only be deleted if one User
951  * owns the Message object.
952  *
953  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
954  * function will not return.
955  */
956 //--------------------------------------------------------------------------------------------------
957 void le_sms_Delete
958 (
959  le_sms_MsgRef_t msgRef
960  ///< [IN] Reference to the message object.
961 );
962 
963 //--------------------------------------------------------------------------------------------------
964 /**
965  * Get the message format.
966  *
967  * @return Message format.
968  *
969  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
970  * function will not return.
971  *
972  */
973 //--------------------------------------------------------------------------------------------------
975 (
976  le_sms_MsgRef_t msgRef
977  ///< [IN] Reference to the message object.
978 );
979 
980 //--------------------------------------------------------------------------------------------------
981 /**
982  * Get the message type.
983  *
984  * @return Message type.
985  *
986  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
987  * function will not return.
988  */
989 //--------------------------------------------------------------------------------------------------
991 (
992  le_sms_MsgRef_t msgRef
993  ///< [IN] Reference to the message object.
994 );
995 
996 //--------------------------------------------------------------------------------------------------
997 /**
998  * Get the Cell Broadcast Message Identifier.
999  *
1000  * @return
1001  * - LE_FAULT Message is not a cell broadcast type.
1002  * - LE_OK Function succeeded.
1003  *
1004  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1005  * function will not return.
1006  */
1007 //--------------------------------------------------------------------------------------------------
1009 (
1010  le_sms_MsgRef_t msgRef,
1011  ///< [IN] Reference to the message object.
1012  uint16_t* messageIdPtr
1013  ///< [OUT] Cell Broadcast Message Identifier.
1014 );
1015 
1016 //--------------------------------------------------------------------------------------------------
1017 /**
1018  * Get the Cell Broadcast Message Serial Number.
1019  *
1020  * @return
1021  * - LE_FAULT Message is not a cell broadcast type.
1022  * - LE_OK Function succeeded.
1023  *
1024  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1025  * function will not return.
1026  */
1027 //--------------------------------------------------------------------------------------------------
1029 (
1030  le_sms_MsgRef_t msgRef,
1031  ///< [IN] Reference to the message object.
1032  uint16_t* serialNumberPtr
1033  ///< [OUT] Cell Broadcast Serial Number.
1034 );
1035 
1036 //--------------------------------------------------------------------------------------------------
1037 /**
1038  * Get the Sender Telephone number.
1039  *
1040  * Output parameter is updated with the Telephone number. If the Telephone number string exceeds
1041  * the value of 'len' parameter, LE_OVERFLOW error code is returned and 'tel' is filled until
1042  * 'len-1' characters and a null-character is implicitly appended at the end of 'tel'.
1043  *
1044  * @return LE_NOT_PERMITTED Message is not a received message.
1045  * @return LE_OVERFLOW Telephone number length exceed the maximum length.
1046  * @return LE_OK Function succeeded.
1047  *
1048  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1049  * function will not return.
1050  */
1051 //--------------------------------------------------------------------------------------------------
1053 (
1054  le_sms_MsgRef_t msgRef,
1055  ///< [IN] Reference to the message object.
1056  char* tel,
1057  ///< [OUT] Telephone number string.
1058  size_t telSize
1059  ///< [IN]
1060 );
1061 
1062 //--------------------------------------------------------------------------------------------------
1063 /**
1064  * Get the Service Center Time Stamp string.
1065  *
1066  * Output parameter is updated with the Time Stamp string. If the Time Stamp string exceeds the
1067  * value of 'len' parameter, a LE_OVERFLOW error code is returned and 'timestamp' is filled until
1068  * 'len-1' characters and a null-character is implicitly appended at the end of 'timestamp'.
1069  *
1070  * @return LE_NOT_PERMITTED Message is not a received message.
1071  * @return LE_OVERFLOW Timestamp number length exceed the maximum length.
1072  * @return LE_OK Function succeeded.
1073  *
1074  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1075  * function will not return.
1076  */
1077 //--------------------------------------------------------------------------------------------------
1079 (
1080  le_sms_MsgRef_t msgRef,
1081  ///< [IN] Reference to the message object.
1082  char* timestamp,
1083  ///< [OUT] Message time stamp (in text mode).
1084  ///< string format: "yy/MM/dd,hh:mm:ss+/-zz"
1085  ///< (Year/Month/Day,Hour:Min:Seconds+/-TimeZone)
1086  ///< The time zone indicates the difference, expressed
1087  ///< in quarters of an hours between the local time
1088  ///< and GMT.
1089  size_t timestampSize
1090  ///< [IN]
1091 );
1092 
1093 //--------------------------------------------------------------------------------------------------
1094 /**
1095  * Get the message Length value.
1096  *
1097  * @return Number of characters for text and UCS2 messages, or the length of the data in bytes for
1098  * raw binary messages.
1099  *
1100  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1101  * function will not return.
1102  */
1103 //--------------------------------------------------------------------------------------------------
1104 size_t le_sms_GetUserdataLen
1105 (
1106  le_sms_MsgRef_t msgRef
1107  ///< [IN] Reference to the message object.
1108 );
1109 
1110 //--------------------------------------------------------------------------------------------------
1111 /**
1112  * Get the text Message.
1113  *
1114  * Output parameter is updated with the text string encoded in ASCII format. If the text string
1115  * exceeds the value of 'len' parameter, LE_OVERFLOW error code is returned and 'text' is filled
1116  * until 'len-1' characters and a null-character is implicitly appended at the end of 'text'.
1117  *
1118  * @return LE_OVERFLOW Message length exceed the maximum length.
1119  * @return LE_OK Function succeeded.
1120  *
1121  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1122  * function will not return.
1123  */
1124 //--------------------------------------------------------------------------------------------------
1126 (
1127  le_sms_MsgRef_t msgRef,
1128  ///< [IN] Reference to the message object.
1129  char* text,
1130  ///< [OUT] SMS text.
1131  size_t textSize
1132  ///< [IN]
1133 );
1134 
1135 //--------------------------------------------------------------------------------------------------
1136 /**
1137  * Get the binary Message.
1138  *
1139  * Output parameters are updated with the binary message content and the length of the raw
1140  * binary message in bytes. If the binary data exceed the value of 'len' input parameter, a
1141  * LE_OVERFLOW error code is returned and 'raw' is filled until 'len' bytes.
1142  *
1143  * @return LE_FORMAT_ERROR Message is not in binary format
1144  * @return LE_OVERFLOW Message length exceed the maximum length.
1145  * @return LE_OK Function succeeded.
1146  *
1147  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1148  * function will not return.
1149  */
1150 //--------------------------------------------------------------------------------------------------
1152 (
1153  le_sms_MsgRef_t msgRef,
1154  ///< [IN] Reference to the message object.
1155  uint8_t* binPtr,
1156  ///< [OUT] Binary message.
1157  size_t* binSizePtr
1158  ///< [INOUT]
1159 );
1160 
1161 //--------------------------------------------------------------------------------------------------
1162 /**
1163  * Get the UCS2 Message (16-bit format).
1164  *
1165  * Output parameters are updated with the UCS2 message content and the number of characters. If
1166  * the UCS2 data exceed the value of the length input parameter, a LE_OVERFLOW error
1167  * code is returned and 'ucs2Ptr' is filled until of the number of chars specified.
1168  *
1169  * @return
1170  * - LE_FORMAT_ERROR Message is not in binary format
1171  * - LE_OVERFLOW Message length exceed the maximum length.
1172  * - LE_OK Function succeeded.
1173  *
1174  */
1175 //--------------------------------------------------------------------------------------------------
1177 (
1178  le_sms_MsgRef_t msgRef,
1179  ///< [IN] Reference to the message object.
1180  uint16_t* ucs2Ptr,
1181  ///< [OUT] UCS2 message.
1182  size_t* ucs2SizePtr
1183  ///< [INOUT]
1184 );
1185 
1186 //--------------------------------------------------------------------------------------------------
1187 /**
1188  * Get the PDU message.
1189  *
1190  * Output parameters are updated with the PDU message content and the length of the PDU message
1191  * in bytes. If the PDU data exceed the value of 'len' input parameter, a LE_OVERFLOW error code is
1192  * returned and 'pdu' is filled until 'len' bytes.
1193  *
1194  * @return LE_FORMAT_ERROR Unable to encode the message in PDU (only for outgoing messages).
1195  * @return LE_OVERFLOW Message length exceed the maximum length.
1196  * @return LE_OK Function succeeded.
1197  *
1198  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1199  * function will not return.
1200  */
1201 //--------------------------------------------------------------------------------------------------
1203 (
1204  le_sms_MsgRef_t msgRef,
1205  ///< [IN] Reference to the message object.
1206  uint8_t* pduPtr,
1207  ///< [OUT] PDU message.
1208  size_t* pduSizePtr
1209  ///< [INOUT]
1210 );
1211 
1212 //--------------------------------------------------------------------------------------------------
1213 /**
1214  * Get the message Length value.
1215  *
1216  * @return Length of the data in bytes of the PDU message.
1217  *
1218  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1219  * function will not return.
1220  */
1221 //--------------------------------------------------------------------------------------------------
1222 size_t le_sms_GetPDULen
1223 (
1224  le_sms_MsgRef_t msgRef
1225  ///< [IN] Reference to the message object.
1226 );
1227 
1228 //--------------------------------------------------------------------------------------------------
1229 /**
1230  * Delete an SMS message from the storage area.
1231  *
1232  * Verifies first if the parameter is valid, then it checks the modem state can support
1233  * message deleting.
1234  *
1235  * @return LE_FAULT Function failed to perform the deletion.
1236  * @return LE_NO_MEMORY The message is not present in storage area.
1237  * @return LE_OK Function succeeded.
1238  *
1239  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1240  * function will not return.
1241  */
1242 //--------------------------------------------------------------------------------------------------
1244 (
1245  le_sms_MsgRef_t msgRef
1246  ///< [IN] Reference to the message object.
1247 );
1248 
1249 //--------------------------------------------------------------------------------------------------
1250 /**
1251  * Create an object's reference of the list of received messages
1252  * saved in the SMS message storage area.
1253  *
1254  * @return
1255  * Reference to the List object. Null pointer if no messages have been retrieved.
1256  */
1257 //--------------------------------------------------------------------------------------------------
1259 (
1260  void
1261 );
1262 
1263 //--------------------------------------------------------------------------------------------------
1264 /**
1265  * Delete the list of the Messages retrieved from the message
1266  * storage.
1267  *
1268  * @note
1269  * On failure, the process exits, so you don't have to worry about checking the returned
1270  * reference for validity.
1271  */
1272 //--------------------------------------------------------------------------------------------------
1273 void le_sms_DeleteList
1274 (
1275  le_sms_MsgListRef_t msgListRef
1276  ///< [IN] Messages list.
1277 );
1278 
1279 //--------------------------------------------------------------------------------------------------
1280 /**
1281  * Get the first Message object reference in the list of messages
1282  * retrieved with le_sms_CreateRxMsgList().
1283  *
1284  * @return NULL No message found.
1285  * @return Msg Message object reference.
1286  *
1287  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1288  * function will not return.
1289  */
1290 //--------------------------------------------------------------------------------------------------
1292 (
1293  le_sms_MsgListRef_t msgListRef
1294  ///< [IN] Messages list.
1295 );
1296 
1297 //--------------------------------------------------------------------------------------------------
1298 /**
1299  * Get the next Message object reference in the list of messages
1300  * retrieved with le_sms_CreateRxMsgList().
1301  *
1302  * @return NULL No message found.
1303  * @return Msg Message object reference.
1304  *
1305  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1306  * function will not return.
1307  */
1308 //--------------------------------------------------------------------------------------------------
1310 (
1311  le_sms_MsgListRef_t msgListRef
1312  ///< [IN] Messages list.
1313 );
1314 
1315 //--------------------------------------------------------------------------------------------------
1316 /**
1317  * Read the Message status (Received Read, Received Unread, Stored
1318  * Sent, Stored Unsent).
1319  *
1320  * @return Status of the message.
1321  *
1322  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1323  * function will not return.
1324  */
1325 //--------------------------------------------------------------------------------------------------
1327 (
1328  le_sms_MsgRef_t msgRef
1329  ///< [IN] Messages list.
1330 );
1331 
1332 //--------------------------------------------------------------------------------------------------
1333 /**
1334  * Mark a message as 'read'.
1335  *
1336  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1337  * function will not return.
1338  */
1339 //--------------------------------------------------------------------------------------------------
1340 void le_sms_MarkRead
1341 (
1342  le_sms_MsgRef_t msgRef
1343  ///< [IN] Messages list.
1344 );
1345 
1346 //--------------------------------------------------------------------------------------------------
1347 /**
1348  * Mark a message as 'unread'.
1349  *
1350  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1351  * function will not return.
1352  */
1353 //--------------------------------------------------------------------------------------------------
1354 void le_sms_MarkUnread
1355 (
1356  le_sms_MsgRef_t msgRef
1357  ///< [IN] Messages list.
1358 );
1359 
1360 //--------------------------------------------------------------------------------------------------
1361 /**
1362  * Get the SMS center address.
1363  *
1364  * Output parameter is updated with the SMS Service center address. If the Telephone number string exceeds
1365  * the value of 'len' parameter, LE_OVERFLOW error code is returned and 'tel' is filled until
1366  * 'len-1' characters and a null-character is implicitly appended at the end of 'tel'.
1367  *
1368  * @return
1369  * - LE_FAULT Service is not available.
1370  * - LE_OVERFLOW Telephone number length exceed the maximum length.
1371  * - LE_OK Function succeeded.
1372  *
1373  */
1374 //--------------------------------------------------------------------------------------------------
1376 (
1377  char* tel,
1378  ///< [OUT] SMS center address number string.
1379  size_t telSize
1380  ///< [IN]
1381 );
1382 
1383 //--------------------------------------------------------------------------------------------------
1384 /**
1385  * Set the SMS center address.
1386  *
1387  * SMS center address number is defined in ITU-T recommendations E.164/E.163.
1388  * E.164 numbers can have a maximum of fifteen digits and are usually written with a '+' prefix.
1389  *
1390  * @return
1391  * - LE_FAULT Service is not available..
1392  * - LE_OK Function succeeded.
1393  *
1394  * @note If the SMS center address number is too long (max LE_MDMDEFS_PHONE_NUM_MAX_LEN digits), it
1395  * is a fatal error, the function will not return.
1396  */
1397 //--------------------------------------------------------------------------------------------------
1399 (
1400  const char* LE_NONNULL tel
1401  ///< [IN] SMS center address number string.
1402 );
1403 
1404 //--------------------------------------------------------------------------------------------------
1405 /**
1406  * Set the preferred SMS storage for incoming messages.
1407  * @return
1408  * - LE_FAULT Function failed.
1409  * - LE_OK Function succeeded.
1410  */
1411 //--------------------------------------------------------------------------------------------------
1413 (
1414  le_sms_Storage_t prefStorage
1415  ///< [IN] storage parameter.
1416 );
1417 
1418 //--------------------------------------------------------------------------------------------------
1419 /**
1420  * Get the preferred SMS storage for incoming messages.
1421  * @return
1422  * - LE_FAULT Function failed.
1423  * - LE_OK Function succeeded.
1424  */
1425 //--------------------------------------------------------------------------------------------------
1427 (
1428  le_sms_Storage_t* prefStoragePtr
1429  ///< [OUT] storage parameter.
1430 );
1431 
1432 //--------------------------------------------------------------------------------------------------
1433 /**
1434  * Activate Cell Broadcast message notification
1435  *
1436  * @return
1437  * - LE_FAULT Function failed.
1438  * - LE_OK Function succeeded.
1439  */
1440 //--------------------------------------------------------------------------------------------------
1442 (
1443  void
1444 );
1445 
1446 //--------------------------------------------------------------------------------------------------
1447 /**
1448  * Deactivate Cell Broadcast message notification
1449  *
1450  * @return
1451  * - LE_FAULT Function failed.
1452  * - LE_OK Function succeeded.
1453  */
1454 //--------------------------------------------------------------------------------------------------
1456 (
1457  void
1458 );
1459 
1460 //--------------------------------------------------------------------------------------------------
1461 /**
1462  * Activate CDMA Cell Broadcast message notification
1463  *
1464  * @return
1465  * - LE_FAULT Function failed.
1466  * - LE_OK Function succeeded.
1467  */
1468 //--------------------------------------------------------------------------------------------------
1470 (
1471  void
1472 );
1473 
1474 //--------------------------------------------------------------------------------------------------
1475 /**
1476  * Deactivate CDMA Cell Broadcast message notification
1477  *
1478  * @return
1479  * - LE_FAULT Function failed.
1480  * - LE_OK Function succeeded.
1481  */
1482 //--------------------------------------------------------------------------------------------------
1484 (
1485  void
1486 );
1487 
1488 //--------------------------------------------------------------------------------------------------
1489 /**
1490  * Add Cell Broadcast message Identifiers range.
1491  *
1492  * @return
1493  * - LE_FAULT Function failed.
1494  * - LE_OK Function succeeded.
1495  */
1496 //--------------------------------------------------------------------------------------------------
1498 (
1499  uint16_t fromId,
1500  ///< [IN] Starting point of the range of cell broadcast message identifier.
1501  uint16_t toId
1502  ///< [IN] Ending point of the range of cell broadcast message identifier.
1503 );
1504 
1505 //--------------------------------------------------------------------------------------------------
1506 /**
1507  * Remove Cell Broadcast message Identifiers range.
1508  *
1509  * @return
1510  * - LE_FAULT Function failed.
1511  * - LE_OK Function succeeded.
1512  */
1513 //--------------------------------------------------------------------------------------------------
1515 (
1516  uint16_t fromId,
1517  ///< [IN] Starting point of the range of cell broadcast message identifier.
1518  uint16_t toId
1519  ///< [IN] Ending point of the range of cell broadcast message identifier.
1520 );
1521 
1522 //--------------------------------------------------------------------------------------------------
1523 /**
1524  * Clear Cell Broadcast message Identifiers.
1525  *
1526  * @return
1527  * - LE_FAULT Function failed.
1528  * - LE_OK Function succeeded.
1529  */
1530 //--------------------------------------------------------------------------------------------------
1532 (
1533  void
1534 );
1535 
1536 //--------------------------------------------------------------------------------------------------
1537 /**
1538  * Add CDMA Cell Broadcast category services.
1539  *
1540  * @return
1541  * - LE_FAULT Function failed.
1542  * - LE_BAD_PARAMETER Parameter is invalid.
1543  * - LE_OK Function succeeded.
1544  */
1545 //--------------------------------------------------------------------------------------------------
1547 (
1548  le_sms_CdmaServiceCat_t serviceCat,
1549  ///< [IN] Service category assignment. Reference to 3GPP2 C.R1001-D
1550  ///< v1.0 Section 9.3.1 Standard Service Category Assignments.
1551  le_sms_Languages_t language
1552  ///< [IN] Language Indicator. Reference to
1553  ///< 3GPP2 C.R1001-D v1.0 Section 9.2.1 Language Indicator
1554  ///< Value Assignments
1555 );
1556 
1557 //--------------------------------------------------------------------------------------------------
1558 /**
1559  * Remove CDMA Cell Broadcast category services.
1560  *
1561  * @return
1562  * - LE_FAULT Function failed.
1563  * - LE_BAD_PARAMETER Parameter is invalid.
1564  * - LE_OK Function succeeded.
1565  */
1566 //--------------------------------------------------------------------------------------------------
1568 (
1569  le_sms_CdmaServiceCat_t serviceCat,
1570  ///< [IN] Service category assignment. Reference to 3GPP2 C.R1001-D
1571  ///< v1.0 Section 9.3.1 Standard Service Category Assignments.
1572  le_sms_Languages_t language
1573  ///< [IN] Language Indicator. Reference to
1574  ///< 3GPP2 C.R1001-D v1.0 Section 9.2.1 Language Indicator
1575  ///< Value Assignments
1576 );
1577 
1578 //--------------------------------------------------------------------------------------------------
1579 /**
1580  * Clear CDMA Cell Broadcast category services.
1581  *
1582  * @return
1583  * - LE_FAULT Function failed.
1584  * - LE_OK Function succeeded.
1585  */
1586 //--------------------------------------------------------------------------------------------------
1588 (
1589  void
1590 );
1591 
1592 //--------------------------------------------------------------------------------------------------
1593 /**
1594  * Get the number of messages successfully received or sent since last counter reset.
1595  *
1596  * @return
1597  * - LE_OK Function succeeded.
1598  * - LE_BAD_PARAMETER A parameter is invalid.
1599  *
1600  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1601  * function will not return.
1602  */
1603 //--------------------------------------------------------------------------------------------------
1605 (
1606  le_sms_Type_t messageType,
1607  ///< [IN] Message type
1608  int32_t* messageCountPtr
1609  ///< [OUT] Number of messages
1610 );
1611 
1612 //--------------------------------------------------------------------------------------------------
1613 /**
1614  * Start to count the messages successfully received and sent.
1615  */
1616 //--------------------------------------------------------------------------------------------------
1617 void le_sms_StartCount
1618 (
1619  void
1620 );
1621 
1622 //--------------------------------------------------------------------------------------------------
1623 /**
1624  * Stop to count the messages successfully received and sent.
1625  */
1626 //--------------------------------------------------------------------------------------------------
1627 void le_sms_StopCount
1628 (
1629  void
1630 );
1631 
1632 //--------------------------------------------------------------------------------------------------
1633 /**
1634  * Reset the count of messages successfully received and sent.
1635  */
1636 //--------------------------------------------------------------------------------------------------
1637 void le_sms_ResetCount
1638 (
1639  void
1640 );
1641 
1642 //--------------------------------------------------------------------------------------------------
1643 /**
1644  * Enable SMS Status Report for outgoing messages.
1645  *
1646  * @return
1647  * - LE_OK Function succeeded.
1648  * - LE_FAULT Function failed.
1649  */
1650 //--------------------------------------------------------------------------------------------------
1652 (
1653  void
1654 );
1655 
1656 //--------------------------------------------------------------------------------------------------
1657 /**
1658  * Disable SMS Status Report for outgoing messages.
1659  *
1660  * @return
1661  * - LE_OK Function succeeded.
1662  * - LE_FAULT Function failed.
1663  */
1664 //--------------------------------------------------------------------------------------------------
1666 (
1667  void
1668 );
1669 
1670 //--------------------------------------------------------------------------------------------------
1671 /**
1672  * Get SMS Status Report activation state.
1673  *
1674  * @return
1675  * - LE_OK Function succeeded.
1676  * - LE_BAD_PARAMETER Parameter is invalid.
1677  * - LE_FAULT Function failed.
1678  */
1679 //--------------------------------------------------------------------------------------------------
1681 (
1682  bool* enabledPtr
1683  ///< [OUT] True when SMS Status Report is enabled, false otherwise.
1684 );
1685 
1686 //--------------------------------------------------------------------------------------------------
1687 /**
1688  * Get TP-Message-Reference of a message. Message type should be either a SMS Status Report or an
1689  * outgoing SMS.
1690  * TP-Message-Reference is defined in 3GPP TS 23.040 section 9.2.3.6.
1691  *
1692  * @return
1693  * - LE_OK Function succeeded.
1694  * - LE_BAD_PARAMETER Parameter is invalid.
1695  * - LE_FAULT Function failed.
1696  * - LE_UNAVAILABLE Outgoing SMS message is not sent.
1697  */
1698 //--------------------------------------------------------------------------------------------------
1700 (
1701  le_sms_MsgRef_t msgRef,
1702  ///< [IN] Reference to the message object.
1703  uint8_t* tpMrPtr
1704  ///< [OUT] 3GPP TS 23.040 TP-Message-Reference.
1705 );
1706 
1707 //--------------------------------------------------------------------------------------------------
1708 /**
1709  * Get TP-Recipient-Address of SMS Status Report.
1710  * TP-Recipient-Address is defined in 3GPP TS 23.040 section 9.2.3.14.
1711  * TP-Recipient-Address Type-of-Address is defined in 3GPP TS 24.011 section 8.2.5.2.
1712  *
1713  * @return
1714  * - LE_OK Function succeeded.
1715  * - LE_BAD_PARAMETER A parameter is invalid.
1716  * - LE_OVERFLOW The Recipient Address length exceeds the length of the provided buffer.
1717  * - LE_FAULT Function failed.
1718  */
1719 //--------------------------------------------------------------------------------------------------
1721 (
1722  le_sms_MsgRef_t msgRef,
1723  ///< [IN] Reference to the message object.
1724  uint8_t* toraPtr,
1725  ///< [OUT] 3GPP TS 24.011 TP-Recipient-Address
1726  ///< Type-of-Address.
1727  char* ra,
1728  ///< [OUT] 3GPP TS 23.040 TP-Recipient-Address.
1729  size_t raSize
1730  ///< [IN]
1731 );
1732 
1733 //--------------------------------------------------------------------------------------------------
1734 /**
1735  * Get TP-Service-Centre-Time-Stamp of SMS Status Report.
1736  * TP-Service-Centre-Time-Stamp is defined in 3GPP TS 23.040 section 9.2.3.11.
1737  *
1738  * @return
1739  * - LE_OK Function succeeded.
1740  * - LE_BAD_PARAMETER A parameter is invalid.
1741  * - LE_OVERFLOW The SC Timestamp length exceeds the length of the provided buffer.
1742  * - LE_FAULT Function failed.
1743  */
1744 //--------------------------------------------------------------------------------------------------
1746 (
1747  le_sms_MsgRef_t msgRef,
1748  ///< [IN] Reference to the message object.
1749  char* scts,
1750  ///< [OUT] 3GPP TS 23.040 TP-Service-Centre-Time-Stamp.
1751  size_t sctsSize
1752  ///< [IN]
1753 );
1754 
1755 //--------------------------------------------------------------------------------------------------
1756 /**
1757  * Get TP-Discharge-Time of SMS Status Report.
1758  * TP-Discharge-Time is defined in 3GPP TS 23.040 section 9.2.3.13.
1759  *
1760  * @return
1761  * - LE_OK Function succeeded.
1762  * - LE_BAD_PARAMETER A parameter is invalid.
1763  * - LE_OVERFLOW The Discharge Time length exceeds the length of the provided buffer.
1764  * - LE_FAULT Function failed.
1765  */
1766 //--------------------------------------------------------------------------------------------------
1768 (
1769  le_sms_MsgRef_t msgRef,
1770  ///< [IN] Reference to the message object.
1771  char* dt,
1772  ///< [OUT] 3GPP TS 23.040 TP-Discharge-Time.
1773  size_t dtSize
1774  ///< [IN]
1775 );
1776 
1777 //--------------------------------------------------------------------------------------------------
1778 /**
1779  * Get TP-Status of SMS Status Report.
1780  * TP-Status is defined in 3GPP TS 23.040 section 9.2.3.15.
1781  *
1782  * @return
1783  * - LE_OK Function succeeded.
1784  * - LE_BAD_PARAMETER A parameter is invalid.
1785  * - LE_FAULT Function failed.
1786  */
1787 //--------------------------------------------------------------------------------------------------
1789 (
1790  le_sms_MsgRef_t msgRef,
1791  ///< [IN] Reference to the message object.
1792  uint8_t* stPtr
1793  ///< [OUT] 3GPP TS 23.040 TP-Status.
1794 );
1795 
1796 /** @} **/
1797 
1798 #endif // LE_SMS_INTERFACE_H_INCLUDE_GUARD
le_result_t le_sms_ActivateCellBroadcast(void)
le_result_t le_sms_ClearCdmaCellBroadcastServices(void)
void le_sms_RemoveFullStorageEventHandler(le_sms_FullStorageEventHandlerRef_t handlerRef)
void le_sms_GetErrorCode(le_sms_MsgRef_t msgRef, le_sms_ErrorCode_t *rpCausePtr, le_sms_ErrorCode_t *tpCausePtr)
le_sms_MsgRef_t le_sms_SendPdu(const uint8_t *pduPtr, size_t pduSize, le_sms_CallbackResultFunc_t handlerPtr, void *contextPtr)
le_sms_MsgRef_t le_sms_GetNext(le_sms_MsgListRef_t msgListRef)
le_result_t
Definition: le_basics.h:46
le_result_t le_sms_AddCellBroadcastIds(uint16_t fromId, uint16_t toId)
le_result_t le_sms_DeactivateCdmaCellBroadcast(void)
le_result_t le_sms_GetCellBroadcastSerialNumber(le_sms_MsgRef_t msgRef, uint16_t *serialNumberPtr)
le_sms_MsgRef_t le_sms_GetFirst(le_sms_MsgListRef_t msgListRef)
size_t le_sms_GetUserdataLen(le_sms_MsgRef_t msgRef)
LE_FULL_API void le_sms_SetServerDisconnectHandler(le_sms_DisconnectHandler_t disconnectHandler, void *contextPtr)
void(* le_sms_DisconnectHandler_t)(void *)
Definition: le_sms_interface.h:407
le_result_t le_sms_GetUCS2(le_sms_MsgRef_t msgRef, uint16_t *ucs2Ptr, size_t *ucs2SizePtr)
le_result_t le_sms_ClearCellBroadcastIds(void)
le_sms_Status_t
Definition: le_sms_common.h:149
void le_sms_Delete(le_sms_MsgRef_t msgRef)
void le_sms_DeleteList(le_sms_MsgListRef_t msgListRef)
void le_sms_ConnectService(void)
void le_sms_DisconnectService(void)
le_sms_Format_t le_sms_GetFormat(le_sms_MsgRef_t msgRef)
struct le_sms_RxMessageHandler * le_sms_RxMessageHandlerRef_t
Definition: le_sms_common.h:537
le_result_t le_sms_GetBinary(le_sms_MsgRef_t msgRef, uint8_t *binPtr, size_t *binSizePtr)
le_result_t le_sms_GetCount(le_sms_Type_t messageType, int32_t *messageCountPtr)
le_result_t le_sms_GetPDU(le_sms_MsgRef_t msgRef, uint8_t *pduPtr, size_t *pduSizePtr)
le_sms_MsgRef_t le_sms_Create(void)
le_result_t le_sms_SetPDU(le_sms_MsgRef_t msgRef, const uint8_t *pduPtr, size_t pduSize)
struct le_sms_Msg * le_sms_MsgRef_t
Definition: le_sms_common.h:521
le_result_t le_sms_Send(le_sms_MsgRef_t msgRef)
void le_sms_StartCount(void)
le_result_t le_sms_SendAsync(le_sms_MsgRef_t msgRef, le_sms_CallbackResultFunc_t handlerPtr, void *contextPtr)
le_sms_FullStorageEventHandlerRef_t le_sms_AddFullStorageEventHandler(le_sms_FullStorageHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_sms_GetTpMr(le_sms_MsgRef_t msgRef, uint8_t *tpMrPtr)
le_result_t le_sms_RemoveCdmaCellBroadcastServices(le_sms_CdmaServiceCat_t serviceCat, le_sms_Languages_t language)
le_result_t le_sms_SetUCS2(le_sms_MsgRef_t msgRef, const uint16_t *ucs2Ptr, size_t ucs2Size)
le_result_t le_sms_GetPreferredStorage(le_sms_Storage_t *prefStoragePtr)
le_sms_ErrorCode3GPP2_t
Definition: le_sms_common.h:305
int32_t le_sms_GetPlatformSpecificErrorCode(le_sms_MsgRef_t msgRef)
void le_sms_StopCount(void)
le_result_t le_sms_AddCdmaCellBroadcastServices(le_sms_CdmaServiceCat_t serviceCat, le_sms_Languages_t language)
size_t le_sms_GetPDULen(le_sms_MsgRef_t msgRef)
le_result_t le_sms_TryConnectService(void)
le_result_t le_sms_ActivateCdmaCellBroadcast(void)
le_sms_Storage_t
Definition: le_sms_common.h:288
le_sms_Type_t le_sms_GetType(le_sms_MsgRef_t msgRef)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_sms_Type_t
Definition: le_sms_common.h:130
le_result_t le_sms_GetText(le_sms_MsgRef_t msgRef, char *text, size_t textSize)
le_result_t le_sms_RemoveCellBroadcastIds(uint16_t fromId, uint16_t toId)
le_sms_MsgListRef_t le_sms_CreateRxMsgList(void)
le_result_t le_sms_SetPreferredStorage(le_sms_Storage_t prefStorage)
le_result_t le_sms_GetSmsCenterAddress(char *tel, size_t telSize)
le_result_t le_sms_SetText(le_sms_MsgRef_t msgRef, const char *LE_NONNULL text)
le_result_t le_sms_SetDestination(le_sms_MsgRef_t msgRef, const char *LE_NONNULL dest)
le_result_t le_sms_IsStatusReportEnabled(bool *enabledPtr)
le_sms_ErrorCode3GPP2_t le_sms_Get3GPP2ErrorCode(le_sms_MsgRef_t msgRef)
le_result_t le_sms_GetTpRa(le_sms_MsgRef_t msgRef, uint8_t *toraPtr, char *ra, size_t raSize)
le_result_t le_sms_GetTpSt(le_sms_MsgRef_t msgRef, uint8_t *stPtr)
le_result_t le_sms_GetTpScTs(le_sms_MsgRef_t msgRef, char *scts, size_t sctsSize)
le_result_t le_sms_SetSmsCenterAddress(const char *LE_NONNULL tel)
le_result_t le_sms_EnableStatusReport(void)
void(* le_sms_RxMessageHandlerFunc_t)(le_sms_MsgRef_t msgRef, void *contextPtr)
Definition: le_sms_common.h:570
struct le_sms_MsgList * le_sms_MsgListRef_t
Definition: le_sms_common.h:529
le_result_t le_sms_GetSenderTel(le_sms_MsgRef_t msgRef, char *tel, size_t telSize)
le_result_t le_sms_DisableStatusReport(void)
le_sms_ErrorCode_t
Definition: le_sms_common.h:402
void le_sms_RemoveRxMessageHandler(le_sms_RxMessageHandlerRef_t handlerRef)
void le_sms_ResetCount(void)
void le_sms_MarkRead(le_sms_MsgRef_t msgRef)
le_result_t le_sms_SetBinary(le_sms_MsgRef_t msgRef, const uint8_t *binPtr, size_t binSize)
void le_sms_MarkUnread(le_sms_MsgRef_t msgRef)
le_result_t le_sms_GetTpDt(le_sms_MsgRef_t msgRef, char *dt, size_t dtSize)
le_sms_Status_t le_sms_GetStatus(le_sms_MsgRef_t msgRef)
le_result_t le_sms_DeactivateCellBroadcast(void)
void(* le_sms_FullStorageHandlerFunc_t)(le_sms_Storage_t storage, void *contextPtr)
Definition: le_sms_common.h:584
le_result_t le_sms_GetCellBroadcastId(le_sms_MsgRef_t msgRef, uint16_t *messageIdPtr)
le_result_t le_sms_GetTimeStamp(le_sms_MsgRef_t msgRef, char *timestamp, size_t timestampSize)
le_sms_Format_t
Definition: le_sms_common.h:109
le_sms_RxMessageHandlerRef_t le_sms_AddRxMessageHandler(le_sms_RxMessageHandlerFunc_t handlerPtr, void *contextPtr)
le_sms_MsgRef_t le_sms_SendText(const char *LE_NONNULL destStr, const char *LE_NONNULL textStr, le_sms_CallbackResultFunc_t handlerPtr, void *contextPtr)
void(* le_sms_CallbackResultFunc_t)(le_sms_MsgRef_t msgRef, le_sms_Status_t status, void *contextPtr)
Definition: le_sms_common.h:554
struct le_sms_FullStorageEventHandler * le_sms_FullStorageEventHandlerRef_t
Definition: le_sms_common.h:545
le_sms_CdmaServiceCat_t
Definition: le_sms_common.h:209
le_result_t le_sms_DeleteFromStorage(le_sms_MsgRef_t msgRef)
le_sms_Languages_t
Definition: le_sms_common.h:180