awt_async.h File Reference

Common stuff that is used for ASYNC APIs. More...

#include "awt_status.h"

Include dependency graph for awt_async.h:

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

Typedefs
typedef void(*	AwtEventCallback )(void *pContext, AwtEvent event, AwtStatus status, void *pUserData)
	AWT Event callback.
typedef void(*	AwtAsyncMain )(int argc, char **argv)
	Asynchronous main function type.
Enumerations
enum	AwtEvent
	Event types for asynchronous event callbacks: AwtCom or AwtDaHL libraries.
Functions
AwtStatus	AWT_ASYNC_Run (int argc, char **argv, AwtAsyncMain asyncMain)
	Asynchronous thread.
AwtStatus	AWT_ASYNC_Terminate ()
	Ask the Asynchronous framework to stop.

---

Detailed Description

Common stuff that is used for ASYNC APIs.

General note for all ASYNC APIs:
The return code of an asynchronous function gives important information on the behavior of the function call process, it returns an AwtStatus :

• AWT_STATUS_ASYNC : when the action has been taken care of. An event will be triggered in order to inform the user how the asynchronous operations went. (Status will be OK or an ERROR )
• AWT_STATUS_OK : when the action requested was actually able to be done synchronously. No further action is requested, no event will be triggered for this request (because it already completed !)
• AWT_STATUS_BUSY : The action requested is not possible at that moment because some resources are not available. This error usually happens when an asynchronous function was called a second time before the first asynchronous call actually completed (an asynchronous call is complete if it returned OK synchronously or an event was called to signal the end of the process). This return code will not provoke a special event.
• SOME_OTHER_ERRORS_CODE : when an error happens synchronously (before executing the asynchronous part of the call). This conclude the asynchronous call. This return code will not provoke a special event.

---

Typedef Documentation

typedef void(* AwtAsyncMain)(int argc, char **argv)

Asynchronous main function type.

See AWT_ASYNC_Run for more details.

typedef void(* AwtEventCallback)(void *pContext, AwtEvent event, AwtStatus status, void *pUserData)

AWT Event callback.

Prototype of the callback used to signal events.

Parameters:

	event	the event being signaled. The event is actually linked to an asynchronous functionality
	status	the status of the functionality being event'ed.

---

Function Documentation

AwtStatus AWT_ASYNC_Run	(	int	argc,
		char **	argv,
		AwtAsyncMain	asyncMain
	)

Asynchronous thread.

When using the asynchronous API, the user must provide a running thread. All calls of the asynchronous API must be done in that thread, since the API is not thread-safe in itself. The call to this function returns only when the user wants to terminate the application calling AWT_ASYNC_End. This function will initialize the asynchronous framework and then call the asynchronous main function given as parameter. If the asynchronous framework is already running, a call to this function return directly.

AwtStatus AWT_ASYNC_Terminate

(

)

Ask the Asynchronous framework to stop.

This will cause the AWT_ASYNC_Run function to return. This function must be called within the thread that called AWT_ASYNC_Run.