#include "legato.h"

Macros
#define	LE_SMS_TIMESTAMP_MAX_LEN 21

#define	LE_SMS_TEXT_MAX_LEN 161

#define	LE_SMS_BINARY_MAX_LEN 140

#define	LE_SMS_PDU_MAX_PAYLOAD 140

#define	LE_SMS_PDU_MAX_LEN 176

Typedefs
typedef struct le_sms_Msg *	le_sms_MsgRef_t

typedef struct le_sms_MsgList *	le_sms_MsgListRef_t

typedef struct le_sms_RxMessageHandler *	le_sms_RxMessageHandlerRef_t

typedef void(*	le_sms_RxMessageHandlerFunc_t )(le_sms_MsgRef_t msgRef, void *contextPtr)

Enumerations
enum	le_sms_Format_t { LE_SMS_FORMAT_PDU, LE_SMS_FORMAT_TEXT, LE_SMS_FORMAT_BINARY, LE_SMS_FORMAT_UNKNOWN }

enum	le_sms_Status_t { LE_SMS_RX_READ, LE_SMS_RX_UNREAD, LE_SMS_STORED_SENT, LE_SMS_STORED_UNSENT, LE_SMS_SENT, LE_SMS_UNSENT, LE_SMS_STATUS_UNKNOWN }

Functions
void	le_sms_StartClient (const char *serviceInstanceName)

void	le_sms_StopClient (void)

le_sms_RxMessageHandlerRef_t	le_sms_AddRxMessageHandler (le_sms_RxMessageHandlerFunc_t handlerPtr, void *contextPtr)

void	le_sms_RemoveRxMessageHandler (le_sms_RxMessageHandlerRef_t addHandlerRef)

le_sms_MsgRef_t	le_sms_Create (void)

le_result_t	le_sms_SetDestination (le_sms_MsgRef_t msgRef, const char *dest)

le_result_t	le_sms_SetText (le_sms_MsgRef_t msgRef, const char *text)

le_result_t	le_sms_SetBinary (le_sms_MsgRef_t msgRef, const uint8_t *binPtr, size_t binNumElements)

le_result_t	le_sms_SetPDU (le_sms_MsgRef_t msgRef, const uint8_t *pduPtr, size_t pduNumElements)

le_result_t	le_sms_Send (le_sms_MsgRef_t msgRef)

void	le_sms_Delete (le_sms_MsgRef_t msgRef)

le_sms_Format_t	le_sms_GetFormat (le_sms_MsgRef_t msgRef)

le_result_t	le_sms_GetSenderTel (le_sms_MsgRef_t msgRef, char *tel, size_t telNumElements)

le_result_t	le_sms_GetTimeStamp (le_sms_MsgRef_t msgRef, char *timestamp, size_t timestampNumElements)

size_t	le_sms_GetUserdataLen (le_sms_MsgRef_t msgRef)

le_result_t	le_sms_GetText (le_sms_MsgRef_t msgRef, char *text, size_t textNumElements)

le_result_t	le_sms_GetBinary (le_sms_MsgRef_t msgRef, uint8_t binPtr, size_t binNumElementsPtr)

le_result_t	le_sms_GetPDU (le_sms_MsgRef_t msgRef, uint8_t pduPtr, size_t pduNumElementsPtr)

size_t	le_sms_GetPDULen (le_sms_MsgRef_t msgRef)

le_result_t	le_sms_DeleteFromStorage (le_sms_MsgRef_t msgRef)

le_sms_MsgListRef_t	le_sms_CreateRxMsgList (void)

void	le_sms_DeleteList (le_sms_MsgListRef_t msgListRef)

le_sms_MsgRef_t	le_sms_GetFirst (le_sms_MsgListRef_t msgListRef)

le_sms_MsgRef_t	le_sms_GetNext (le_sms_MsgListRef_t msgListRef)

le_sms_Status_t	le_sms_GetStatus (le_sms_MsgRef_t msgRef)

void	le_sms_MarkRead (le_sms_MsgRef_t msgRef)

void	le_sms_MarkUnread (le_sms_MsgRef_t msgRef)

Detailed Description

