PTREE_REGISTER_HANDLER(3PICLTREE) PICL Plug-In Library Functions

NAME

ptree_register_handler - register a handler for the event

SYNOPSIS

cc [ flag... ] file... -lpicltree [ library... ]
#include <picltree.h>

int ptree_register_handler(const char *ename,
void (*evt_handler)(const char *ename, const void *earg,
size_t size, void *cookie), void *cookie);

DESCRIPTION

The ptree_register_handler() function registers an event handler for
a PICL event. The argument ename specifies the name of the PICL event
for which to register the handler. The argument evt_handler specifies
the event handler function. The argument cookie is a pointer to
caller-specific data to be passed as an argument to the event handler
when it is invoked.


The event handler function must be defined as

void evt_handler(const char *ename, const void *earg, \
size_t size, void *cookie)


where, ename, earg, size, and cookie are the arguments passed to the
event handler when it is invoked. The argument ename is the PICL
event name for which the handler is invoked. The arguments earg and
size gives the pointer to the event argument buffer and its size,
respectively. The argument cookie is the pointer to the caller
specific data registered with the handler. The arguments ename and
earg point to buffers that are transient and shall not be modified by
the event handler or reused after the event handler finishes
execution.


The PICL framework invokes the event handlers in the order in which
they were registered when dispatching an event. If the event handler
execution order is required to be the same as the plug-in dependency
order, then a plug-in should register its handlers from its init
function. The handlers that do not have any ordering dependencies on
other plug-in handlers can be registered at any time.


The registered handler may be called at any time after this function
is called.

RETURN VALUES

Upon successful completion, 0 is returned. On failure, a non-negative
integer is returned to indicate an error and the handler is not
registered.

ERRORS

PICL_INVALIDARG
Invalid argument


PICL_FAILURE
General system failure

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+

SEE ALSO

ptree_unregister_handler(3PICLTREE), attributes(7)

August 1, 2000
PTREE_REGISTER_HANDLER(3PICLTREE)