EIO_registerReceiveFn

- a callback function to receive events

SYNOPSIS

#include <$OV_HEADER/ecs/EIO/EIO.h>
int32 EIO_registerReceiveFn
(
	EIO_ConnectionId id,
	EIO_ReceiveFn *receiveFn
);

DESCRIPTION

This function registers a callback function for a specified event I/O connection. The registered function is called for each event received from the specified connection.

Only one receive function can be registered for each event I/O connection. If a call is made to register a function where one is already registered the existing registration is replaced.

If EIO_ConnectionId is specified as EIO_ALLCON, a default receive function will be registered. This default function will receive events that were not accepted by any receive function registered for a specific EIO_ConnectionId. The EIO_ConnectionId passed to the callback function will also be set to EIO_ALLCON if the callback is made from the default receive function.

Parameters

EIO_ConnectionId id

The event I/O connection ID that the receiveFn will be registered for (as set by EIO_open). If EIO_ALLCON is specified then the receive function specifies a default function that is called for each event received on event I/O connections not accepted by a registered receive function.

EIO_ReceiveFn *receiveFn

Function to call for each event received from the specified event I/O connection. If zero is specified any previously registered receive function for the specified event I/O connection is deregistered. The prototype of EIO_ReceiveFn is:

int32
(EIO_ReceiveFn)
	( EIO_ConnectionId id, /* the EIO_ConnectionId the
	                          event came from. */
	  const void* pdu,     /* a pointer to an array of
	                          bytes containing the event PDU. */
	  int32 pdu_length,    /* the length (in bytes) of
	                          the event PDU. */
	  int32 createTime,    /* the time at which this
	                          event was created. */
	  const char* encoding_type, /* the endecoder type of
	                                the event. The caller
	                                must free this string
	                                by calling free(3).*/
	  const char* event_syntax   /* the endecoder event
	                                syntax of the event
	                                (may be NULL if there
	                                are no event syntaxes
	                                within this encoding
	                                type). The caller must
	                                free this string by
	                                calling free(3).*/
	)

EXAMPLES

Open an EIO connection over an ESOK connection and register a receive function to receive an MDL/ASCII event with the SimpleEvent syntax.

#include <stdio.h>
#include <sys/socket.h>
#include <ESOK/sockstack.h>
#include <EIO/EIO.h>
main(int argc, char* argv[])
{
	int ret;
	ESOK_Remote remote;
	ESOK_ConnectionId cid;
	EIO_ConnectionId eid;
	char* encoding_type;
	char* event_syntax;
	int instance = 1;
	ESOK_stackInit();
	EIO_stackInit();
	ESOK_buildRemote(instance, &remote);
	ESOK_open(remote, &cid); /* open a socket connection */
	EIO_open(cid, 0, &eid);  /* open an EIO connection on default stream*/
	/*
	** now set up recvFn to be called when an mdl SimpleEvent
	** is received by event I/O
	*/

EIO_registerReceiveFn(eid, recvFn); /* instead of eid, use
                                       EIO_ALLCON to specify
                                       a default receive function */
encoding_type = "mdl";
event_syntax = "SimpleEvent";
EIO_addFilter(eid, encoding_type, event_syntax);

while(ESOK_process(1000) >= 0);
}

RETURNS

ECS_SUCCESS

Succeeded.

ECS_BAD_PARAMETER

Bad event I/O connection ID parameter.

EIO_NOT_INITIALISED

EIO_stackInit has not been called.

EIO_BAD_CONNECTION

The specified event I/O connection is not open.