Mercurial > pub > dyncall > dyncall

comparison doc/manual/manual_dyncallback_api.tex @ 0:3e629dc19168

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial from svn dyncall-1745
author Daniel Adler
date Thu, 19 Mar 2015 22:24:28 +0100
parents
children 1d68b4778979
comparison
equal deleted inserted replaced
-1:000000000000 0:3e629dc19168
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 \newpage
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 void dcbFreeCallback(DCCallback* pcb);
65 \end{lstlisting}
66
67 \lstinline{dcbNewCallback} creates and initializes a new \emph{Callback} object,
68 where \lstinline{signature} is the needed function signature (format is the
69 one outlined in the language bindings-section of this manual, see \ref{sigchar})
70 of the function to mimic, \lstinline{funcptr} is a pointer to a callback handler,
71 and \lstinline{userdata} a pointer to custom data that might be useful in the
72 handler.
73 Use \lstinline{dcbFreeCallback} to destroy the \emph{Callback} object.\\
74 \\
75 As with \capi{dcNewCallVM}/\capi{dcFree}, this will allocate memory using the
76 system allocators or custom overrides.
77
78
79 \subsection{Callback handler}
80
81 The unified callback handler's declaration used when creating a \capi{DCCallback}
82 is:
83
84 \begin{lstlisting}
85 char cbHandler(DCCallback* cb,
86 DCArgs* args,
87 DCValue* result,
88 void* userdata);
89 \end{lstlisting}
90
91 \capi{cb} is a pointer to the \capi{DCCallback} object in use, \capi{args} allows
92 for dynamic iteration over the called-back-function's arguments (input) and
93 \capi{result} is a pointer to a \capi{DCValue} object in order to store the
94 callback's return value (output, to be set by handler).\\
95 Finally, \capi{userdata} is a pointer to some user defined data that can be
96 set when creating the callback object.
97 The handler itself returns a signature character (see \ref{sigchar}) specifying the
98 data type used for \capi{result}.
99