usr/src/man/man3picltree/ptree_register_handler.3picltree

   1 '\" te
   2 .\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PTREE_REGISTER_HANDLER 3PICLTREE "Aug 1, 2000"
   7 .SH NAME
   8 ptree_register_handler \- register a handler for the event
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lpicltree\fR [ \fIlibrary\fR... ]
  13 #include <picltree.h>
  14
  15 \fBint\fR \fBptree_register_handler\fR(\fBconst char *\fR\fIename\fR,
  16      \fBvoid (*\fR\fIevt_handler\fR)(\fBconst char *\fR\fIename\fR, const void *\fIearg\fR,
  17      \fBsize_t\fR \fIsize\fR, \fBvoid *\fR\fIcookie\fR), \fBvoid *\fR\fIcookie\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The \fBptree_register_handler()\fR function registers an event handler for a
  24 PICL event. The argument \fIename\fR specifies the name of the PICL event for
  25 which to register the handler. The argument \fIevt_handler\fR specifies the
  26 event handler function. The argument \fIcookie\fR is a pointer to
  27 caller-specific data to be passed as an argument to the event handler when it
  28 is invoked.
  29 .sp
  30 .LP
  31 The event handler function must be defined as
  32 .sp
  33 .in +2
  34 .nf
  35 void evt_handler(const char *\fIename\fR, const void *\fIearg\fR, \e
  36         size_t \fIsize\fR, void *\fIcookie\fR)
  37 .fi
  38 .in -2
  39
  40 .sp
  41 .LP
  42 where, \fIename\fR, \fIearg\fR, \fIsize\fR, and \fIcookie\fR are the arguments
  43 passed to the event handler when it is invoked. The argument \fIename\fR is the
  44 PICL event name for which the handler is invoked. The arguments \fIearg\fR and
  45 \fIsize\fR gives the pointer to the event argument buffer and its size,
  46 respectively. The argument \fIcookie\fR is the pointer to the caller specific
  47 data registered with the handler. The arguments \fIename\fR and \fIearg\fR
  48 point to buffers that are transient and shall not be modified by the event
  49 handler or reused after the event handler finishes execution.
  50 .sp
  51 .LP
  52 The PICL framework invokes the event handlers in the order in which they were
  53 registered when dispatching an event. If the event handler execution order is
  54 required to be the same as the plug-in dependency order, then a plug-in should
  55 register its handlers from its init function. The handlers that do not have any
  56 ordering dependencies on other plug-in handlers can be registered at any time.
  57 .sp
  58 .LP
  59 The registered handler may be called at any time after this function is called.
  60 .SH RETURN VALUES
  61 .sp
  62 .LP
  63 Upon successful completion, \fB0\fR is returned. On failure, a non-negative
  64 integer is returned to indicate an error and the handler is not registered.
  65 .SH ERRORS
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBPICL_INVALIDARG\fR\fR
  70 .ad
  71 .RS 19n
  72 Invalid argument
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBPICL_FAILURE\fR\fR
  79 .ad
  80 .RS 19n
  81 General system failure
  82 .RE
  83
  84 .SH ATTRIBUTES
  85 .sp
  86 .LP
  87 See \fBattributes\fR(7) for descriptions of the following attributes:
  88 .sp
  89
  90 .sp
  91 .TS
  92 box;
  93 c | c
  94 l | l .
  95 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  96 _
  97 Interface Stability     Evolving
  98 _
  99 MT-Level        MT-Safe
 100 .TE
 101
 102 .SH SEE ALSO
 103 .sp
 104 .LP
 105 .BR ptree_unregister_handler (3PICLTREE),
 106 .BR attributes (7)