Mercurial > pub > dyncall > dyncall
diff doc/manual/manual_dyncallback_api.tex @ 0:3e629dc19168
initial from svn dyncall-1745
author | Daniel Adler |
---|---|
date | Thu, 19 Mar 2015 22:24:28 +0100 |
parents | |
children | 1d68b4778979 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/manual/manual_dyncallback_api.tex Thu Mar 19 22:24:28 2015 +0100 @@ -0,0 +1,99 @@ +%////////////////////////////////////////////////////////////////////////////// +% +% Copyright (c) 2007,2013 Daniel Adler <dadler@uni-goettingen.de>, +% Tassilo Philipp <tphilipp@potion-studios.com> +% +% Permission to use, copy, modify, and distribute this software for any +% purpose with or without fee is hereby granted, provided that the above +% copyright notice and this permission notice appear in all copies. +% +% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +% +%////////////////////////////////////////////////////////////////////////////// + +\newpage +\section{\emph{Dyncallback} C library API} + +This library extends \product{dyncall} with function callback support, allowing +the user to dynamically create a callback object that can be called directly, +or passed to functions expecting a function-pointer as argument.\\ +\\ +Invoking a \product{dyncallback} calls into a user-defined unified handler that +permits iteration and thus dynamic handling over the called-back-function's +parameters.\\ +\\ +The flexibility is constrained by the set of supported types, though.\\ +\\ +For style conventions and supported types, see \product{dyncall} API section. +In order to use \product{dyncallback}, include {\tt "dyncall\_callback.h"}. + +\subsection{Callback Object} + +The \emph{Callback Object} is the core component to this library. + +\paragraph{Types} + +\begin{lstlisting}[language=c] +typedef struct DCCallback DCCallback; +\end{lstlisting} + +\paragraph{Details} +The \emph{Callback Object} is an object that mimics a fully typed function +call to another function (a generic callback handler, in this case).\\ +\\ +This means, a pointer to this object is passed to a function accepting a pointer +to a callback function \emph{as the very callback function pointer itself}. +Or, if called directly, cast a pointer to this object to a function pointer and +issue a call. + + +\subsection{Allocation} + +\paragraph{Functions} + +\begin{lstlisting}[language=c] +DCCallback* dcbNewCallback(const char* signature, + DCCallbackHandler* funcptr, + void* userdata); +void dcbFreeCallback(DCCallback* pcb); +\end{lstlisting} + +\lstinline{dcbNewCallback} creates and initializes a new \emph{Callback} object, +where \lstinline{signature} is the needed function signature (format is the +one outlined in the language bindings-section of this manual, see \ref{sigchar}) +of the function to mimic, \lstinline{funcptr} is a pointer to a callback handler, +and \lstinline{userdata} a pointer to custom data that might be useful in the +handler. +Use \lstinline{dcbFreeCallback} to destroy the \emph{Callback} object.\\ +\\ +As with \capi{dcNewCallVM}/\capi{dcFree}, this will allocate memory using the +system allocators or custom overrides. + + +\subsection{Callback handler} + +The unified callback handler's declaration used when creating a \capi{DCCallback} +is: + +\begin{lstlisting} +char cbHandler(DCCallback* cb, + DCArgs* args, + DCValue* result, + void* userdata); +\end{lstlisting} + +\capi{cb} is a pointer to the \capi{DCCallback} object in use, \capi{args} allows +for dynamic iteration over the called-back-function's arguments (input) and +\capi{result} is a pointer to a \capi{DCValue} object in order to store the +callback's return value (output, to be set by handler).\\ +Finally, \capi{userdata} is a pointer to some user defined data that can be +set when creating the callback object. +The handler itself returns a signature character (see \ref{sigchar}) specifying the +data type used for \capi{result}. +