libAwtCom_async.h File Reference

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

#include "libAwtCom.h"
#include "awt_status.h"
#include <stdint.h>
#include "awt_async.h"

Include dependency graph for libAwtCom_async.h:

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

Functions
AWTCOM_API const char *	AWT_Com_A_Version (void)
	SYNC - Return the version of this library.
AWTCOM_API AwtStatus	AWT_Com_A_Create (AwtComContext **ppContext, char *pAssetId, AwtEventCallback pfEventHandler, void *pUserData)
	ASYNC - Initialize the library and return a context.
AWTCOM_API AwtStatus	AWT_Com_A_Destroy (AwtComContext *pContext)
	SYNC - Destroy the library context, and free associated resources.
AWTCOM_API AwtStatus	AWT_Com_A_GetState (AwtComContext *pContext, AwtComState *state)
	SYNC - Test if the library context is connected to the ReadyAgent.
AWTCOM_API AwtStatus	AWT_Com_A_GetTicketId (AwtComContext *pContext, int32_t *pTicketId)
	SYNC - Get a new TicketID.
AWTCOM_API AwtStatus	AWT_Com_A_SendData (AwtComContext *pContext, const char *pBuffer, uint32_t size)
	ASYNC - Send a message to the ReadyAgent.
AWTCOM_API AwtStatus	AWT_Com_A_ForceConnectionToServer (AwtComContext *pContext)
	ASYNC - Tells the ReadyAgent to do a connection with the server, as soon as it can.
AWTCOM_API AwtStatus	AWT_Com_A_GetReceivedData (AwtComContext *pContext, char **ppBuffer, uint32_t *pSize)
	ASYNC - Get a message that has been received from the ReadyAgent.
AWTCOM_API AwtStatus	AWT_Com_A_FreeReceivedData (char *pBuffer)
	SYNC - Release a previously received message (a message that was retrieved with AWT_Com_A_GetReceivedData function)

---

Detailed Description

This library provide transparent connection with the ReadyAgent.

(Asynchrounous API version)

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

---

Function Documentation

AWTCOM_API AwtStatus AWT_Com_A_Create	(	AwtComContext **	ppContext,
		char *	pAssetId,
		AwtEventCallback	pfEventHandler,
		void *	pUserData
	)

ASYNC - Initialize the library and return a context.

Initialization is finished when the event handler is called with the event AWTDACOM_INIT_EVENT.

Parameters:

	ppContext	will hold the returned context pointer
	pAssetId	a string defining the name of the asset
	pfEventHandler	the callback that will be used in order to trigger events
	pUserData	the user data that is given back in the event handler function

AWTCOM_API AwtStatus AWT_Com_A_Destroy

(

AwtComContext *

pContext

)

SYNC - Destroy the library context, and free associated resources.

The context pointer must be discarded and not used anymore.

Note:

Even though the API is synchronous, the destroy process may take some time to release all internal resources.

AWTCOM_API AwtStatus AWT_Com_A_ForceConnectionToServer

(

AwtComContext *

pContext

)

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

Note:

The function returns before the ReadyAgent actually connect to the server, so the return code equal to true does not mean the data where actually sent.

AWTCOM_API AwtStatus AWT_Com_A_GetReceivedData	(	AwtComContext *	pContext,
		char **	ppBuffer,
		uint32_t *	pSize
	)

ASYNC - Get a message that has been received from the ReadyAgent.

If one or more messages are available in the context, return synchronously the older message. Otherwise, the event handler is called whenever a new message is received.

If This function is never called all messages received by libCom are automatically flushed. Thus if you want to receive messages events you need to call this function at least once.

Once you get a message with this function you must release the message (with AWT_Com_A_FreeReceivedData function) when you do not need it anymore.

If you do not Receive and Free all signaled (with event) messages, then they will accumulate in the memory.

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

ASYNC - Send a message to the ReadyAgent.

The event handler is called when the message has been sent.

AWTCOM_API const char* AWT_Com_A_Version

(

void

)

SYNC - Return the version of this library.

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