libAwtDaHL_async.h File Reference

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

#include "libAwtDaProtocol.h"
#include "libAwtCom_async.h"
#include "awt_async.h"
#include "libAwtDaHL.h"
#include "libAwtDaHL_containers.h"

Include dependency graph for libAwtDaHL_async.h:

Functions
HL_API const char *	AWT_HL_A_Version (void)
	Get the version of the library.
HL_API AwtStatus	AWT_HL_A_DataManager_Create (AwtDataManager **ppDataManager, char *pAssetId, AwtEventCallback pfEventHandler, void *pUserData)
	ASYNC Create the library context.
HL_API AwtStatus	AWT_HL_A_DataManager_Destroy (AwtDataManager *pDataManager)
	SYNC.
HL_API AwtStatus	AWT_HL_A_DataManager_AddDataContainer (AwtDataManager *pDataManager, AwtDataContainer *pDataContainer, int32_t *requestId)
	SYNC when not requesting acknowledge from the server ASYNC when requesting acknowledge from the server.
HL_API AwtStatus	AWT_HL_A_DataManager_AddEvents (AwtDataManager *pDataManager, char *pRelativePath, int32_t startTime, AwtDaObject *pTimeDeltasList, AwtDaObject *pEventList, int32_t *requestId)
	SYNC when not requesting acknowledge from the server ASYNC when requesting acknowledge from the server.
HL_API AwtStatus	AWT_HL_A_DataManager_AddEvent (AwtDataManager *pDataManager, char *pRelativePath, int32_t timestamp, AwtDaObject *pEvent, int32_t *requestId)
	SYNC when not requesting acknowledge from the server ASYNC when requesting acknowledge from the server.
HL_API AwtStatus	AWT_HL_A_DataManager_GetReceivedResponse (AwtDataManager *pDataManager, int32_t *requestId, AwtDaObject **message)
	ASYNC.
HL_API AwtStatus	AWT_HL_A_DataManager_GetReceivedMessage (AwtDataManager *pDataManager, AwtDaObject **message, uint32_t *needAck)
	ASYNC.
HL_API AwtStatus	AWT_HL_A_DataManager_FlushAllReceivedMessages (AwtDataManager *pDataManager)
	SYNC.
HL_API AwtStatus	AWT_HL_A_DataManager_AddAcknowledgement (AwtDataManager *pDataManager, AwtDaObject *message, AwtDaObject *data, AwtStatus status)
	SYNC.
HL_API AwtStatus	AWT_HL_A_DataManager_Flush (AwtDataManager *pDataManager)
	ASYNC.
HL_API AwtStatus	AWT_HL_A_DataManager_GetComHandle (AwtDataManager *pDataManager, AwtComContext **plibComContext, AwtEventCallback pfEventHandler, void *pUserData)
	SYNC.

---

Detailed Description

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

Version:

0.1

This API is not meant to be used in a threaded environment.

---

Function Documentation

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

SYNC.

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 AWT_HL_A_DataManager_GetReceivedMessage function.

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_A_DataManager_AddDataContainer	(	AwtDataManager *	pDataManager,
		AwtDataContainer *	pDataContainer,
		int32_t *	requestId
	)

SYNC when not requesting acknowledge from the server ASYNC when requesting acknowledge from the server.

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 a requestId will be associated with the Data Container. When the Server will receive the data it will send an acknowledge when the data are processed. This will trigger an event, the requestId can be retrieved with AWT_HL_A_DataManager_GetReceivedResponse function.

Note:

Adding a Data Container to the Data Manager does not send the object to the ReadyAgent (but serialize it and empty it). 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 .

HL_API AwtStatus AWT_HL_A_DataManager_AddEvent	(	AwtDataManager *	pDataManager,
		char *	pRelativePath,
		int32_t	timestamp,
		AwtDaObject *	pEvent,
		int32_t *	requestId
	)

SYNC when not requesting acknowledge from the server ASYNC when requesting acknowledge from the server.

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 a requestId will be associated with the Events. When the Server will receive the data it will send an acknowledge when the data are processed. This will trigger an event, the requestId can be retrieved with AWT_HL_A_DataManager_GetReceivedResponse function.

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_A_DataManager_AddEvents	(	AwtDataManager *	pDataManager,
		char *	pRelativePath,
		int32_t	startTime,
		AwtDaObject *	pTimeDeltasList,
		AwtDaObject *	pEventList,
		int32_t *	requestId
	)

