EvmConnSubscribe(3) Library Functions Manual EvmConnSubscribe(3)
NAME
EvmConnSubscribe, EvmConnRegistrationGet, EvmConnTemplateScan - Establishes a subscription for event notification
LIBRARY
EVM Support Library (libevm.so, libevm.a)
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
The connection established to listen for events. See the EvmConnCreate(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 cannot 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 originating request.
DESCRIPTION
To receive notification of events as they happen, a program must establish a listening connection to the EVM daemon, using the EvmConnCre-
ate(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 rou-
tine 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 func-
tion, 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 EvmREA-
SON_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 nececessary 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 tem-
plate 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 connection. A write error occurred while writing to the EVM daemon connection.
ERRORS
None
FILES
None
SEE ALSO
Routines: EvmConnCreate(3), EvmConnDestroy(3), EvmConnWait(3), EvmStatusTextGet(3)
Files: evm.auth(4)
Event Management: EVM(5)
Event Callback: EvmCallback(5)
Event Connection: EvmConnection(5)
Event Filter: EvmFilter(5)
delim off
EvmConnSubscribe(3)