DESCRIPTION
To receive notification of events as they happen, a program must establish
a listening connection to the EVM daemon, using the
EvmConnCreate()
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)
manpage.
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, the routine passes the
request to the daemon.
The daemon's response is returned through
the connection's callback function, with a reason code of
EvmREASON_SUBSCRIBE_COMPLETE.
The caller must watch for the response using
EvmConnWait()
or a related function, and then invoke
EvmConnDispatch()
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.
The
caller must handle it 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.
The next matching template continues to be 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 must supply a different
user_arg
for each request in the cycle.
The caller must also
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, do not issue a stream of
EvmConnRegistrationGet()
or
EvmConnTemplateScan()
requests before taking any callbacks.
Work in a request/callback/request cycle.
Printable version
