Mercurial > pub > dyncall > dyncall
view doc/manual/manual_dyncallback_api.tex @ 524:1b1abed0ea32
- test/callback_suite_aggrs: small fix, removed missing param with default value
author | Tassilo Philipp |
---|---|
date | Wed, 13 Apr 2022 15:16:56 +0200 |
parents | 17287342e273 |
children | 71c884e610f0 |
line wrap: on
line source
%////////////////////////////////////////////////////////////////////////////// % % 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. % %////////////////////////////////////////////////////////////////////////////// \section{\emph{Dyncallback} C library API} See the dyncallback(3) manpage for more information. %@@@ removed, as manpages are more precise and up to date -------------------> % %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 DCsigchar* signature, % DCCallbackHandler* funcptr, % void* userdata, % DCaggr** aggrs); %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 Table \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} %DCsigchar 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 Table \ref{sigchar}) specifying the %data type used for \capi{result}. %