Legato SMS Services include file.

Macro Definition Documentation

#define LE_SMS_BINARY_MAX_LEN 140

The raw binary message can be up to 140 bytes long.

#define LE_SMS_PDU_MAX_LEN 176

The PDU message can be up to 36 (header) + 140 (payload) bytes long.

#define LE_SMS_PDU_MAX_PAYLOAD 140

The PDU payload bytes long.

#define LE_SMS_TEXT_MAX_LEN 161

The text message can be up to 160 characters long. One extra byte is added for the null character.

#define LE_SMS_TIMESTAMP_MAX_LEN 21

Time stamp string length. The string format is "yy/MM/dd,hh:mm:ss+/-zz" (Year/Month/Day,Hour:Min:Seconds+/-TimeZone). One extra byte is added for the null character.

Typedef Documentation

typedef struct le_sms_MsgList* le_sms_MsgListRef_t

Opaque type for SMS Message Listing.

typedef struct le_sms_Msg* le_sms_MsgRef_t

Declare a reference type for referring to SMS Message objects.

typedef void(* le_sms_RxMessageHandlerFunc_t)(le_sms_MsgRef_t msgRef, void *contextPtr)

Handler for New Message.

Parameters

msgRef	Message reference.
contextPtr

typedef struct le_sms_RxMessageHandler* le_sms_RxMessageHandlerRef_t

Reference type for le_sms_RxMessageHandler handler ADD/REMOVE functions

Enumeration Type Documentation

enum le_sms_Format_t

Message Format.

Enumerator
LE_SMS_FORMAT_PDU	PDU message format.
LE_SMS_FORMAT_TEXT	Text message format.
LE_SMS_FORMAT_BINARY	Binary message format.
LE_SMS_FORMAT_UNKNOWN	Unknown message format.

enum le_sms_Status_t

Message Status.

Enumerator
LE_SMS_RX_READ	Message present in the message storage has been read.
LE_SMS_RX_UNREAD	Message present in the message storage has not been read.
LE_SMS_STORED_SENT	Message saved in the message storage has been sent.
LE_SMS_STORED_UNSENT	Message saved in the message storage has not been sent.
LE_SMS_SENT	Message has been sent.
LE_SMS_UNSENT	Message has not been sent.
LE_SMS_STATUS_UNKNOWN	Unknown message status.

Function Documentation

le_sms_RxMessageHandlerRef_t le_sms_AddRxMessageHandler	(	le_sms_RxMessageHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

le_sms_RxMessageHandler handler ADD function

Parameters

[in]	handlerPtr
[in]	contextPtr

le_sms_MsgRef_t le_sms_Create ( void )

Create an SMS Message data structure.

Returns: Reference to the new Message object.

Note: On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

le_sms_MsgListRef_t le_sms_CreateRxMsgList ( void )

Create an object's reference of the list of received messages saved in the SMS message storage area.

Returns: Reference to the List object. Null pointer if no messages have been retrieved.

void le_sms_Delete ( le_sms_MsgRef_t msgRef )

Delete a Message data structure.

It deletes the Message data structure and all the allocated memory is freed. If several users own the Message object (e.g., several handler functions registered for SMS message reception), the Message object will only be deleted if one User owns the Message object.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgRef Reference to the message object.

le_result_t le_sms_DeleteFromStorage ( le_sms_MsgRef_t msgRef )

Delete an SMS message from the storage area.

Verifies first if the parameter is valid, then it checks the modem state can support message deleting.

Returns: LE_NOT_POSSIBLE Current modem state does not support message deleting.; LE_FAULT Function failed to perform the deletion.; LE_NO_MEMORY Message storage is not available.; LE_OK Function succeeded.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgRef Reference to the message object.

void le_sms_DeleteList ( le_sms_MsgListRef_t msgListRef )

Delete the list of the Messages retrieved from the message storage.

Note: On failure, the process exits, so you don't have to worry about checking the returned reference for validity.

Parameters

[in] msgListRef Messages list.

le_result_t le_sms_GetBinary	(	le_sms_MsgRef_t	msgRef,
		uint8_t *	binPtr,
		size_t *	binNumElementsPtr
	)

Get the binary Message.

Output parameters are updated with the binary message content and the length of the raw binary message in bytes. If the binary data exceed the value of 'len' input parameter, a LE_OVERFLOW error code is returned and 'raw' is filled until 'len' bytes.

Returns: LE_FORMAT_ERROR Message is not in binary format; LE_OVERFLOW Message length exceed the maximum length.; LE_OK Function succeeded.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in]	msgRef	Reference to the message object.
[out]	binPtr	Binary message.
[in,out]	binNumElementsPtr

