Index Index for
Section 3
Index Alphabetical
listing for E
Bottom of page Bottom of
page		 

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

  connection
	  The connection through which events are posted.  See the
	  EvmConnCreate(3) reference page.

  event	  The event that is to be posted to the specified connection.  See
	  the EvmEventCreate(3) reference page.

  item_id 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.

  item_value
	  The value to be stored in the associated item indicated 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 connection,
  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 synchronization, 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

  EvmERROR_NONE
	The operation was completed without error.

  EvmERROR_EVENT_REJECTED
	The EVM daemon rejected the event.  The most likely reasons for this
	to happen are that no template 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.

  EvmERROR_INVALID_ARGUMENT
	One of the arguments to the function was invalid.

  EvmERROR_INVALID_VALUE
	A value in a structure member is invalid.

  EvmERROR_NO_MEMORY
	An operation failed because an attempt to acquire heap memory failed.

  EvmERROR_QUEUED
	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.

  EvmERROR_READ
	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.

  EvmERROR_WRITE
	A write error occurred while writing to the EVM daemon connection.
	The connection 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)

Index Index for
Section 3
Index Alphabetical
listing for E
Top of page Top of
page