libAwtCom_sync.h File Reference

This library provide transparent connection with the ReadyAgent. More...

#include "libAwtCom.h"

Include dependency graph for libAwtCom_sync.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef void(*	AwtOnDataCB )(char *pBuffer, uint32_t size, void *userData)
	Callback type for message reception.
typedef void(*	AwtForceConnectionCB )(AwtStatus status, void *userData)
	Callback type for connection to server notification.
typedef void(*	AwtOnSMSCB )(char *sender, char *message, uint32_t size)
	Callback type for SMS reception.
Functions
AWTCOM_API const char *	AWT_Com_S_Version (void)
	Return the version of this library.
AWTCOM_API AwtStatus	AWT_Com_S_Create (AwtComContext **ppContext, char *pAssetId, void *userData)
	Initialize the library and return a context.
AWTCOM_API AwtStatus	AWT_Com_S_Destroy (AwtComContext *pContext)
	Destroy the library context, and free associated resources.
AWTCOM_API AwtStatus	AWT_Com_S_GetState (AwtComContext *pContext, AwtComState *state)
	Test if the library context is connected to the ReadyAgent.
AWTCOM_API AwtStatus	AWT_Com_S_GetTicketId (AwtComContext *pContext, int32_t *pTicketId)
	Get a new TicketID.
AWTCOM_API AwtStatus	AWT_Com_S_SendData (AwtComContext *pContext, const char *pBuffer, uint32_t size)
	Send a message to the ReadyAgent.
AWTCOM_API AwtStatus	AWT_Com_S_RegisterDataListener (AwtComContext *pContext, AwtOnDataCB onDataCB)
	Register a listener on Data reception.
AWTCOM_API AwtStatus	AWT_Com_S_FreeReceivedData (char *pBuffer)
	Release a previously received message (a message that was retrieved with onDataCB of the above function).
AWTCOM_API AwtStatus	AWT_Com_S_ForceConnectionToServer (AwtComContext *pContext, AwtForceConnectionCB doneCB)
	Tells the ReadyAgent to do a connection with the server, as soon as it can.
AWTCOM_API AwtStatus	AWT_Com_S_RegisterSMSListener (AwtComContext *pContext, const char *pattern, AwtOnSMSCB onSMSCB)
	Register a listener on SMS reception for incoming message with a sender matching the pattern given as parameter.
AWTCOM_API AwtStatus	AWT_Com_S_SendSMS (AwtComContext *pContext, const char *pRecipient, const char *pBuffer, uint32_t size)
	Tells the ReadyAgent to send an SMS to the given recipient.
AWTCOM_API AwtStatus	AWT_Com_S_SetVariables (AwtComContext *pContext, char **keys, char **values, int length)
	Retrieve variables from the Core ReadyAgent.
AWTCOM_API AwtStatus	AWT_Com_S_GetVariables (AwtComContext *pContext, char **keys, uint32_t length, VarsMap **vars)
	Retrieve variables from the Core ReadyAgent.
AWTCOM_API AwtStatus	AWT_Com_S_FreeVarsMap (VarsMap *vars)
	Release a previously received VarsMap (a message that was retrieved with AWT_Com_S_GetVariables).

---

Detailed Description

This library provide transparent connection with the ReadyAgent.

(Synchrounous API version)

Multithread safeness: The API is protected by mutexes so it safe to call all the API from different thread on the same context. There is one exception though: the AWT_Com_S_Destroy function is not protected and thus not thread-safe.

---

Typedef Documentation

typedef void(* AwtForceConnectionCB)(AwtStatus status, void *userData)

Callback type for connection to server notification.

The userData value is the one given in the AWT_Com_S_Create function.

typedef void(* AwtOnDataCB)(char *pBuffer, uint32_t size, void *userData)

Callback type for message reception.

The userData value is the one given in the AWT_Com_S_Create function.

---

Function Documentation

