EvmConnSubscribe(3)EvmConnSubscribe(3)NAMEEvmConnSubscribe(), EvmConnRegistrationGet(), EvmConnTemplateScan()-
establish a subscription for event notification
SYNOPSIS
Library
EVM Support Library
Parameters
connection The EVM connection established to listen for events. See
the EvmConnCreate(3) manpage.
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) manpage.
event_class An event name string having at least one component of the
event name. An event class cannot contain wildcard char‐
acters. For example, in the EVM event name of and are
components of the event name.
user_arg The value supplied in this parameter is returned in the
callback function's extended callback structure. The
value can be used by the calling code to match the call‐
back with the originating request.
DESCRIPTION
To receive notification of events as they happen, a program must estab‐
lish a listening connection to the EVM daemon, using the routine. The
program must then call 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 routine passes the supplied filter_string to the EVM daemon to
select a set of events for subscription. The routine returns immedi‐
ately 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 The caller
must watch for the response using or a related function, and then
invoke to handle it.
The 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
If the event class is registered, the event field in the extended call‐
back 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 and the event handle in the structure is set to NULL.
The 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
The first time the function is called, a single event template is
returned, if one is available. On subsequent calls that have the fil‐
ter_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 or
requests before taking any callbacks. Work in a request/call‐
back/request cycle.
RETURN VALUE
The operation completed without error.
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.
For the
routine, the requested event template is not registered.
For the routine, there is no match for the specified fil‐
ter_string, or the template list is exhausted.
A read error occurred while reading from the EVM daemon connection.
A write error occurred while writing to the EVM daemon connection.
ERRORS
The value of is not set.
SEE ALSO
Routines
EvmConnCreate(3), EvmConnDestroy(3), EvmConnWait(3), EvmStatus‐
TextGet(3).
Files
evm.auth(4).
Event Management
EVM(5).
Event Callback
EvmCallback(5).
Event Connection
EvmConnection(5).
Event Filter
EvmFilter(5).
EvmConnSubscribe(3)