share/man/man3picltree/ptree_post_event.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_POST_EVENT 3PICLTREE "Aug 1, 2000"
   7 .SH NAME
   8 ptree_post_event \- post a PICL 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_post_event\fR(\fBconst char *\fR\fIename\fR, \fBconst void *\fR\fIearg\fR,
  16      \fBsize_t\fR \fIsize\fR, \fBvoid (*\fR\fIcompletion_handler\fR)(char *\fIename\fR,
  17      \fBvoid *\fR\fIearg\fR, \fBsize_t\fR \fIsize\fR));
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The \fBptree_post_event()\fR function posts the specified event and its
  24 arguments to the PICL framework. The argument \fIename\fR specifies a pointer
  25 to a string containing the name of the PICL event. The arguments \fIearg\fR and
  26 \fIsize\fR specify a pointer to a buffer containing the event arguments and
  27 size of that buffer, respectively. The argument \fIcompletion_handler\fR
  28 specifies the completion handler to be called after the event has been
  29 dispatched to all handlers. A \fINULL\fR value for a completion handler
  30 indicates that no handler should be called. The PICL framework invokes the
  31 completion handler of an event with the \fIename\fR, \fIearg\fR, and \fIsize\fR
  32 arguments specified at the time of the posting of the event.
  33 .sp
  34 .LP
  35 PICL events are dispatched in the order in which they were posted. They are
  36 dispatched by executing the handlers registered for that event.  The handlers
  37 are invoked in the order in which they were registered.
  38 .sp
  39 .LP
  40 New events will not begin execution until all previous events have finished
  41 execution. Specifically, an event posted from an event handler will not begin
  42 execution until the current event has finished execution.
  43 .sp
  44 .LP
  45 The caller may not reuse or reclaim the resources associated with the event
  46 name and arguments until the invocation of the completion handler.  The
  47 completion handlers are normally used to reclaim any resources allocated for
  48 the posting of an event.
  49 .SH RETURN VALUES
  50 .sp
  51 .LP
  52 Upon successful completion, \fB0\fR is returned. On failure, a non-negative
  53 integer is returned to indicate an error, the event is not posted, and the
  54 completion handler is not invoked.
  55 .SH ERRORS
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fBPICL_INVALIDARG\fR\fR
  60 .ad
  61 .RS 19n
  62 Invalid argument
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBPICL_FAILURE\fR\fR
  69 .ad
  70 .RS 19n
  71 General system failure
  72 .RE
  73
  74 .SH ATTRIBUTES
  75 .sp
  76 .LP
  77 See \fBattributes\fR(5) for descriptions of the following attributes:
  78 .sp
  79
  80 .sp
  81 .TS
  82 box;
  83 c | c
  84 l | l .
  85 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  86 _
  87 Interface Stability     Evolving
  88 _
  89 MT-Level        MT-Safe
  90 .TE
  91
  92 .SH SEE ALSO
  93 .sp
  94 .LP
  95 \fBptree_register_handler\fR(3PICLTREE),
  96 \fBptree_unregister_handler\fR(3PICLTREE), \fBattributes\fR(5)