%//////////////////////////////////////////////////////////////////////////////
%
% Copyright (c) 2007,2010-2022 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.
%
%//////////////////////////////////////////////////////////////////////////////

\clearpage
\section{\emph{Dyncall} C library API}

See the dyncall(3) manpage for more information.

%@@@ removed, as manpages are more precise and up to date ------------------->

%The library provides low-level functionality to make foreign function calls
%from different run-time environments. The flexibility is constrained by the
%set of supported types.
%
%\paragraph{C interface style conventions}
%
%This manual and the \product{dyncall} library's C interface {\tt "dyncall.h"}
%use the following C source code style.
%
%
%\begin{table}[h]
%\begin{center}
%\begin{tabular*}{0.8\textwidth}{llll}
%Subject    & C symbol & Details & Example \\
%\hline  
%Types      & {\tt DC\group{type name}}      & lower-case & \capi{DCint}, \capi{DCfloat}, \capi{DClong}, \ldots\\
%Structures & {\tt DC\group{structure name}} & camel-case & \capi{DCCallVM}\\
%Functions  & {\tt dc\group{function name}}  & camel-case & \capi{dcNewCallVM}, \capi{dcArgInt}, \ldots\\
%           & {\tt dcb\group{function name}} &            & \capi{dcbNewCallback}, \ldots\\
%           & {\tt dl\group{function name}}  &            & \capi{dlLoadLibrary}, \ldots\\
%\end{tabular*}
%\caption{C interface conventions}
%\label{sourcecode}
%\end{center}
%\end{table}
%
%\subsection{Supported C/C++ argument and return types}
%
%\begin{table}[h]
%\begin{center}
%\begin{tabular*}{0.75\textwidth}{ll}
%Type alias & C/C++ data type\\
%\hline
%DCbool     & \_Bool, bool\\
%DCchar     & char, unsigned char\\
%DCshort    & short, unsigned short\\
%DCint      & int, unsigned char\\
%DClong     & long, unsigned char\\
%DClonglong & long long, unsigned char\\
%DCfloat    & float\\
%DCdouble   & double\\
%DCpointer  & void*\\
%DCvoid     & void\\
%\em{...}   & \em{aggregates (struct, union)}
%\end{tabular*}
%\caption{Supported C/C++ argument and return types}
%\label{types}
%\end{center}
%\end{table}
%
%\pagebreak
%
%\subsection{Call Virtual Machine - CallVM}
%
%This \emph{CallVM} is the main entry to the functionality of the library.
%
%\paragraph{Types}
%
%\begin{lstlisting}[language=c]
%typedef void DCCallVM; /* abstract handle */
%\end{lstlisting}
%
%\paragraph{Details}
%The \emph{CallVM} is a state machine that manages all aspects of a function 
%call from configuration, argument passing up the actual function call on
%the processor.
%
%\subsection{Allocation}
%
%\paragraph{Functions}
%
%\begin{lstlisting}[language=c]
%DCCallVM* dcNewCallVM (DCsize size);
%void      dcFree(DCCallVM* vm);
%\end{lstlisting}
%
%\lstinline{dcNewCallVM} creates a new \emph{CallVM} object, where
%\lstinline{size} specifies the max size of the internal stack that will be
%allocated and used to bind arguments to. Use \lstinline{dcFree} to
%destroy the \emph{CallVM} object.\\
%\\
%This will allocate memory using the system allocators or custom ones provided
%custom \capi{dcAllocMem} and \capi{dcFreeMem} macros are defined to override the
%default behaviour. See \capi{dyncall\_alloc.h} for defails.
%
%
%\subsection{Error Reporting}
%
%\paragraph{Function}
%
%\begin{lstlisting}[language=c]
%DCint dcGetError(DCCallVM* vm);
%\end{lstlisting}
%
%Returns the most recent error state code out of the following:
%
%\paragraph{Errors}
%
%\begin{table}[h]
%\begin{center}
%\begin{tabular*}{0.95\textwidth}{ll}
%Constant & Description\\
%\hline
%\lstinline@DC_ERROR_NONE@             & No error occured. \\
%\lstinline@DC_ERROR_UNSUPPORTED_MODE@ & Unsupported mode, caused by \lstinline@dcMode()@ \\
%\end{tabular*}
%\caption{CallVM calling convention modes}
%\label{errorcodes}
%\end{center}
%\end{table}
%
%\pagebreak
%
%\subsection{Configuration}
%
%\paragraph{Function}
%
%\begin{lstlisting}[language=c]
%void dcMode (DCCallVM* vm, DCint mode);
%\end{lstlisting}
%
%Sets the calling convention to use. See dyncall.h for a list of available
%modes. Note that some mode/platform combination don't make any sense (e.g.
%using a PowerPC calling convention on a MIPS platform) and are silently
%ignored.
%
%
%\subsection{Machine state reset}
%
%\begin{lstlisting}[language=c]
%void dcReset(DCCallVM* vm);
%\end{lstlisting}
%
%Resets the internal stack of arguments and prepares it for a new call. This
%function should be called after setting the initial/main call mode (using
%dcMode()), but prior to binding arguments to the CallVM (sometimes dcMode()
%calls are needed after pushing some args, e.g.  DC\_SIGCHAR\_CC\_ELLIPSIS\_VARARGS,
%which is used prior to binding varargs of variadic functions). Use it also when
%reusing a CallVM, as arguments don't get flushed automatically after a function
%call invocation.\\
%Note: you should also call this function after initial creation of the a CallVM
%object, as dcNewCallVM doesn't do this, implicitly.
%
%
%\subsection{Argument binding}
%
%\paragraph{Functions}
%
%\begin{lstlisting}[language=c]
%void dcArgBool    (DCCallVM*, DCbool);
%void dcArgChar    (DCCallVM*, DCchar);
%void dcArgShort   (DCCallVM*, DCshort);
%void dcArgInt     (DCCallVM*, DCint);
%void dcArgLong    (DCCallVM*, DClong);
%void dcArgLongLong(DCCallVM*, DClonglong);
%void dcArgFloat   (DCCallVM*, DCfloat);
%void dcArgDouble  (DCCallVM*, DCdouble);
%void dcArgPointer (DCCallVM*, DCpointer);
%void dcArgAggr    (DCCallVM*, const DCaggr*, const void*);
%\end{lstlisting}
%
%\paragraph{Details}
%
%Used to bind arguments of the named types to the CallVM object.
%Arguments should be bound in \emph{left-to-right} order regarding the C
%function prototype.\\
%\\
%See the dyncall(3) manpage for more information.
%
%
%\subsection{Call invocation}
%
%\paragraph{Functions}
%
%\begin{lstlisting}[language=c]
%DCvoid     dcCallVoid    (DCCallVM*, DCpointer);
%DCbool     dcCallBool    (DCCallVM*, DCpointer);
%DCchar     dcCallChar    (DCCallVM*, DCpointer);
%DCshort    dcCallShort   (DCCallVM*, DCpointer);
%DCint      dcCallInt     (DCCallVM*, DCpointer);
%DClong     dcCallLong    (DCCallVM*, DCpointer);
%DClonglong dcCallLongLong(DCCallVM*, DCpointer);
%DCfloat    dcCallFloat   (DCCallVM*, DCpointer);
%DCdouble   dcCallDouble  (DCCallVM*, DCpointer);
%DCpointer  dcCallPointer (DCCallVM*, DCpointer);
%DCpointer  dcCallAggr(DCCallVM*, DCpointer, const DCaggr*, DCpointer);
%void       dcBeginCallAggr(DCCallVM*, const DCaggr*);
%\end{lstlisting}
%
%\paragraph{Details}
%Calls the function specified by \emph{funcptr} with the arguments bound to
%the \emph{CallVM} and returns. Use the function that corresponds to the
%dynamically called function's return value.\\
%\\
%After the invocation of the foreign function call, the argument values are
%still bound and a second call using the same arguments can be issued. If you
%need to clear the argument bindings, you have to reset the \emph{CallVM}.\\
%\\
%See the dyncall(3) manpage for more information.
%
%\subsection{Formatted argument binding and calls (ANSI C ellipsis interface)}
%
%\paragraph{Functions}
%
%\begin{lstlisting}[language=c]
%void dcArgF  (DCCallVM*, const DCsigchar*, ...);
%void dcVArgF (DCCallVM*, const DCsigchar*, va_list);
%void dcCallF (DCCallVM*, DCValue*, DCpointer, const DCsigchar*, ...);
%void dcVCallF(DCCallVM*, DCValue*, DCpointer, const DCsigchar*, va_list);
%\end{lstlisting}
%
%\paragraph{Details}
%
%These functions can be used to operate \product{dyncall} via a printf-style
%functional interface, using a signature string encoding the argument types and 
%return type (and optionally also the calling convention used).
%\capi{dcArgF()} and \capi{dcVArgF()} just bind arguments to the \capi{DCCallVM}
%object, so any return value specified in the signature is ignored. \capi{dcCallF()}
%and \capi{dcVCallF()} also take a function pointer to call after binding the arguments.
%The return value will be stored in what \lstinline{result} points to.
%For more information about the signature format, refer to \ref{sigchar}.
%