libAwtDaHL_sync.h File Reference

This is the synchronous version of the AWT-DA HL library. More...

#include "libAwtDaProtocol.h"
#include "libAwtCom_sync.h"
#include "libAwtDaHL.h"
#include <stdint.h>
#include "libAwtDaHL.h"

Include dependency graph for libAwtDaHL_sync.h:

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

Typedefs
typedef void(*	AwtOnMessageCB )(AwtDaObject *message, int needAnAck, void *pUserData)
	Callback type for message reception.
Functions
HL_API const char *	AWT_HL_S_Version (void)
	Get the version of the library.
HL_API AwtStatus	AWT_HL_S_DataManager_Create (AwtDataManager **ppDataManager, char *pAssetId, void *pUserData)
	Create the library context.
HL_API AwtStatus	AWT_HL_S_DataManager_Destroy (AwtDataManager *pDataManager)
	Destroy the library context, and release all associated resources.
HL_API AwtStatus	AWT_HL_S_DataManager_AddDataContainer (AwtDataManager *pDataManager, AwtDataContainer *pDataContainer, int32_t *requestId, AwtOnAckCB onAckCB)
	Add a Data Container into the "to send" queue.
HL_API AwtStatus	AWT_HL_S_DataManager_AddEvents (AwtDataManager *pDataManager, char *pRelativePath, int32_t startTime, AwtDaObject *pTimeDeltasList, AwtDaObject *pEventList, int32_t *requestId, AwtOnAckCB onAckCB)
	Add an Event list to the "to send" queue.
HL_API AwtStatus	AWT_HL_S_DataManager_AddEvent (AwtDataManager *pDataManager, char *pRelativePath, int32_t timestamp, AwtDaObject *pEvent, int32_t *requestId, AwtOnAckCB onAckCB)
	Add a single Event to the "to send" queue.
HL_API AwtStatus	AWT_HL_S_DataManager_SetMessageListener (AwtDataManager *pDataManager, const char *relativePath, int messageType, AwtOnMessageCB onMessageCB)
	Register a message reception listener.
HL_API AwtStatus	AWT_HL_S_DataManager_AddAcknowledgement (AwtDataManager *pDataManager, AwtDaObject *message, AwtDaObject *data, AwtStatus status)
	Send an acknowledgment of a received message.
HL_API AwtStatus	AWT_HL_S_DataManager_Flush (AwtDataManager *pDataManager)
	Flush the "to send" queue so that the stored messages are actually sent to the ReadyAgent.
HL_API AwtStatus	AWT_HL_S_DataManager_GetComHandle (AwtDataManager *pDataManager, AwtComContext **plibComContext)
	Retrieve the handle to the libCom Library.

---

Detailed Description

This is the synchronous version of the AWT-DA HL library.

Version:

0.1

Multithread safeness: The Data Manager 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_HL_S_DataManager_Destroy function is not protected and thus not thread-safe. The Data Containers API is not thread safe on the same object. It is safe to use the API into several threads, but not with the same object.

---

Typedef Documentation

typedef void(* AwtOnMessageCB)(AwtDaObject *message, int needAnAck, void *pUserData)

Callback type for message reception.

Parameters:

	message	the message needs to be released once done with it, see AWT_DaObject_Release.
	needAnAck	if non null, an acknowledge is requested by the other peer, use AWT_HL_S_DataManager_AddAcknowledgement to send back the acknowledgment.
	pUserData	the user data value is the one given in the AWT_HL_S_DataManager_Create function.

---

Function Documentation

HL_API AwtStatus AWT_HL_S_DataManager_AddAcknowledgement	(	AwtDataManager *	pDataManager,
		AwtDaObject *	message,
		AwtDaObject *	data,
		AwtStatus	status
	)

Send an acknowledgment of a received message.

The given message must have a non null ticketId. This function can only be used with messages received with AwtOnMessageCB listener.

Parameters:

	pDataManager	the library context to use.
	message	the message to acknowledge
	data	the data object to send with the response object
	status	the status to send with the response object

Note:

Data Manager doesn't keep data in persisted storage, so no data loss can be guaranteed only when a successful Flush to ReadyAgent has been done, followed by a successful ForceConnectionToServer call .

HL_API AwtStatus AWT_HL_S_DataManager_AddDataContainer	(	AwtDataManager *	pDataManager,
		AwtDataContainer *	pDataContainer,
		int32_t *	requestId,
		AwtOnAckCB	onAckCB
	)

Add a Data Container into the "to send" queue.

Data Container can be set to request an acknowledge on reception.

Parameters:

	pDataManager	the library context to use.
	pDataContainer	the Data Container to add in the "to send" queue.
	requestId	if set to non-null and if onAckCB is non-null, a requestId will be associated with the Data Container. It will be send again when onAckCB is called, to be compared with the one returned by this function.
	onAckCB	if set to non-null, the callback to use for the data acknowledgment. When the Server will receive the data it will send an acknowledge when the data are processed. This will cause a call to this callback.

Note:

Adding a Data Container to the Data Manager does not send the object to the ReadyAgent: it serializes its content, flush the Data Container and send this serialized content to the Data Manager. The flush API must be used to send the object to the ReadyAgent.

Data Manager doesn't keep data in persisted storage, so no data loss can be guaranteed only when a successful Flush to ReadyAgent has been done, followed by a successful ForceConnectionToServer call .

There is a relation between requestId and onAckCB parameters. You can specify a onAckCB and no requestId, then you will have to use specific onAckCB for this message. But it has no sense to give a valid pointer for a requestId but no onAckCB, because the onAckCB is only means to receive the requestID. Status AWT_STATUS_WRONG_PARAMS will be returned to inform you if you did it wrong.

