HP-UX Event ManagerProgrammer's Guide

The EvmEvent_t type defines a pointer to a short handle structure that holds some control
information and a pointer to the event body. When you use EvmEventCreate or any related
function to create a new event, the following functions are performed:
• Allocates heap memory separately for the handle and the event body
• Stores the address of the event body in the handle
• Returns the address of the handle as the function's EvmEvent_t output argument
You must use the returned pointer any time you need to refer to the event.
If you modify the event by adding a variable, for example, it is likely that the space used by the
event body may be freed and reallocated in a new location. If this happens, the address stored
in the handle is automatically updated to reflect the new location. As a result, the reallocation is
completely transparent to your program. The location of the handle remains unchanged for the
life of the event.
If you need to transfer an event from one variable to another, you can use a simple C-language
assignment statement between variables of type EvmEvent_t. Because the value you hold is
simply a pointer to a constant location — the event's handle — you can continue to use both of
the variables to refer to the event. However, if you subsequently use EvmEventDestroy to
destroy the event, you must discard both references.
Reassigning an event copies only the reference to its handle; it does not copy the event body. If
you need to make a completely independent copy of the event, use the EvmEventDup function
call.
Callback Functions
EVM posting and subscribing clients connect to the EVM daemon using the EvmConnCreate
function call, and must specify one of three possible response modes: EvmRESPONSE_IGNORE,
EvmRESPONSE_WAIT, or EvmRESPONSE_CALLBACK. For more information about modes, see
EvmConnCreate(3).
The subscribing clients must specify EvmRESPONSE_CALLBACK as the response mode. The
incoming events are passed to them by the callback function that you supply as the fourth
argument to EvmConnCreate. For an example of the usage of a callback function by a subscribing
client, see “Subscribing Event Notifications” (page 43).
When working with a callback function, it is important to understand that your function is not
called asynchronously, in the manner of a signal handler. Rather, your program must monitor
the connection for input activity, using EvmConnWait or select or a related function, and then
call EvmConnDispatch to handle the activity. EvmConnDispatch then reads an incoming
message from the connection and invokes your callback function, if necessary. For a list of reasons
for callback being invoked, see EvmCallback(5).
As with any function, the arguments passed to your callback function are passed on the program
stack and are available only within the scope of the function. Therefore, to save values for use
after you have returned from the callback, you must copy them to global memory space before
returning.
If the callback is reporting an incoming event and you want to preserve the event instead of
handling it and then destroying it within the callback, you can declare a globally accessible
variable of type EvmEvent_t and assign the incoming event to it, for example:
/* In global declarations */
EvmEvent_t SavedEvent;
...
/* In your callback function */
SavedEvent = cbdata->event;
In this case, you must not destroy the event in the callback function, because the assignment
copies only the reference to the event, not the event body. You need to destroy the event from
Callback Functions 33