EvmConnection(5)EvmConnection(5)NAMEEvmConnection - Connection to the Event Management daemon
DESCRIPTION
An EVM connection is the context through which data is passed to and
from the EVM daemon. A connection has the following attributes: Con‐
nection Type Response Mode Transport Type Callback, and associated
Callback Argument Connection Context
These attributes are described in the following sections.
An EVM client is any program that processes events through the EVM dae‐
mon. EVM supports three distinct types of client: posting clients,
subscribing (listening) clients, and service clients. Regardless of
type, all clients connect to the EVM daemon in the same way.
Connection Type
The type of connection established determines the client type. There
are associated constants to be used when the connection is created.
The client uses this connection to post events to the daemon for dis‐
tribution. The client uses this connection to listen for events dis‐
tributed by the daemon. The client uses this connection to request
that the daemon provide a service, such as retrieve events from a log.
A client may use all three types of connection, but must establish each
connection separately.
Response Mode
The response mode associated with a connection determines the manner in
which certain API functions will deal with the daemon's responses to
request messages. See the EvmConnCreate(3) reference page for full
details of each mode. The modes are: The API functions will return as
soon as the request has been sent to the daemon, and the caller will
not receive the daemon's response. The API functions will send the
request to the daemon, and wait until a response has been received
before returning to the caller. The returned status code will reflect
the response. The API functions will return as soon as the request has
been sent to the daemon, and the caller must monitor the connection for
a response. When the response is received, the connection's callback
function will be invoked to handle it.
Transport type
This specifies the type of connection to be made to the daemon. Valid
connection types are as follows: Connection is through a domain socket
to a daemon running on the local host. Connection is through a TCP/IP
socket to a daemon running on a remote host.
Callback
This attribute specifies the function you want to handle any incoming
responses resulting from activity on the connection. Callbacks are dis‐
cussed in more detail in the EvmCallback(5) reference page. This
attribute is valid only when the Response Mode is EvmRESPONSE_CALLBACK.
Connection Context
This attribute is a handle to a connection returned when a connection
is created. You must pass this handle to all other functions you call
which need to access the connection.
Connection Monitoring
Once you have established a connection, the API functions will take
care of all communication activity with the daemon. However, you must
make sure that these functions get an opportunity to do their work when
activity occurs. EVM provides several ways for you to do this - the
method you choose depends on the model of your program. If your pro‐
gram is I/O driven, waiting for I/O to occur on one or more file
descriptors, handling activity as it occurs and then returning to wait
for more I/O, it probably spends most of its time in a select() call.
In this case, you should use EvmConnFdGet() to establish which file
descriptor the EVM connection is using, and then include that fd in
your select() read mask. When you detect activity on the connection,
invoke EvmConnDispatch() to handle the activity. If your program is
driven purely by activity on a single EVM connection, you can let the
API handle the I/O entirely by using EvmConnWait() to wait for activity
to occur on the connection. When the function returns, dispatch the I/O
using EvmConnDispatch(), and then return to EvmConnWait(). If your
program is driven in some other way, and there are certain points (for
example, at the end of some control loop) at which you want to handle
EVM activity, you can call EvmConnCheck() to check for any outstanding
activity. If this function indicates that there is something to do, you
can call EvmConnDispatch(); otherwise you can continue immediately with
normal processing.
Destroying a connection
When you are finished with the connection, use EvmConnDestroy() to dis‐
connect from the daemon. It is important to check the return status
for any failure each time you call a connection function and destroy
the connection if a failure occurred. The file descriptor associated
with the connection remains open until you destroy the connection even
if I/O errors have been detected on the connection.
SEE ALSO
Functions: select(2)
Routines: EvmConnControl(3), EvmConnCreate(3), EvmConnFdGet(3), EvmCon‐
nCheck(3), EvmConnWait(3), EvmConnDispatch(3), EvmConnDestroy(3)
Event Management: EVM(5)
Event Callback: EvmCallback(5)
EVM Events: EvmEvent(5)EvmConnection(5)