SYNC when not requesting acknowledge from the server ASYNC when requesting acknowledge from the server.

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 a requestId will be associated with the Event. When the Server will receive the data it will send an acknowledge when the data are processed. This will trigger an event, the requestId can be retrieved with AWT_HL_A_DataManager_GetReceivedResponse function.

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_A_DataManager_Create	(	AwtDataManager **	ppDataManager,
		char *	pAssetId,
		AwtEventCallback	pfEventHandler,
		void *	pUserData
	)

ASYNC Create the library context.

This function also set the root path of the library. The initialization is complete when the AwtEventCallback is called with AWTDACOM_INIT_EVENT.

Note:

If AwtEventCallback is called with AWTDACOM_INIT_EVENT but a status different of AWT_STATUS_OK, it's up to the user to call AWT_HL_A_DataManager_Destroy whenever he want to.

Parameters:

	ppDataManager	pointer to store the AwtDataManager* context, must be non NULL
	pAssetId	the name of the application asset. All sent messages will be prefixed with this asset name.
	pfEventHandler	the user callback to use on every event to report, must be non NULL
	pUserData	the user data that will be given back on each pfEventHandler call.

HL_API AwtStatus AWT_HL_A_DataManager_Destroy

(

AwtDataManager *

pDataManager

)

SYNC.

Destroy the library context, and release all associated resources.

Parameters:

pDataManager

the context to destroy, must be a valid context

HL_API AwtStatus AWT_HL_A_DataManager_Flush

(

AwtDataManager *

pDataManager

)

ASYNC.

Flush the "to send" queue so that the stored messages are actually sent to the ReadyAgent, this implies data container (correlated or not), events and acknowledges. This Flush function doesn't deal with the data transfer to the server, only to the ReadyAgent. The data transfer to the server can be at the ReadyAgent discretion, however the user can force the connection of the ReadyAgent to the server using AWT_Com_A_ForceConnectionToServer() function in the AwtCom library. The AwtCom context can be accessed using AWT_HL_A_DataManager_GetComHandle() function.

Parameters:

pDataManager

the library context to use.

HL_API AwtStatus AWT_HL_A_DataManager_FlushAllReceivedMessages

(

AwtDataManager *

pDataManager

)

SYNC.

Flush all the receives messages, to be used when the user doesn't need them and want to save memory.

Parameters:

pDataManager

the library context to use.

HL_API AwtStatus AWT_HL_A_DataManager_GetComHandle	(	AwtDataManager *	pDataManager,
		AwtComContext **	plibComContext,
		AwtEventCallback	pfEventHandler,
		void *	pUserData
	)

SYNC.

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_A_ForceConnectionToServer function can be used. Events coming from the libCom asynchronous process are going through the pfEventHandler handler given in AWT_HL_CreateDataManager function.

Parameters:

	pDataManager	the library context to use.
	plibComContext	the pointer to store the AwtComContext*, must be non NULL
	pfEventHandler	the user callback, it will be triggered on any event related to AwtCom. See awt_async.h, Awt_Event enum.
	pUserData	the user data that will be given back the user on each call to the pfEventHandler given here.

HL_API AwtStatus AWT_HL_A_DataManager_GetReceivedMessage	(	AwtDataManager *	pDataManager,
		AwtDaObject **	message,
		uint32_t *	needAck
	)

ASYNC.

Return a received message and status OK if available, status ASYNC if no message is available for the moment This function is likely to be called after notification of event AWTDAHL_RECEIVED_MESSAGE_EVENT.

Parameters:

	pDataManager	the library context to use.
	message	pointer to the received message
	needAck	pointer to int used as boolean to inform the user about acknowledgment necessity of the returned message. Can be NULL

Note:

It's up to the user to call AWT_DaObject_Release on the retrieved message when he doesn't need it anymore.

HL_API AwtStatus AWT_HL_A_DataManager_GetReceivedResponse	(	AwtDataManager *	pDataManager,
		int32_t *	requestId,
		AwtDaObject **	message
	)

ASYNC.

Return a received response and corresponding the RequestId with status OK, or ASYNC status if no response message is available for the moment. This function is likely to be called after notification of event AWTDAHL_RECEIVED_RESPONSE_EVENT.

Parameters:

	pDataManager	pDataManager the library context to use.
	requestId	the requestId corresponding to the sent message, same value that the output param in AddEvent(s) or AddDataContainer functions
	message	the response message

Note:

It's up to the user to call AWT_DaObject_Release on the retrieved message when he doesn't need it anymore. *

HL_API const char* AWT_HL_A_Version

(

void

)

Get the version of the library.

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