le_sms_MsgRef_t le_sms_GetFirst ( le_sms_MsgListRef_t msgListRef )

Get the first Message object reference in the list of messages retrieved with le_sms_CreateRxMsgList().

Returns: NULL No message found.; le_sms_MsgRef_t Message object reference.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgListRef Messages list.

le_sms_Format_t le_sms_GetFormat ( le_sms_MsgRef_t msgRef )

Get the message format (text or PDU).

Returns: Message format.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgRef Reference to the message object.

le_sms_MsgRef_t le_sms_GetNext ( le_sms_MsgListRef_t msgListRef )

Get the next Message object reference in the list of messages retrieved with le_sms_CreateRxMsgList().

Returns: NULL No message found.; le_sms_MsgRef_t Message object reference.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgListRef Messages list.

le_result_t le_sms_GetPDU	(	le_sms_MsgRef_t	msgRef,
		uint8_t *	pduPtr,
		size_t *	pduNumElementsPtr
	)

Get the PDU message.

Output parameters are updated with the PDU message content and the length of the PDU message in bytes. If the PDU data exceed the value of 'len' input parameter, a LE_OVERFLOW error code is returned and 'pdu' is filled until 'len' bytes.

Returns: LE_FORMAT_ERROR Unable to encode the message in PDU.; LE_OVERFLOW Message length exceed the maximum length.; LE_OK Function succeeded.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in]	msgRef	Reference to the message object.
[out]	pduPtr	PDU message.
[in,out]	pduNumElementsPtr

size_t le_sms_GetPDULen ( le_sms_MsgRef_t msgRef )

Get the message Length value.

Returns: Length of the data in bytes of the PDU message.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgRef Reference to the message object.

le_result_t le_sms_GetSenderTel	(	le_sms_MsgRef_t	msgRef,
		char *	tel,
		size_t	telNumElements
	)

Get the Sender Telephone number.

Output parameter is updated with the Telephone number. If the Telephone number string exceeds the value of 'len' parameter, LE_OVERFLOW error code is returned and 'tel' is filled until 'len-1' characters and a null-character is implicitly appended at the end of 'tel'.

Returns: LE_NOT_PERMITTED Message is not a received message.; LE_OVERFLOW Telephone number length exceed the maximum length.; LE_OK Function succeeded.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in]	msgRef	Reference to the message object.
[out]	tel	Telephone number string.
[in]	telNumElements

le_sms_Status_t le_sms_GetStatus ( le_sms_MsgRef_t msgRef )

Read the Message status (Received Read, Received Unread, Stored Sent, Stored Unsent).

Returns: Status of the message.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgRef Messages list.

le_result_t le_sms_GetText	(	le_sms_MsgRef_t	msgRef,
		char *	text,
		size_t	textNumElements
	)

Get the text Message.

Output parameter is updated with the text string. If the text string exceedS the value of 'len' parameter, LE_OVERFLOW error code is returned and 'text' is filled until 'len-1' characters and a null-character is implicitly appended at the end of 'text'.

Returns: LE_OVERFLOW Message length exceed the maximum length.; LE_OK Function succeeded.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in]	msgRef	Reference to the message object.
[out]	text	SMS text.
[in]	textNumElements

le_result_t le_sms_GetTimeStamp	(	le_sms_MsgRef_t	msgRef,
		char *	timestamp,
		size_t	timestampNumElements
	)

Get the Service Center Time Stamp string.

Output parameter is updated with the Time Stamp string. If the Time Stamp string exceeds the value of 'len' parameter, a LE_OVERFLOW error code is returned and 'timestamp' is filled until 'len-1' characters and a null-character is implicitly appended at the end of 'timestamp'.

