EvmConnSubscribe(3)EvmConnSubscribe(3)NAME
EvmConnSubscribe, EvmConnRegistrationGet, EvmConnTemplateScan - Estab‐
lishes a subscription for event notification
SYNOPSIS
#include <evm/evm.h>
EvmStatus_t EvmConnSubscribe(
EvmConnection_t connection,
void *unused,
EvmString_t filter_string ); EvmStatus_t EvmConnRegistra‐
tionGet(
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
The connection established to listen for events. See the EvmConnCre‐
ate(3) reference page. This parameter must be specified as NULL. A
string specifying the events of interest. For a formal description of
the syntax of the filter_string, see the EvmFilter(5) reference page.
An event name string having at least one component. An event class can‐
not contain wildcard characters. 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 origi‐
nating request.
DESCRIPTION
To receive notification of events as they happen, a program must estab‐
lish a listening connection to the EVM daemon, using the EvmConnCre‐
ate(3) routine. The program must then call EvmConnSubscribe() to asso‐
ciate 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 EvmCon‐
nDispatch() (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 call‐
back 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 EvmER‐
ROR_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 Evm‐
REASON_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 fil‐
ter_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 tak‐
ing any callbacks, but work in a request/callback/request cycle.
RETURN VALUES
The operation was 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 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. A
read error occurred while reading from the EVM daemon connec‐
tion. 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), EvmSta‐
tusTextGet(3)
Files: evm.auth(4), kevm(7)
Event Management: EVM(5)
Event Callback: EvmCallback(5)
Event Connection: EvmConnection(5)
Event Filter: EvmFilter(5)EvmConnSubscribe(3)