The asynchronous API

Functions
const struct aura_object *	aura_get_current_object (struct aura_node *node)
	Obtain the pointer to the current aura_object. More...
struct aura_eventloop *	aura_eventloop_get_data (struct aura_node *node)
void	aura_status_changed_cb (struct aura_node *node, void(*cb)(struct aura_node *node, int newstatus, void *arg), void *arg)
void	aura_fd_changed_cb (struct aura_node *node, void(*cb)(const struct aura_pollfds *fd, enum aura_fd_action act, void *arg), void *arg)
void	aura_etable_changed_cb (struct aura_node *node, void(*cb)(struct aura_node *node, struct aura_export_table *old, struct aura_export_table *new, void *arg), void *arg)
void	aura_unhandled_evt_cb (struct aura_node *node, void(*cb)(struct aura_node *node, struct aura_buffer *buf, void *arg), void *arg)
int	aura_start_call_raw (struct aura_node *node, int id, void(*calldonecb)(struct aura_node *dev, int status, struct aura_buffer *ret, void *arg), void *arg,...)
int	aura_set_event_callback_raw (struct aura_node *node, int id, void(*calldonecb)(struct aura_node *dev, int status, struct aura_buffer *ret, void *arg), void *arg)
int	aura_set_event_callback (struct aura_node *node, const char *event, void(*calldonecb)(struct aura_node *dev, int status, struct aura_buffer *ret, void *arg), void *arg)
int	aura_start_call (struct aura_node *node, const char *name, void(*calldonecb)(struct aura_node *dev, int status, struct aura_buffer *ret, void *arg), void *arg,...)

Detailed Description

If you are reading this, you must be familiar with the concept of events and methods. If not have a look at the previous section that describes synchronous API. It has a nice overview of how things work.

In this section we'll be dealing with asynchronous API. In real life your target device may work at speeds of several Mhz and take ages (compared to the host PC) to execute a method call. That's not cool, because we can do many other things while the remote side gets the job done.

With asynchronous API you can start a method call, and get the results in the supplied callback. Events also get delivered into their respective callbacks (if any).

If the node goes offline and later becomes live once more with a different export table, aura will try to preserve all of the event callbacks, even if their id changes. The callback will only get unregistered if event signature changes (e.g. the number or type of the returned values changes)

All of the callbacks are delivered from the eventloop. aura comes with it's own easy to use event loop implementation that is covered in the next section. The general workflow is:

• Open one or several nodes using aura_open() or aura_vopen()
• Register all of your callbacks
• Create an eventloop using aura_eventloop_create()
• Run the event processing loop with aura_handle_events() for as long as you want

If you wish to integrate aura with your own event loop, see aura_get_pollfds() to get a list of descriptors to poll and aura_fd_changed_cb() to get notified whenever transport expects a descriptor to be added/removed.

Function Documentation

void aura_etable_changed_cb	(	struct aura_node *	node,
		void(*)(struct aura_node *node, struct aura_export_table *old, struct aura_export_table *new, void *arg)	cb,
		void *	arg
	)

Set up etable changed callback.

Parameters

node
cb
arg

Definition at line 295 of file aura.c.

struct aura_eventloop* aura_eventloop_get_data

(

struct aura_node *

node

)

Get the eventloop associated with this node

Parameters

node

Returns

Pointer to node's eventloop or NULL if node has none

Definition at line 243 of file aura.c.

Referenced by aura_close(), aura_eventloop_add(), and aura_eventloop_del().

void aura_fd_changed_cb	(	struct aura_node *	node,
		void(*)(const struct aura_pollfds *fd, enum aura_fd_action act, void *arg)	cb,
		void *	arg
	)

Set the fd changed callback. You don't need this call unless you're using your own eventsystem. Setting this callback will trigger callbacks for all the file descriptors that are already registered.

Parameters

node
cb
arg

Definition at line 275 of file aura.c.

Referenced by aura_eventloop_add(), and aura_eventloop_del().

const struct aura_object* aura_get_current_object

(

struct aura_node *

node

)

Obtain the pointer to the current aura_object.

This function can be used while in the callback to get the pointer to the struct aura_object that caused this callback.

Calling this function outside the callback will return NULL and spit out a warning to the log

Parameters

node

Returns

Definition at line 226 of file aura.c.

int aura_set_event_callback	(	struct aura_node *	node,
		const char *	event,
		void(*)(struct aura_node *dev, int status, struct aura_buffer *ret, void *arg)	calldonecb,
		void *	arg
	)

Set the callback that will be called when event with supplied name arrives. NULL calldonecb disables this event callback. aura_buffer supplied to called in 'ret' contains any data assiciated with this event. You should not free the data buffer in the callback or access the buffer from anywhere but this callback. Make a copy if you need it.

Parameters

node
event
calldonecb
arg

Returns

Definition at line 536 of file aura.c.

int aura_set_event_callback_raw	(	struct aura_node *	node,
		int	id,
		void(*)(struct aura_node *dev, int status, struct aura_buffer *ret, void *arg)	calldonecb,
		void *	arg
	)

Set the callback that will be called when event with supplied id arrives. NULL calldonecb disables this event callback. aura_buffer supplied to called in 'ret' contains any data assiciated with this event. You should not free the data buffer in the callback or access the buffer from anywhere but this callback. Make a copy if you need it.

Parameters

node
id
calldonecb
arg

Returns

Definition at line 505 of file aura.c.

int aura_start_call	(	struct aura_node *	node,
		const char *	name,
		void(*)(struct aura_node *dev, int status, struct aura_buffer *ret, void *arg)	calldonecb,
		void *	arg,
			...
	)

Start a call to an object identified by name.

Parameters

node
name
calldonecb
arg

Returns

-EBADSLT if the requested id is not in etable -EIO if serialization failed or another synchronous call for this id is pending -ENOEXEC if the node is currently offline

Definition at line 564 of file aura.c.

References aura_buffer_release(), and aura_core_start_call().

int aura_start_call_raw	(	struct aura_node *	node,
		int	id,
		void(*)(struct aura_node *dev, int status, struct aura_buffer *ret, void *arg)	calldonecb,
		void *	arg,
			...
	)

Start a call for the object identified by its id the export table. Upon completion the specified callback will be fired with call results.

Parameters

node
id
calldonecb
arg

Returns

-EBADSLT if the requested id is not in etable -EIO if serialization failed or another synchronous call for this id is pending -ENOEXEC if the node is currently offline

Definition at line 462 of file aura.c.

References aura_buffer_release(), and aura_core_start_call().

void aura_status_changed_cb	(	struct aura_node *	node,
		void(*)(struct aura_node *node, int newstatus, void *arg)	cb,
		void *	arg
	)

Setup the status change callback. This callback will be called when the node goes online and offline

Parameters

node
cb
arg

Definition at line 258 of file aura.c.

void aura_unhandled_evt_cb	(	struct aura_node *	node,
		void(*)(struct aura_node *node, struct aura_buffer *buf, void *arg)	cb,
		void *	arg
	)

Set up a generic callback to catch all events that have no callbacks installed. Warning: This callback will not be called if you enable synchronous event processing

Parameters

node
cb	The callback function to call
arg	Argument that will be passed to the callback function

Definition at line 314 of file aura.c.