swi_sms.h File Reference

This API provides functionalities to send and receive SMS. More...

#include "returncodes.h"

Include dependency graph for swi_sms.h:

Typedefs
typedef enum swi_sms_Format	swi_sms_Format_t
	The encoding format to send the SMS.
typedef rc_ReturnCode_t(*	swi_sms_ReceptionCB_t )(const char *senderPtr, const char *messagePtr)
	SMS reception callback.
typedef void *	swi_sms_regId_t
	Registration identifier.
Enumerations
enum	swi_sms_Format {   SWI_SMS_7BITS,   SWI_SMS_8BITS,   SWI_SMS_UCS2 }
	The encoding format to send the SMS. More...
Functions
rc_ReturnCode_t	swi_sms_Init ()
	Initializes the module.
rc_ReturnCode_t	swi_sms_Destroy ()
	Destroys the Sms library.
rc_ReturnCode_t	swi_sms_Send (const char *recipientPtr, const char *messagePtr, swi_sms_Format_t format)
	Sends an SMS.
rc_ReturnCode_t	swi_sms_Register (swi_sms_ReceptionCB_t callback, const char *senderPatternPtr, const char *messagePatternPtr, swi_sms_regId_t *regIdPtr)
	Registers a callback on SMS reception.
rc_ReturnCode_t	swi_sms_Unregister (swi_sms_regId_t regId)
	Cancels a callback registration on SMS reception.

---

Detailed Description

This API provides functionalities to send and receive SMS.

---

---

Typedef Documentation

typedef enum swi_sms_Format swi_sms_Format_t

The encoding format to send the SMS.

Supported formats depend on network operator. As a SMS payload has a limited size(140 bytes) and each format encode a character on various number of bits, the choice of encoding format impacts the number of characters sent into one SMS.

typedef rc_ReturnCode_t(* swi_sms_ReceptionCB_t)(const char *senderPtr,const char *messagePtr)

SMS reception callback.

String parameters will be released after the callback have returned.

Parameters:

	senderPtr	[IN] phone number of the SMS sender
	messagePtr	[IN] message content

typedef void* swi_sms_regId_t

Registration identifier.

Used to identify an registration so that it can be unregistered afterwards.

---

Enumeration Type Documentation

enum swi_sms_Format

The encoding format to send the SMS.

Supported formats depend on network operator. As a SMS payload has a limited size(140 bytes) and each format encode a character on various number of bits, the choice of encoding format impacts the number of characters sent into one SMS.

Enumerator:

SWI_SMS_7BITS	7 bits format, regular encoding format to send text using GSM 7bit alphabet. 160 characters maximum per message.
SWI_SMS_8BITS	8 bits format, especially useful to send binary payload, not widely supported. 140 characters maximum per message.
SWI_SMS_UCS2	UCS-2 format (i.e. Universal Character Set on 16 bits), useful to send characters of specific alphabet which don't fit on one byte(e.g. Japanese). 70 characters maximum per message.

---

Function Documentation

rc_ReturnCode_t swi_sms_Destroy

(

)

Destroys the Sms library.

Returns:

RC_OK on success

rc_ReturnCode_t swi_sms_Init

(

)

Initializes the module.

A call to init is mandatory to enable SMS library APIs.

Returns:

RC_OK on success

rc_ReturnCode_t swi_sms_Register	(	swi_sms_ReceptionCB_t	callback,
		const char *	senderPatternPtr,
		const char *	messagePatternPtr,
		swi_sms_regId_t *	regIdPtr
	)

Registers a callback on SMS reception.

The callback will be called in a new pthread.

New SMS will be notified if the content (sender or message) of the SMS matches the given patterns.

Returns:

RC_OK on success

Parameters:

callback	[IN] function to be called on sms reception matching both patterns.
senderPatternPtr	[IN] string, regex pattern that matches the sender address, NULL means "no filtering".
messagePatternPtr	[IN] string, regex pattern that matches the message, NULL means "no filtering".
regIdPtr	[OUT] identifier of the registration, to be used to cancel it afterward using SMS_Unregister function.

rc_ReturnCode_t swi_sms_Send	(	const char *	recipientPtr,
		const char *	messagePtr,
		swi_sms_Format_t	format
	)

Sends an SMS.

Returns:

RC_OK on success

RC_SERVICE_UNAVAILABLE when network status made the SMS sending fail

RC_BAD_FORMAT when selected SMS format is not supported.

Parameters:

recipientPtr	[IN] phone number to send the SMS to.
messagePtr	[IN] string containing the message
format	[IN] the format to use to send the message, see SMS_Format for accepted values. Supported formats may differ depending on the hardware and network capabilities.

rc_ReturnCode_t swi_sms_Unregister

(

swi_sms_regId_t

regId

)

Cancels a callback registration on SMS reception.

Returns:

RC_OK on success

Parameters:

regId

[IN] identifier of the registration to cancel, the id returned by previous SMS_Register call.