Returns: LE_NOT_PERMITTED Message is not a received message.; LE_OVERFLOW Timestamp number length exceed the maximum length.; LE_OK Function succeeded.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in]	msgRef	Reference to the message object.
[out]	timestamp	Message time stamp (in text mode). string format: "yy/MM/dd,hh:mm:ss+/-zz" (Year/Month/Day,Hour:Min:Seconds+/-TimeZone)
[in]	timestampNumElements

size_t le_sms_GetUserdataLen ( le_sms_MsgRef_t msgRef )

Get the message Length value.

Returns: Number of characters for text messages, or the length of the data in bytes for raw binary messages.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgRef Reference to the message object.

void le_sms_MarkRead ( le_sms_MsgRef_t msgRef )

Mark a message as 'read'.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgRef Messages list.

void le_sms_MarkUnread ( le_sms_MsgRef_t msgRef )

Mark a message as 'unread'.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgRef Messages list.

void le_sms_RemoveRxMessageHandler ( le_sms_RxMessageHandlerRef_t addHandlerRef )

le_sms_RxMessageHandler handler REMOVE function

Parameters

[in] addHandlerRef

le_result_t le_sms_Send ( le_sms_MsgRef_t msgRef )

Send an SMS message.

Verifies first if the parameters are valid, then it checks the modem state can support message sending.

Returns: LE_NOT_POSSIBLE Current modem state does not support message sending.; LE_FORMAT_ERROR Message content is invalid.; LE_FAULT Function failed to send the message.; LE_OK Function succeeded.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] msgRef Reference to the message object.

le_result_t le_sms_SetBinary	(	le_sms_MsgRef_t	msgRef,
		const uint8_t *	binPtr,
		size_t	binNumElements
	)

Set the binary message content.

Returns: LE_NOT_PERMITTED Message is Read-Only.; LE_BAD_PARAMETER Length of the data is equal to zero.; LE_OK Function succeeded.

Note: If len is too long (max 140 bytes), it is a fatal error, the function will not return.; If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in]	msgRef	Reference to the message object.
[in]	binPtr	Binary data.
[in]	binNumElements

le_result_t le_sms_SetDestination	(	le_sms_MsgRef_t	msgRef,
		const char *	dest
	)

Set the Telephone destination number.

Telephone number is defined in ITU-T recommendations E.164/E.163. E.164 numbers can have a maximum of fifteen digits and are usually written with a '+' prefix.

Returns: LE_NOT_PERMITTED Message is Read-Only.; LE_BAD_PARAMETER Telephone destination number length is equal to zero.; LE_OK Function succeeded.

Note: If telephone destination number is too long (max 17 digits), it is a fatal error, the function will not return.; If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in]	msgRef	Reference to the message object.
[in]	dest	Telephone number string.

le_result_t le_sms_SetPDU	(	le_sms_MsgRef_t	msgRef,
		const uint8_t *	pduPtr,
		size_t	pduNumElements
	)

Set the PDU message content.

Returns: LE_NOT_PERMITTED Message is Read-Only.; LE_BAD_PARAMETER Length of the data is equal to zero.; LE_OK Function succeeded.

Note: If len is too long (max 176 bytes), it is a fatal error, the function will not return.; If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in]	msgRef	Reference to the message object.
[in]	pduPtr	PDU message.
[in]	pduNumElements

le_result_t le_sms_SetText	(	le_sms_MsgRef_t	msgRef,
		const char *	text
	)

This function must be called to set the Text Message content.

Returns: LE_NOT_PERMITTED Message is Read-Only.; LE_BAD_PARAMETER Text message length is equal to zero.; LE_OK Function succeeded.

Note: If message is too long (max 160 digits), it is a fatal error, the function will not return.; If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in]	msgRef	Reference to the message object.
[in]	text	SMS text.

void le_sms_StartClient ( const char * serviceInstanceName )

Start the service for the client main thread

Parameters

[in] serviceInstanceName

void le_sms_StopClient ( void )

Stop the service for the current client thread

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation