unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



EvmConnection(5)					     EvmConnection(5)



NAME

  EvmConnection	- Connection to	the Event Management daemon

DESCRIPTION

  An EVM connection is the context through which data is passed	to and from
  the EVM daemon.  A connection	has the	following attributes:

    +  Connection Type

    +  Response	Mode

    +  Transport Type

    +  Callback, and associated	Callback Argument

    +  Connection Context

  These	attributes are described in the	following sections.

  An EVM client	is any program that processes events through the EVM daemon.
  EVM supports three distinct types of client: posting clients,	subscribing
  (listening) clients, and service clients. Regardless of type,	all clients
  connect to the EVM daemon in the same	way.

  Connection Type


  The type of connection established determines	the client type.  There	are
  associated constants to be used when the connection is created.

  Posting Connection (EvmCONNECTION_POST)
      The client uses this connection to post events to	the daemon for dis-
      tribution.

  Listening Connection (EvmCONNECTION_LISTEN)
      The client uses this connection to listen	for events distributed by the
      daemon.

  Service Connection (EvmCONNECTION_SERVICE)
      The client uses this connection to request that the daemon provide a
      service, such as retrieve	events from a log.

  A client may use all three types of connection, but must establish each
  connection separately.








  Response Mode


  The response mode associated with a connection determines the	manner in
  which	certain	API functions will deal	with the daemon's responses to
  request messages.  See the EvmConnCreate(3) reference	page for full details
  of each mode.	 The modes are:

  Ignore (EvmRESPONSE_IGNORE)
      The API functions	will return as soon as the request has been sent to
      the daemon, and the caller will not receive the daemon's response.

  Wait (EvmRESPONSE_WAIT)
      The API functions	will send the request to the daemon, and wait until a
      response has been	received before	returning to the caller.  The
      returned status code will	reflect	the response.

  Callback (EvmRESPONSE_CALLBACK)
      The API functions	will return as soon as the request has been sent to
      the daemon, and the caller must monitor the connection for a response.
      When the response	is received, the connection's callback function	will
      be invoked to handle it.

  Transport type


  This specifies the type of connection	to be made to the daemon.  Valid con-
  nection types	are as follows:

  Local	Connection (EvmTRANSPORT_DOMAIN_SOCKET)
      Connection is through a domain socket to a daemon	running	on the local
      host.

  Remote Connection (EvmTRANSPORT_TCPIP)
      Connection is through a TCP/IP socket to a daemon	running	on a remote
      host.

  Callback


  This attribute specifies the function	you want to handle any incoming
  responses resulting from activity on the connection. Callbacks are dis-
  cussed in more detail	in the EvmCallback(5) reference	page.  This attribute
  is valid only	when the Response Mode is EvmRESPONSE_CALLBACK.

  Connection Context


  This attribute is a handle to	a connection returned when a connection	is
  created. You must pass this handle to	all other functions you	call which
  need to access the connection.

  Connection Monitoring


  Once you have	established a connection, the API functions will take care of
  all communication activity with the daemon. However, you must	make sure
  that these functions get an opportunity to do	their work when	activity
  occurs. EVM provides several ways for	you to do this - the method you
  choose depends on the	model of your program.

    +  If your program is I/O driven, waiting for I/O to occur on one or more
       file descriptors, handling activity as it occurs	and then returning to
       wait for	more I/O, it probably spends most of its time in a select()
       call. In	this case, you should use EvmConnFdGet() to establish which
       file descriptor the EVM connection is using, and	then include that fd
       in your select()	read mask. When	you detect activity on the connec-
       tion, invoke EvmConnDispatch() to handle	the activity.

    +  If your program is driven purely	by activity on a single	EVM connec-
       tion, you can let the API handle	the I/O	entirely by using
       EvmConnWait() to	wait for activity to occur on the connection. When
       the function returns, dispatch the I/O using EvmConnDispatch(), and
       then return to EvmConnWait().

    +  If your program is driven in some other way, and	there are certain
       points (for example, at the end of some control loop) at	which you
       want to handle EVM activity, you	can call EvmConnCheck()	to check for
       any outstanding activity. If this function indicates that there is
       something to do,	you can	call EvmConnDispatch();	otherwise you can
       continue	immediately with normal	processing.

  Destroying a connection


  When you are finished	with the connection, use EvmConnDestroy() to discon-
  nect from the	daemon.	 It is important to check the return status for	any
  failure each time you	call a connection function and destroy the connection
  if a failure occurred.  The file descriptor associated with the connection
  remains open until you destroy the connection	even if	I/O errors have	been
  detected on the connection.

SEE ALSO

  Functions: select(2)

  Routines: EvmConnControl(3), EvmConnCreate(3), EvmConnFdGet(3),
  EvmConnCheck(3), EvmConnWait(3), EvmConnDispatch(3), EvmConnDestroy(3)

  Event	Management: EVM(5)

  Event	Callback: EvmCallback(5)

  EVM Events: EvmEvent(5)