EvmConnCreate(3) Library Functions Manual EvmConnCreate(3)
NAME
EvmConnCreate, EvmConnCreatePoster, EvmConnCreateSubscriber, EvmConnFdGet, EvmConnDestroy - Establish or destroy connection with the EVM
daemon
LIBRARY
EVM Support Library (libevm.so, libevm.a)
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 EvmConnCreateSubscriber(
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 parameter establishes the function of the connection. Possible values are the following: Creates a connection for use by posting
clients. Creates a connection for use by subscribing clients. The responseMode parameter must be set to EvmRESPONSE_CALLBACK. Creates a
service connection. This mode is not currently supported for general use. This parameter establishes the behavior of certain connection-
oriented API functions when requests are made to the EVM daemon. If a function call results in such a request, the function will return a
response according to the value of this parameter, 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 EvmER-
ROR_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 dae-
mon and blocks until a response is received from the daemon. The status returned by the function may result either from preliminary vali-
dation or from validation by the daemon. If no error is returned by the function, the request has been accepted by the daemon. The func-
tion returns without waiting for a response. Any return status other than EvmERROR_NONE indicates that a problem was detected in prelimi-
nary 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 function to watch for I/O activity on the connection, and then invoke Evm-
ConnDispatch(3) to handle the activity. In most cases, this will result in the connection's callback function being invoked to han-
dle incoming messages.
This response mode must be used for listening connections. This specifies the type of connection to be made to the daemon. You usu-
ally should set this argument to NULL for the default connection 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; trans-
port.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 parameter 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 the EvmCallback(5)
reference page. The calling process should use this argument to pass its own context data for the connection to the callback func-
tion. This parameter should be NULL if no context data is required. For EvmConnCreate() this is the return parameter for the new
connection. For the other routines described on this page, it is the connection to be processed. The return parameter for the file
number associated with the supplied connection.
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
calling 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 equiv-
alent 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 determine 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 signal.
ERRORS
None
FILES
Default pathname for the domain socket.
SEE ALSO
Functions: connect(2), select(2), socket(2)
Routines: EvmConnControl(3), EvmConnDispatch(3), EvmConnWait(3)
Event Management: EVM(5)
Event Callback: EvmCallback(5)
Event Connection: EvmConnection(5)
EVM Events: EvmEvent(5)
Common Desktop Environment: Programmer's Guide
delim off
EvmConnCreate(3)