HL_API AwtStatus AWT_HL_S_DataManager_AddEvent	(	AwtDataManager *	pDataManager,
		char *	pRelativePath,
		int32_t	timestamp,
		AwtDaObject *	pEvent,
		int32_t *	requestId,
		AwtOnAckCB	onAckCB
	)

Add a single Event to the "to send" queue.

As Data Containers, the Event can be set to request an acknowledge on reception.

Parameters:

	pDataManager	the library context to use.
	pRelativePath	the path (relative to the library root path) of the events sent.
	timestamp	the timestamp of the event.
	pEvent	the Event to send.
	requestId	if set to non-null and if onAckCB is non-null, a requestId will be associated with the Data Container. It will be send again when onAckCB is called, to be compared with the one returned by this function.
	onAckCB	if set to non-null, the callback to use for the data acknowledgment. When the Server will receive the data it will send an acknowledge when the data are processed. This will cause a call to this callback.

Note:

Data Manager doesn't keep data in persisted storage, so no data loss can be guaranteed only when a successful Flush to ReadyAgent has been done, followed by a successful ForceConnectionToServer call .

There is a relation between requestId and onAckCB parameters. You can specify a onAckCB and no requestId, then you will have to use specific onAckCB for this message. But it has no sense to give a valid pointer for a requestId but no onAckCB, because the onAckCB is only means to receive the requestID. Status AWT_STATUS_WRONG_PARAMS will be returned to inform you if you did it wrong.

HL_API AwtStatus AWT_HL_S_DataManager_AddEvents	(	AwtDataManager *	pDataManager,
		char *	pRelativePath,
		int32_t	startTime,
		AwtDaObject *	pTimeDeltasList,
		AwtDaObject *	pEventList,
		int32_t *	requestId,
		AwtOnAckCB	onAckCB
	)

Add an Event list to the "to send" queue.

As Data Containers, the Event list can be set to request an acknowledge on reception.

Parameters:

	pDataManager	the library context to use.
	pRelativePath	the path (relative to the library root path) of the events sent.
	startTime	timestamp of the 1st event of the list.
	pTimeDeltasList	list of timestamp delta ( tsdelta(n) = ts(n)-ts(n-1) ) of the event n+1 in the event list.
	pEventList	list of events.
	requestId	if set to non-null and if onAckCB is non-null, a requestId will be associated with the Data Container. It will be send again when onAckCB is called, to be compared with the one returned by this function.
	onAckCB	if set to non-null, the callback to use for the data acknowledgment. When the Server will receive the data it will send an acknowledge when the data are processed. This will cause a call to this callback.

Note:

Data Manager doesn't keep data in persisted storage, so no data loss can be guaranteed only when a successful Flush to ReadyAgent has been done, followed by a successful ForceConnectionToServer call .

There is a relation between requestId and onAckCB parameters. You can specify a onAckCB and no requestId, then you will have to use specific onAckCB for this message. But it has no sense to give a valid pointer for a requestId but no onAckCB, because the onAckCB is only means to receive the requestID. Status AWT_STATUS_WRONG_PARAMS will be returned to inform you if you did it wrong.

HL_API AwtStatus AWT_HL_S_DataManager_Create	(	AwtDataManager **	ppDataManager,
		char *	pAssetId,
		void *	pUserData
	)

Create the library context.

This function also set the root path of the library. The initialization is complete when the function returns.

Note:

If the function returns a status different to AWT_STATUS_OK, all potential internal resource are freed (thus there is no need to call Destroy afterwards)

Parameters:

	ppDataManager	the pointer to store the created AwtDataManager* context, must be non NULL
	pAssetId	the name of the application asset. All sent messages will be prefixed with this asset name.
	pUserData	the user data that is given back in the different notification callbacks below.

HL_API AwtStatus AWT_HL_S_DataManager_Flush

(

AwtDataManager *

pDataManager

)

Flush the "to send" queue so that the stored messages are actually sent to the ReadyAgent.

Parameters:

pDataManager

the library context to use.

HL_API AwtStatus AWT_HL_S_DataManager_GetComHandle	(	AwtDataManager *	pDataManager,
		AwtComContext **	plibComContext
	)

Retrieve the handle to the libCom Library.

The libCom context can be used to call libCom specific functions. For instance, in order to force a connection to the server AWT_Com_S_ForceConnectionToServer function can be used.

Parameters:

	pDataManager	the library context to use.
	plibComContext	the pointer where to store the AwtComContext*, must be non NULL.

HL_API AwtStatus AWT_HL_S_DataManager_SetMessageListener	(	AwtDataManager *	pDataManager,
		const char *	relativePath,
		int	messageType,
		AwtOnMessageCB	onMessageCB
	)

Register a message reception listener.

Call with a null callback in order to un-register a message reception listener.

Parameters:

	pDataManager	the library context to use.
	relativePath	relative path to register the listener on.
	messageType	type of message to register the listener on, see AwtDaMessageType enum in libAwtDaProtocol.h .
	onMessageCB	message reception listener

Note:

When a message is received by the Data Manager, only one listener will be called. The listener that will be called is the one with the closest parent path. For instance 2 listeners: one on "house.room1.heating" (L1), the other one on "house.room1" (L2). When a message with path="house.room1.heating.targettemp" is received it will call L1. When a message with path="house.room1.power" is received, it will call L2.

HL_API const char* AWT_HL_S_Version

(

void

)

Get the version of the library.

The string is statically allocated, and thus need not to be released.