|
467
|
1 %//////////////////////////////////////////////////////////////////////////////
|
|
|
2 %
|
|
|
3 % Copyright (c) 2007,2013 Daniel Adler <dadler@uni-goettingen.de>,
|
|
|
4 % Tassilo Philipp <tphilipp@potion-studios.com>
|
|
|
5 %
|
|
|
6 % Permission to use, copy, modify, and distribute this software for any
|
|
|
7 % purpose with or without fee is hereby granted, provided that the above
|
|
|
8 % copyright notice and this permission notice appear in all copies.
|
|
|
9 %
|
|
|
10 % THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
|
11 % WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
|
12 % MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
|
13 % ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
|
14 % WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
|
15 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
|
16 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
|
17 %
|
|
|
18 %//////////////////////////////////////////////////////////////////////////////
|
|
|
19
|
|
|
20 \clearpage
|
|
|
21 \section{\emph{Dyncallback} C library API}
|
|
|
22
|
|
|
23 This library extends \product{dyncall} with function callback support, allowing
|
|
|
24 the user to dynamically create a callback object that can be called directly,
|
|
|
25 or passed to functions expecting a function-pointer as argument.\\
|
|
|
26 \\
|
|
|
27 Invoking a \product{dyncallback} calls into a user-defined unified handler that
|
|
|
28 permits iteration and thus dynamic handling over the called-back-function's
|
|
|
29 parameters.\\
|
|
|
30 \\
|
|
|
31 The flexibility is constrained by the set of supported types, though.\\
|
|
|
32 \\
|
|
|
33 For style conventions and supported types, see \product{dyncall} API section.
|
|
|
34 In order to use \product{dyncallback}, include {\tt "dyncall\_callback.h"}.
|
|
|
35
|
|
|
36 \subsection{Callback Object}
|
|
|
37
|
|
|
38 The \emph{Callback Object} is the core component to this library.
|
|
|
39
|
|
|
40 \paragraph{Types}
|
|
|
41
|
|
|
42 \begin{lstlisting}[language=c]
|
|
|
43 typedef struct DCCallback DCCallback;
|
|
|
44 \end{lstlisting}
|
|
|
45
|
|
|
46 \paragraph{Details}
|
|
|
47 The \emph{Callback Object} is an object that mimics a fully typed function
|
|
|
48 call to another function (a generic callback handler, in this case).\\
|
|
|
49 \\
|
|
|
50 This means, a pointer to this object is passed to a function accepting a pointer
|
|
|
51 to a callback function \emph{as the very callback function pointer itself}.
|
|
|
52 Or, if called directly, cast a pointer to this object to a function pointer and
|
|
|
53 issue a call.
|
|
|
54
|
|
|
55
|
|
|
56 \subsection{Allocation}
|
|
|
57
|
|
|
58 \paragraph{Functions}
|
|
|
59
|
|
|
60 \begin{lstlisting}[language=c]
|
|
|
61 DCCallback* dcbNewCallback(const char* signature,
|
|
|
62 DCCallbackHandler* funcptr,
|
|
|
63 void* userdata,
|
|
|
64 DCaggr** aggrs);
|
|
|
65 void dcbFreeCallback(DCCallback* pcb);
|
|
|
66 \end{lstlisting}
|
|
|
67
|
|
|
68 \lstinline{dcbNewCallback} creates and initializes a new \emph{Callback} object,
|
|
|
69 where \lstinline{signature} is the needed function signature (format is the
|
|
|
70 one outlined in the language bindings-section of this manual, see Table \ref{sigchar})
|
|
|
71 of the function to mimic, \lstinline{funcptr} is a pointer to a callback handler,
|
|
|
72 and \lstinline{userdata} a pointer to custom data that might be useful in the
|
|
|
73 handler.
|
|
|
74 Use \lstinline{dcbFreeCallback} to destroy the \emph{Callback} object.\\
|
|
|
75 \\
|
|
|
76 As with \capi{dcNewCallVM}/\capi{dcFree}, this will allocate memory using the
|
|
|
77 system allocators or custom overrides.
|
|
|
78
|
|
|
79
|
|
|
80 \subsection{Callback handler}
|
|
|
81
|
|
|
82 The unified callback handler's declaration used when creating a \capi{DCCallback}
|
|
|
83 is:
|
|
|
84
|
|
|
85 \begin{lstlisting}
|
|
|
86 char cbHandler(DCCallback* cb,
|
|
|
87 DCArgs* args,
|
|
|
88 DCValue* result,
|
|
|
89 void* userdata);
|
|
|
90 \end{lstlisting}
|
|
|
91
|
|
|
92 \capi{cb} is a pointer to the \capi{DCCallback} object in use, \capi{args} allows
|
|
|
93 for dynamic iteration over the called-back-function's arguments (input) and
|
|
|
94 \capi{result} is a pointer to a \capi{DCValue} object in order to store the
|
|
|
95 callback's return value (output, to be set by handler).\\
|
|
|
96 Finally, \capi{userdata} is a pointer to some user defined data that can be
|
|
|
97 set when creating the callback object.
|
|
|
98 The handler itself returns a signature character (see Table \ref{sigchar}) specifying the
|
|
|
99 data type used for \capi{result}.
|
|
|
100
|
