EvmConnCreate(3)EvmConnCreate(3)NAME
EvmConnCreate, EvmConnCreatePoster, EvmConnCreateSubscriber, EvmConnFd‐
Get, EvmConnDestroy - Establish or destroy connection with the EVM dae‐
mon
SYNOPSIS
#include <evm/evm.h>
EvmStatus_t EvmConnCreate(
EvmConnectionType_t type,
EvmResponseMode_t responseMode,
const EvmTransport_t transport,
EvmCallback_t callback,
EvmCallbackArg_t callbackArg,
EvmConnection_t *connection ); EvmStatus_t EvmConnCreatePoster(
EvmConnection_t *connection ); EvmStatus_t EvmConnCreateSub‐
scriber(
EvmCallback_t callback,
EvmCallbackArg_t callbackArg,
EvmConnection_t *connection ); EvmStatus_t EvmConnFdGet(
EvmConnection_t connection,
EvmFd_t *fd ); EvmStatus_t EvmConnDestroy(
EvmConnection_t connection );
OPERANDS
This operand establishes the function of the connection. Possible val‐
ues are the following: Creates a connection for use by posting clients.
Creates a connection for use by subscribing clients. The responseMode
operand must be set to EvmRESPONSE_CALLBACK. Creates a service connec‐
tion. This mode is not currently supported for general use. This oper‐
and establishes the behavior of certain connection-oriented API func‐
tions when requests are made to the EVM daemon. If a function call
results in such a request, the function will return a response accord‐
ing to the value of this operand, as follows: The function returns
without waiting for the daemon's response. In this mode, any return
status other than EvmERROR_NONE indicates that a problem was detected
in preliminary validation. A response of EvmERROR_NONE signifies only
that the request was sent to the daemon; you cannot establish whether
it was received or accepted. The function does preliminary validation,
returning a status reflecting any error it finds. If it finds no
error, it passes the request to the EVM daemon and blocks until a
response is received from the daemon. The status returned by the func‐
tion may result either from preliminary validation or from validation
by the daemon. If no error is returned by the function, the request
has been accepted by the daemon. The function returns without waiting
for a response. Any return status other than EvmERROR_NONE indicates
that a problem was detected in preliminary validation.
If no error is found, the function passes the request to the EVM
daemon, and returns immediately with a status of EvmERROR_NONE.
The calling process must use EvmConnWait(3) or a related func‐
tion to watch for I/O activity on the connection, and then
invoke EvmConnDispatch(3) to handle the activity. In most cases,
this will result in the connection's callback function being
invoked to handle incoming messages.
This response mode must be used for listening connections. This
specifies the type of connection to be made to the daemon. You
usually should set this argument to NULL for the default connec‐
tion to the local daemon. For remote connection, set it to the
address of an EvmTransport_t structure, transport, initialized
in the following manner: transport.type = EvmTRANSPORT_TCPIP;
transport.data.tcpip.portNumber = -1; /* -1 for default port */
transport.data.tcpip.hostName = "remote_system_address"; A
pointer to a routine that will be called by EvmConnDispatch() to
process an incoming message. The routine must be declared as
described in the EvmCallback(5) reference page. This operand
should be NULL if the response mode is not EvmRESPONSE_CALLBACK.
The argument that will be supplied as the callbackArg argument
each time the callback routine is invoked by EvmConnDispatch().
See EvmCallback(5). The calling process should use this argu‐
ment to pass its own context data for the connection to the
callback function. This operand should be NULL if no context
data is required. For EvmConnCreate() this is the return oper‐
and for the new connection. For the other routines described on
this page, it is the connection to be processed. The return op‐
erand for the file number associated with the supplied connec‐
tion.
DESCRIPTION
The EvmConnCreate() routine establishes a connection between a client
process and the EVM daemon. If the connection is successful, a pointer
to a new connection context is returned in the connection argument.
The EvmConnCreatePoster() routine is a macro that establishes a posting
connection to the local daemon. Using this macro is equivalent to call‐
ing EvmConnCreate() with type set to EvmCONNECTION_POST, responseMode
set to EvmRESPONSE_WAIT, and transport, callback and callbackArg all
set to NULL.
The EvmConnCreateSubscriber() routine is a macro that establishes a
subscribing connection to the local daemon. Using this macro is equiva‐
lent to calling EvmConnCreate() with type set to EvmCONNECTION_LISTEN,
responseMode set to EvmRESPONSE_CALLBACK, and transport set to NULL.
The EvmConnFdGet() routine returns the file number associated with the
connection. This file number can be used by a client application, which
handles multiple I/O sources, for use in a call to select(2) to deter‐
mine when there is activity on the connection. The program must call
EvmConnDispatch() to handle the activity. It must not close the file
descriptor, nor perform any direct I/O on it.
The EvmConnDestroy() routine destroys the connection and frees any
resources associated with it. This routine must be called to destroy
the connection.
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. A
read error occurred while reading from the EVM daemon connection. A
write error occurred while writing to the EVM daemon connection. An
error occurred while attempting to connect to the EVM daemon. An error
occurred on the EVM connection. Invoke EvmConnDestroy() to destroy the
connection. The current operation was interrupted by receipt of a sig‐
nal.
ERRORS
None
LIBRARY
EVM Support Library (libevm.so, libevm.a)
FILES
Default pathname for the domain socket.
SEE ALSO
Commands: evmget(1), evmpost(1), evmwatch(1)
Functions: connect(2), select(2), socket(2)
Routines: EvmConnControl(3), EvmConnDispatch(3), EvmConnWait(3)
Files: kevm(7)
Event Management: EVM(5)
Event Callback: EvmCallback(5)
Event Connection: EvmConnection(5)
EVM Events: EvmEvent(5)
Programmer's Guide
EvmConnCreate(3)