\rhead{\bf MC\_AddAgentInitCallback()}
\noindent
\vspace{5pt}
\rule{6.5in}{0.015in}
\noindent
\phantomsection
{\LARGE \bf MC\_AddAgentInitCallback()\index{MC\_AddAgentInitCallback()}}\\
\addcontentsline{toc}{section}{MC\_AddAgentInitCallback()}
\label{api:MC_AddAgentInitCallback()}

\noindent
{\bf Synopsis}\\
{\bf \#include $<$libmc.h$>$}\\
{\bf int MC\_AddAgentInitCallback}({\bf MCAgency\_t} $agency$, {\bf MC\_AgentInitCallbackFunc\_t} $function$, {\bf void*} user\_data);\\

\noindent
{\bf Purpose}\\
Register a callback function executed during agent initialization.\\

\noindent
{\bf Return Value}\\
The function returns 0 on success and non-zero otherwise.\\

\noindent
{\bf Parameters}
\vspace{-0.1in}
\begin{description}
\item
\begin{tabular}{p{20 mm}p{145 mm}} 
\texttt{agency} & An initialized agency handle to add an agent to.\\
\texttt{function} & The callback function. \\
\texttt{user\_data} & User data to be passed to the callback function
\end{tabular}
\end{description}

\noindent
{\bf Description}\\
This function adds a agent initialization callback function to an already running agency.
The callback function is called after the Ch interpreter for an agent is fully initialized,
but before the agent is executed with the interpreter. The callback function may modify
the Ch intepreter and/or the incoming agent before they are executed. The callback
function will be called once for every incoming agent. The callback
function should have a prototype of the form

\begin{verbatim}
int function(ChInterp_t interp, MCAgent_t agent, void* user_data);
\end{verbatim}

The callback function should return zero to indicate that everything succeeded and that the 
agent execution process should continue normally. If the callback function returns a 
non-zero value, the agent will be forced into a neutral "persistent" state, and will
not be executed. The agent will remain neutral in the agency until either the agency terminates
or further actions are taken to purge the agent.

\noindent
{\bf Example}\\
\noindent
{\footnotesize\verbatiminput{../demos/cspace-agentspace_interface/agent_init_callback/server.c}}

\noindent
{\bf See Also}\\

%\CPlot::\DataThreeD(), \CPlot::\DataFile(), \CPlot::\Plotting(), \plotxy().\\
