XBEE_CONCALLBACKGET(3)

NAME
xbee_conCallbackGet, xbee_conCallbackSet

SYNOPSIS
#include <xbee.h>

typedef void(*xbee_t_conCallback)(struct xbee *xbee, struct xbee_con *con, struct xbee_pkt **pkt, void **data);

xbee_err xbee_conCallbackSet(struct xbee_con *con, xbee_t_conCallback newCallback, xbee_t_conCallback *oldCallback);

xbee_err xbee_conCallbackGet(struct xbee_con *con, xbee_t_conCallback *curCallback);

DESCRIPTION

xbee_conCallbackSet() allows you to associate a callback function with a connection, whilst retrieving the current callback.

con must be a valid connection, returned from xbee_conNew(). newCallback must be either NULL (to disable callbacks), or non-NULL to enable callbacks, with the given function address. oldCallback can be NULL to indicate that you do not wish to retrieve the previously assigned callback.

xbee_conCallbackGet() allows you to retrieve the callback function that is currently assigned to the given connection.

  Return Value
On success these functions will return XBEE_ENONE, otherwise an error number from enum xbee_errors (as specified in <xbee.h>)

  Note
While a connection has a callback function assigned, use of xbee_conRx() will be disabled, and it will return XBEE_EINVAL.

  Callback Behavior
For each connection, one callback thread may be active. Within this thread, the connection's callback function will be executed once for each packet that is received, in the order that they were received.

This means that if a single callback function is associated with multiple connections, static variables will be unsafe, and the developer should instead use the void **data that is provided. The data parameter is initialized to NULL, so you may safely initialize this from within the callback function, or alternatively from outside, by calling xbee_conDataSet().

  Callback Parameters
The callback function's parameters are detailed below:

xbee
    provides the libxbee instance from which the connection is derived.

con provides the connection that the packet was received by (you may call a variant of xbee_conTx() with this from within the callback function).

pkt provides access to the packet that was received.

    NOTE: you must dereference this argument once. If you leave the argument alone, then libxbee will automatically call xbee_pktFree() on the packet after the callback has completed. If you instead re-assign NULL to it, libxbee will not call xbee_pktFree() on the packet. This is useful if you wish to postpone processing, in which case you must later call xbee_pktFree(). See the EXAMPLE section for more information.

data
    provides the data item that you have assigned to the connection, either from within a callback, or by using xbee_conDataSet(). Again, you must dereference this argument once before use, and you may re-assign it from within the callback function, without calling xbee_conDataSet().

EXAMPLE

  A simple callback
#include <xbee.h>
void myCallback(struct xbee *xbee, struct xbee_con *con, struct xbee_pkt **pkt, void **data) {
	printf("received data for connection @ %p\n", con);
	xbee_conTx(con, "Hello!\n");
}
struct xbee *xbee;
struct xbee_con *con;
/* initialize xbee, using xbee_setup() */
/* initialize con, using xbee_conNew() */
if (xbee_conCallbackSet(con, myCallback, NULL) != XBEE_ENONE) return;

  A callback that uses the connection's data
struct myStruct {
	int counter;
	struct xbee_pkt *pkt;
};
void myCallback(struct xbee *xbee, struct xbee_con *con, struct xbee_pkt **pkt, void **data) {
	struct myStruct *ms;

	/* allocate storage for the counter & packet */
	if (!(*data)) {
		if ((ms = malloc(sizeof(*ms))) == NULL) return; /* error */
		/* keep hold of the storage */
		*data = ms;
	} else {
		ms = *data;
	}

	/* if we are already holding a packet, print a message and return (libxbee will free the packet) */
	if (ms->pkt) {
		printf("already holding a packet...\n");
		return;
	}

	/* otherwise increment the counter, and hold on to the packet */
	ms->counter++;
	ms->pkt = *pkt;

	printf("received %d packets for connection @ %p\n", ms->a, con);
	xbee_conTx(con, "Hello!\n");

	/* don't let libxbee free our packet */
	*pkt = NULL;
}
/* observe the data using xbee_conDataGet() */

AUTHOR
Attie Grande <attie@attie.co.uk>

SEE ALSO
libxbee(3), xbee_setup(3), xbee_conNew(3), xbee_conTx(3), xbee_conRx(3), xbee_conDataGet(3), xbee_conDataSet(3), xbee_pktFree(3)