evmcallback(5) [osf1 man page]
EvmCallback(5) File Formats Manual EvmCallback(5) NAME
EvmCallback - Event Management callback function SYNOPSIS
void EventCB( EvmConnection_t connection, EvmCallbackArg_t callbackArg, EvmCallbackData_t *callbackData) DESCRIPTION
An EVM callback function is a function that you provide to allow your program to handle messages arriving on an EVM connection. Most mes- sages will be incoming events or responses to requests you have made to the EVM daemon, but you may also get a callback for other reasons. You specify the name (EventCB) of the callback function in the callback parameter when you create an EVM connection with a response mode of callback. Your callback function is invoked by EvmConnDispatch(), which you must call whenever you detect activity pending on the connection. An EVM callback function must conform to the prototype shown. Callback function parameters: The connection parameter contains the connection context pertaining to this callback. This value was returned by EvmConnCreate() when the connection was created. If you have one callback function servicing multiple connections, you might test this to determine which connection a particular invocation is handling. The callbackArg parameter contains the value you specified as the callbackArg parameter to EvmCon- nCreate() when you created the connection. For example, you might use it to hold a pointer to your own context data for the connection. The callbackData parameter points to a structure containing the details of the callback. The structure includes a callback reason code, an event, and a union containing data specific to each possible reason. The event member may contain NULL if it is not applicable to the rea- son. You may get these reasons: This callback reason indicates that the daemon was unable to deliver one or more events, probably because the client process had not finished processing earlier events, causing the connection buffer to overflow. If necessary, you can use Evm- ConnControl(3) to increase the size of the receive buffer. This callback reason indicates that an EVM event has been received from the daemon. The event is available in the callbackData structure. You must use EvmEventDestroy(3) to free the event when you have finished with it. This callback reason indicates that a prior EvmEventPost() call has completed, usually with a response from the daemon if the responseMode was specified as EvmRESPONSE_CALLBACK when the connection was created. The posting status is available in the callbackData structure. This callback reason indicates that a requested template has been delivered in response to an EvmConnRegistrationGet() request. You must use EvmEventDestroy(3) to free the template when you have finished with it. This callback reason indicates that a prior EvmEventSubscribe() call has completed, usually with a response from the daemon. This callback reason indicates that event template infor- mation has been delivered in response to an EvmConnTemplateScan() request. The template is available in the callbackData structure. You must use EvmEventDestroy(3) to free the template when you have finished with it. See the Common Desktop Environment: Programmer's Guide for examples of callback functions. FILES
Header file that contains the event declaration, structures, and prototype for the callback function SEE ALSO
Routines: EvmConnCreate(3), EvmConnCheck(3), EvmConnSubscribe(3), EvmEventPost(3) Event Management: EVM(5) Event Connection: EvmConnection(5) EVM Events: EvmEvent(5) Common Desktop Environment: Programmer's Guide delim off EvmCallback(5)
Check Out this Related Man Page
EvmConnCreate(3) Library Functions Manual EvmConnCreate(3) NAME
EvmConnCreate(), EvmConnCreatePoster(), EvmConnCreateSubscriber(), EvmConnDestroy(), EvmConnFdGet() - establish or destroy connection with the EVM daemon SYNOPSIS
Library EVM Support Library Parameters type Establishes the function of the connection. Possible values are as follows: Creates a connection for use by posting clients. Creates a connection for use by subscribing clients. The responseMode operand must be set to responseMode Establishes the behavior of certain connection-oriented API functions when requests are made to the EVM daemon. If a func- tion call results in such a request, the function returns a response according 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 indicates that a problem was detected in preliminary validation. A response of signifies only that the request was sent to the daemon. An response cannot determine if the request was received or accepted. The function does preliminary validation, returning a status reflecting any error it finds. If the function 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 function 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 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 The calling process must use or a related function to watch for I/O activity on the connection, and then invoke to handle the activity. In most cases, the connection's callback function is invoked to handle incoming messages. This response mode must be used for listening connections. transport Specify the type of connection to be made to the daemon. Because EVM currently supports only local connection the daemon, this argument must always be set to NULL. If this argument is not NULL, an error occurs. callback A pointer to a routine that is to be called by to process an incoming message. The routine is declared as described in the EvmCallback(5) manpage. If the response mode is not this operand is NULL. callbackArg This argument is supplied each time the callback routine is invoked by See EvmCallback(5). The calling process uses this argument to pass its own context data for the connection to the callback function. If no context data is required, this op- erand is NULL. connection For connection is the return operand for the new connection. For the other routines described on this manpage, connection is the EVM connection to be processed. fd The return operand for the file number associated with the supplied connection. DESCRIPTION
The routine establishes a connection between a client process and the EVM daemon. If the connection is successful, a pointer to a new con- nection context is returned in the connection argument. The routine is a macro that establishes a posting connection to the local daemon. Using this macro is equivalent to calling with type set to responseMode set to and transport, callback,and callbackArg are all set to NULL. The routine is a macro that establishes a subscribing connection to the local daemon. Using this macro is equivalent to calling with type set to responseMode set to and transport set to NULL. The 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 to determine when there is activity on the connection. The program must call to handle the activity. It must not close the file descriptor, nor perform any direct I/O on it. The routine destroys the connection and frees any resources associated with it. This routine must be called to destroy the connection. RETURN VALUE
The operation completed without error. One of the arguments to the function is 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 to destroy the connection. The current operation was interrupted by receipt of a signal. ERRORS
The value of is not set. 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). Event Management EVM(5). Event Callback EvmCallback(5). Event Connection EvmConnection(5). EVM Events EvmEvent(5). EvmConnCreate(3)