|
0
|
1 .\" Copyright (c) 2007-2014 Daniel Adler <dadler AT uni-goettingen DOT de>,
|
|
|
2 .\" Tassilo Philipp <tphilipp AT potion-studios DOT com>
|
|
|
3 .\"
|
|
|
4 .\" Permission to use, copy, modify, and distribute this software for any
|
|
|
5 .\" purpose with or without fee is hereby granted, provided that the above
|
|
|
6 .\" copyright notice and this permission notice appear in all copies.
|
|
|
7 .\"
|
|
|
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
|
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
|
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
|
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
|
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
|
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
|
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
|
15 .\"
|
|
|
16 .Dd $Mdocdate$
|
|
|
17 .Dt dyncallback 3
|
|
|
18 .Os
|
|
|
19 .Sh NAME
|
|
|
20 .Nm dyncallback
|
|
|
21 .Nd callback interface of dyncall
|
|
|
22 .Sh SYNOPSIS
|
|
|
23 .In dyncall_callback.h
|
|
|
24 .Ft DCCallback *
|
|
|
25 .Fn dcbNewCallback "const char * signature" "DCCallbackHandler * funcptr" "void * userdata"
|
|
|
26 .Ft void
|
|
|
27 .Fn dcbInitCallback "DCCallback * pcb" "const char * signature" "DCCallbackHandler * funcptr" "void * userdata"
|
|
|
28 .Ft void
|
|
|
29 .Fn dcbFreeCallback "DCCallback * pcb"
|
|
|
30 .Ft void
|
|
|
31 .Fn dcbGetUserData "DCCallback * pcb"
|
|
|
32 .Sh DESCRIPTION
|
|
|
33 The
|
|
|
34 .Nm
|
|
|
35 dyncall library has an interface to create callback objects, that can be passed
|
|
|
36 to functions as callback arguments. In other words, a pointer to the callback
|
|
|
37 object can be "called", directly. The callback handler then allows iterating
|
|
|
38 dynamically over the arguments once called back.
|
|
|
39 .Pp
|
|
|
40 .Fn dcbNewCallback
|
|
|
41 creates a new callback object, where
|
|
|
42 .Ar signature
|
|
|
43 is a signature string describing the function to be called back (see manual for
|
|
|
44 format). This is needed for
|
|
|
45 .Nm
|
|
|
46 dyncallback to correctly prepare the arguments passed in by the function that
|
|
|
47 calls the callback handler. Note that the handler doesn't return the value
|
|
|
48 specified in the signature, directly, but simply 'i' or 'f' depending on whether
|
|
|
49 it is a integral or floating point type. The return value itself is stored
|
|
|
50 where the handler's 3rd parameter points to (see example).
|
|
|
51 .Ar funcptr
|
|
|
52 is a pointer to the
|
|
|
53 .Nm
|
|
|
54 dyncallback callback handler (see below), and
|
|
|
55 .Ar userdata
|
|
|
56 a pointer to arbitrary user data you want to use in the callback handler.
|
|
|
57 Use the returned pointer as callback argument in functions requiring a callback
|
|
|
58 function pointer.
|
|
|
59 .Pp
|
|
|
60 .Fn dcbInitCallback
|
|
|
61 (re)initialize the callback object.
|
|
|
62 .Pp
|
|
|
63 .Fn dcbFreeCallback
|
|
|
64 destroys and frees the callback handler.
|
|
|
65 .Pp
|
|
|
66 .Fn dcbGetUserData
|
|
|
67 returns a pointer to the userdata passed to the callback object on creation or
|
|
|
68 initialization.
|
|
|
69 .Pp
|
|
|
70 Declaration of a dyncallback handler (following function pointer definition in
|
|
|
71 dyncallback/dyncall_callback.h):
|
|
|
72 .Bd -literal -offset indent
|
|
|
73 char cbHandler(DCCallback* cb,
|
|
|
74 DCArgs* args,
|
|
|
75 DCValue* result,
|
|
|
76 void* userdata);
|
|
|
77 .Ed
|
|
|
78 .Pp
|
|
|
79 .Ar cb is a pointer to the DCCallback object in use
|
|
|
80 .Nm
|
|
|
81 result is a pointer to a DCValue object in order to store the callback's
|
|
|
82 return value (output, to be set by handler). Finally,
|
|
|
83 .Ar userdata is a pointer to some user defined data that can be
|
|
|
84 set when creating the callback object.
|
|
|
85 The handler itself returns a signature character (see manual for format)
|
|
|
86 specifying the data type used for
|
|
|
87 .Ar result .
|
|
|
88 .Sh EXAMPLE
|
|
|
89 Let's say, we want to create a callback object and call it. For simplicity, this
|
|
|
90 example will omit passing it as a function pointer to a function (e.g. compar
|
|
|
91 in qsort(), etc.) and demonstrate calling it, directly. First, we need to define
|
|
|
92 our callback handler - the following handler illustrates how to access the passed-
|
|
|
93 in arguments:
|
|
|
94 .Bd -literal -offset indent
|
|
|
95 char cbHandler(DCCallback* cb,
|
|
|
96 DCArgs* args,
|
|
|
97 DCValue* result,
|
|
|
98 void* userdata)
|
|
|
99 {
|
|
|
100 int* ud = (int*)userdata;
|
|
|
101 int arg1 = dcbArgInt (args);
|
|
|
102 float arg2 = dcbArgFloat (args);
|
|
|
103 short arg3 = dcbArgShort (args);
|
|
|
104 double arg4 = dcbArgDouble (args);
|
|
|
105 long long arg5 = dcbArgLongLong(args);
|
|
|
106
|
|
|
107 // .. do something ..
|
|
|
108
|
|
|
109 result->s = 1244;
|
|
|
110 return 'i';
|
|
|
111 }
|
|
|
112 .Ed
|
|
|
113 .Pp
|
|
|
114 Note that the return value of the handler is a signature character, not the
|
|
|
115 actual return value, itself, and note that the actual return value is of type
|
|
|
116 short.
|
|
|
117 Now, let's call it through a DCCallback object:
|
|
|
118 .Bd -literal -offset indent
|
|
|
119 DCCallback* cb;
|
|
|
120 short result = 0;
|
|
|
121 int userdata = 1337;
|
|
|
122 cb = dcbNewCallback("ifsdl)s", &cbHandler, &userdata);
|
|
|
123 result = ((short(*)(int, float, short, double, long long))cb)
|
|
|
124 (123, 23.f, 3, 1.82, 9909ll);
|
|
|
125 dcbFreeCallback(cb);
|
|
|
126 .Ed
|
|
|
127 .Sh SEE ALSO
|
|
|
128 .Xr dyncall 3 ,
|
|
|
129 .Xr dynload 3
|
|
|
130 and the dyncall manual (available in PDF format) for a way more detailed documentation of this
|
|
|
131 library.
|
|
|
132 .Sh AUTHORS
|
|
|
133 .An "Daniel Adler" Aq dadler@uni-goettingen.de
|
|
|
134 .An "Tassilo Philipp" Aq tphilipp@potion-studios.com
|
