EvmEventPost(3) 					     Library Functions Manual						   EvmEventPost(3)

NAME

       EvmEventPost - Posts an event

LIBRARY

       EVM Support Library (libevm.so, libevm.a)

SYNOPSIS

       #include <evm/evm.h>

       EvmStatus_t EvmEventPost(
	       EvmConnection_t connection,
	       const EvmEvent_t event);

       EvmStatus_t EvmEventPostVa(
	       EvmConnection_t connection,
	       const EvmEvent_t event,
	       [EvmItemId_t item_id,
	       const EvmItemValue_t item_value,]      ...	EvmITEM_NONE);

OPERANDS

       The  connection through which events are posted.  See the EvmConnCreate(3) reference page.  The event that is to be posted to the specified
       connection.  See the EvmEventCreate(3) reference page.  The identifier for the event data item to be set.  See the EvmItemSet(3)  reference
       page  for possible values for this parameter, and the data contained by the data item.  The value to be stored in the associated item indi-
       cated by item_id.

DESCRIPTION

       An EVM client program uses the routines described on this page to pass events to the EVM daemon, for distribution to subscribers.

       EvmEventPost() posts an event that has already been created with EvmEventCreate() or EvmEventCreateVa().

       EvmEventPostVa() allows you to create, post and destroy an event in a single call.  It first creates a new event, adding  to  it  any  data
       items supplied in the call.  If the event parameter is not NULL, the contents of the supplied event are then merged into the new event, and
       the new event is posted.  The new event is destroyed before the routine returns, and the supplied event (if any) is  unchanged.	 Refer	to
       the EvmItemSetVa(3) reference page for details of the item_ids and item_values that may be passed as parameters to this routine.

       If you pass NULL as the connection parameter to either of these routines the event is posted to the local daemon, using a temporary connec-
       tion, which is destroyed before the routine returns.  Because of the overhead associated with creating and destroying  an  EVM  connection,
       you should pass only NULL if your program rarely posts events.

       If  either  routine  is unable to pass the event to the daemon, the error is reported immediately through the return code.  If the event is
       passed to the daemon, the type of response depends on the response mode specified when the connection was created.

NOTES

       These routines do not destroy the event passed as the event parameter.  You must explicitly call EvmEventDestroy() to destroy the event and
       free its memory once it is no longer needed.

       You  should  avoid posting a large number of events in rapid succession, since this may cause the connection's send buffer to fill, and the
       posting process to block until the EVM daemon has relieved some or all of the data.  Although this is a normal part of process synchroniza-
       tion,  some high-performance processes may prefer to block as infrequently as possible.	 EvmConnControl() can be used to increase the size
       of the send buffer.  See the EvmConnControl reference page for more information.

       If you use extended item_ids to supply names and values of variable items to EvmEventPostVa(), be sure to  supply  the  correct	number	of
       parameters  for	each.	A  variable name and value is required for all such items, and some variable types require an additional argument.
       Refer to the EvmItemSetVa(3) reference page for more information.

RESTRICTIONS

       None

RETURN VALUES

       The operation was completed without error.  The EVM daemon rejected the event.  The most likely reasons for this to happen are that no tem-
       plate  has  been  registered for the event, or that the caller is not authorized to post the event.  See the evmtemplate(4) and evm.auth(4)
       reference pages for more information.  One of the arguments to the function was invalid.  A value in a structure  member  is  invalid.	An
       operation  failed  because an attempt to acquire heap memory failed.  The connection's output buffer is full, and the event has been queued
       in heap space.  Another attempt will be made to flush the queue when the next call is made to EvmEventPost(3), or when the  caller  invokes
       EvmConnFlush(3).   This	error code is only returned for connections for which EvmConnControl(3) has been invoked with the request argument
       set to EvmCONN_POST_NONBLOCK_SET.  A read error occurred while reading from the EVM daemon connection.  The connection is no longer usable,
       and  the caller should invoke EvmConnDestroy() to destroy it.  A write error occurred while writing to the EVM daemon connection.  The con-
       nection is no longer usable, and the caller should invoke EvmConnDestroy() to destroy it.

ERRORS

       None

FILES

       None

SEE ALSO

       Routines:  EvmConnControl(3),  EvmConnCreate(3),  EvmConnDestroy(3),  EvmConnRegistrationGet(3),   EvmEventCreate(3),   EvmEventDestroy(3),
	    EvmItemSetVa(3)

       Event Management: EVM(5)

       Event Connection: EvmConnection(5)

       EVM Events: EvmEvent(5)
       delim off

																   EvmEventPost(3)