AWTCOM_API AwtStatus AWT_Com_S_Create	(	AwtComContext **	ppContext,
		char *	pAssetId,
		void *	userData
	)

Initialize the library and return a context.

Parameters:

	ppContext	will hold the returned context pointer
	pAssetId	a string defining the name of the asset
	userData	a user data value that is given back in notification callbacks (e.g. connection done or receive message)

AWTCOM_API AwtStatus AWT_Com_S_Destroy

(

AwtComContext *

pContext

)

Destroy the library context, and free associated resources.

The context pointer must be discarded and not used anymore. The function return when all resources are freed, however the thread spawned for notifications (see bellow) are not affected by this call.

AWTCOM_API AwtStatus AWT_Com_S_ForceConnectionToServer	(	AwtComContext *	pContext,
		AwtForceConnectionCB	doneCB
	)

Tells the ReadyAgent to do a connection with the server, as soon as it can.

The doneCB is called when the connection with the server actually completed. The status of the server connection is provided into the callback parameters. The callback is called into a spawned thread, so it is safe to call any other API from the callback, to block or to do any process in this call.

Parameters:

	pContext	the library context to use
	doneCB	the function that is called when the connection was established. Can be null if no notification is required.

AWTCOM_API AwtStatus AWT_Com_S_GetVariables	(	AwtComContext *	pContext,
		char **	keys,
		uint32_t	length,
		VarsMap **	vars
	)

Retrieve variables from the Core ReadyAgent.

Parameters:

	pContext	the library context to use
	keys	char array containing path of variables to get (i.e config.mediation, config.agent.deviceId)
	length	number of keys
	vars	pointer on the VarsMap structure to fill

AWTCOM_API AwtStatus AWT_Com_S_RegisterDataListener	(	AwtComContext *	pContext,
		AwtOnDataCB	onDataCB
	)

Register a listener on Data reception.

In order to unregister a callback, call this function with a null callback. Only one user can register to the data reception. The callback is called into a spawned thread, so it is safe to call any other API from the callback, to block or to do any process in this call.

Parameters:

	pContext	the library context to use
	onDataCB	the function that is called when a new message is received. Can be null if no notification is required.

AWTCOM_API AwtStatus AWT_Com_S_RegisterSMSListener	(	AwtComContext *	pContext,
		const char *	pattern,
		AwtOnSMSCB	onSMSCB
	)

Register a listener on SMS reception for incoming message with a sender matching the pattern given as parameter.

In order to unregister a callback, call this function with a null callback, a null pattern. Only one user can register to the data reception. The callback is called into a spawned thread, so it is safe to call any other API from the callback, to block or to do any process in this call.

Parameters:

	pContext	the library context to use
	pattern	sender to listen to. Must conform to lua pattern specification.
	onSMSCB	the function that is called when a new SMS is received.

AWTCOM_API AwtStatus AWT_Com_S_SendData	(	AwtComContext *	pContext,
		const char *	pBuffer,
		uint32_t	size
	)

Send a message to the ReadyAgent.

This function returns when the message has been sent.

AWTCOM_API AwtStatus AWT_Com_S_SendSMS	(	AwtComContext *	pContext,
		const char *	pRecipient,
		const char *	pBuffer,
		uint32_t	size
	)

Tells the ReadyAgent to send an SMS to the given recipient.

Parameters:

	pContext	the library context to use
	pRecipient	recipient of the message
	pBuffer	SMS message
	size	size of pBuffer

AWTCOM_API AwtStatus AWT_Com_S_SetVariables	(	AwtComContext *	pContext,
		char **	keys,
		char **	values,
		int	length
	)

Retrieve variables from the Core ReadyAgent.

Parameters:

	pContext	the library context to use
	keys	Keys to be set
	values	Values of keys to be set
	length	number of values to be set

AWTCOM_API const char* AWT_Com_S_Version

(

void

)

Return the version of this library.

The string is statically allocated, so there is no need to release it !