Index for Section 3

Alphabetical listing for E

Bottom of page

EvmConnSubscribe(3)
NAME
  EvmConnSubscribe, EvmConnRegistrationGet, EvmConnTemplateScan - Establishes
  a subscription for event notification

SYNOPSIS
  #include <evm/evm.h>

  EvmStatus_t EvmConnSubscribe(
	  EvmConnection_t connection,
	  void *unused,
	  EvmString_t filter_string );

  EvmStatus_t EvmConnRegistrationGet(
	  EvmConnection_t connection,
	  const EvmString_t event_class,
	  EvmPointer_t user_arg );

  EvmStatus_t EvmConnTemplateScan(
	  EvmConnection_t connection,
	  const EvmString_t filter_string,
	  EvmPointer_t user_arg );

OPERANDS
  connection
      The connection established to listen for events. See the
      EvmConnCreate(3) reference page.

  unused
      This parameter must be specified as NULL.

  filter_string
      A string specifying the events of interest. For a formal description of
      the syntax of the filter_string, see the EvmFilter(5) reference page.

  event_class
      An event name string having at least one component. An event class
      cannot contain wildcard characters.

  user_arg
      The value supplied in this parameter is returned in the callback
      function's extended callback structure, and can be used by the calling
      code to match the callback with the originating request.

DESCRIPTION
  To receive notification of events as they happen, a program must establish
  a listening connection to the EVM daemon, using the EvmConnCreate(3)
  routine. The program must then call EvmConnSubscribe() to associate a
  filter with the connection. Whenever the daemon receives an event matching
  the filter, it delivers the event to the subscriber.	The subscriber must
  handle incoming events using the API routines described in the
  EvmConnWait(3) reference page.

  The EvmConnSubscribe() routine passes the supplied filter_string to the EVM
  daemon, to select a set of events for subscription. The routine returns
  immediately if preliminary validation fails; otherwise it passes the
  request to the daemon, and the daemon's response will be returned through
  the connection's callback function, with a reason code of
  EvmREASON_SUBSCRIBE_COMPLETE. The caller must watch for the response using
  EvmConnWait() (3) or a related function, and then invoke EvmConnDispatch()
  (3) to handle it.

  The EvmConnRegistrationGet() routine asks the daemon to return the event
  template corresponding to the supplied event_class, if the event is
  registered. The daemon responds by returning the event template, in the
  form of an EVM event, through the connection's callback function, with a
  reason code of EvmREASON_TEMPLATE_INFO_DELIVERED.

  If the event class is registered, the event field in the extended callback
  data structure holds an event corresponding to the template, which the
  caller must handle as if it were an incoming event. If the event class is
  not registered, the callback status code is set to EvmERROR_NOT_PRESENT,
  and the event handle in the structure is set to NULL.

  The EvmConnTemplateScan() routine asks the daemon to return a series of
  event templates that match the supplied filter_string. The daemon responds
  by returning event templates, in the form of EVM events, through the
  connection's callback function, with a reason code of
  EvmREASON_TEMPLATE_INFO_DELIVERED.

  The first time the function is called a single event template is returned,
  if one is available. On subsequent calls that have the filter_string
  parameter set to NULL, the next matching template is returned, until all
  templates that match the original filter_string have been returned.

  If it is necessary to match individual callback responses with their
  original requests, the caller should supply a different user_arg for each
  request in the cycle, and verify that each incoming template relates to the
  expected request.

NOTES
  The daemon does not return templates for which the user does not have
  access authorization.

  To avoid missing incoming templates you should not issue a stream of
  EvmConnRegistrationGet() or EvmConnTemplateScan() requests before taking
  any callbacks, but work in a request/callback/request cycle.

RETURN VALUES
  EvmERROR_NONE
      The operation was completed without error.

  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_NOT_PRESENT
      For the EvmConnRegistrationGet() routine the requested event template
      is not registered.

      For the EvmConnTemplateScan() routine, there is no match for the
      specified filter_string, or the template list is exhausted.

  EvmERROR_READ
      A read error occurred while reading from the EVM daemon connection.

  EvmERROR_WRITE
      A write error occurred while writing to the EVM daemon connection.

ERRORS
  None

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

FILES
  None

SEE ALSO
  Routines: EvmConnCreate(3), EvmConnDestroy(3), EvmConnWait(3),
  EvmStatusTextGet(3)

  Files: evm.auth(4), kevm(7)

  Event Management: EVM(5)

  Event Callback: EvmCallback(5)

  Event Connection: EvmConnection(5)

  Event Filter: EvmFilter(5)

Index for Section 3

Alphabetical listing for E

Top of page