\section{The MOOSApp Superclass - Structure and Methods}
%====================================================================

Nearly all MOOS applications in the MOOS-IvP tree inherit from the
MOOSApp superclass. This class facilitates the construction of a new
application by providing a template of operation for configuration,
reading mail and executing the application's main iterate loop. Here
we describe the basic structure of this class, how to use it to build
your own MOOS App, and useful utility functions defined on the MOOSApp.

%====================================================================
\subsection*{Creating Your Own Application Using MOOSApp}

Creating your own MOOS application based on the MOOSApp superclass is
done by doing something similar to the below example for the
fictitous \app{pFooBar} application.

\vspace{0.1in}
\begin{fileverb}
 #include "MOOS/libMOOS/MOOSLib.h"
 class FooBar : public CMOOSApp
 {
  public:
    FooBar();
    ~FooBar();
 
  protected:
    bool OnNewMail(MOOSMSG_LIST &NewMail);
    bool Iterate();
    bool OnConnectToServer();
    bool OnStartUp();
 };
\end{fileverb}
\vspace{0.1in}

\noindent
Of course the above \var{FooBar.h} file could be made by just creating the 
file and typing it in, but we generally advocate using one of the scripts for
generating a "template" MOOS application:

\vspace{0.1in}
\begin{consoleverb}
$ GenMOOSApp [app-name] [prefix]
\end{consoleverb}
\vspace{0.1in}

\noindent
For example:

\vspace{0.1in}
\begin{consoleverb}
$ GenMOOSApp FooBar p
\end{consoleverb}
\vspace{0.1in}

\noindent
There is also a version for generating an AppCasting MOOS App:

\vspace{0.1in}
\begin{consoleverb}
$ GenMOOSApp_AppCasting FooBar p
\end{consoleverb}
\vspace{0.1in}

\noindent
In the MOOS-IvP code base, most newly created MOOS apps in recent
years are of the AppCasting type. You can read more on AppCasting
here: \urlx{http://oceanai.mit.edu/ivpman/appcasting}. This link also
contains information on how to convert a basic MOOS app later into an
AppCasting MOOS App if you prefer to start with a simpler structure
for now.


%====================================================================
\subsection*{The Primary MOOS App Overloadable Functions}

MOOS apps publish, subscribe for, and handle mail passed from one
application to another through the \app{MOOSDB}.  The key components
are shown in Figure
\ref{fig_moos_functions} below. All MOOS apps begin by being a subclass
of the MOOSApp superclass defined in the Oxford MOOS library (included
with the MOOS-IvP distribution). The primary work of the app developer
is in writing the three functions shown in the figure.

\vspace{0.3in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figs_help/moos_functions.png}
\caption{{\bf The MOOSApp Key Functions:} All MOOS apps are a subclass
  of the MOOSApp superclass. Development mostly boils down to
  overriding the three functions below with the particulars of one's
  own liking.}
\label{fig_moos_functions}
\end{figure}

%====================================================================
\subsection*{MOOSApp Utility Functions}


%====================================================================
\subsection*{The \func{Notify()} function}

This is the primary means for an app to publish mail to the MOOSDB.
There are several versions of this function depending on whether a
string, a double, or binary data is being posted, or if a "auxilliary"
information is included in the posting. Normally a MOOS message will
include automatically the time-stamp and source (the application making
the post). But sometimes it's also useful to include auxilliary source
information. For example, in \app{pHelmIvP} application, if a behavior
is posting to the MOOSDB, the behavior name is contained in the 
auxilliary source.

\vspace{0.08in}
\begin{fileverb}
 bool    Notify(string varname, string value)
\end{fileverb}

\vspace{0.08in}
\begin{fileverb}
 bool    Notify(string varname, double value)
\end{fileverb}

\vspace{0.08in}
\begin{fileverb}
 bool    Notify(string varname, string value, string auxilliary_info)
\end{fileverb}

\vspace{0.08in}
\begin{fileverb}
 bool    Notify(string varname, double value, string auxilliary_info)
\end{fileverb}

\vspace{0.08in}
\begin{fileverb}
 bool    Notify(string varname, vector<unsigned char> binaray_data)
\end{fileverb}

\vspace{0.08in}
\begin{fileverb}
 bool    Notify(string varname, vector<unsigned char> binaray_data, string auxilliary_info)
\end{fileverb}

%====================================================================
\subsection*{The \func{Register()} function}

This is the way an app can register for mail, by naming a MOOS variable it is
interested in. The \var{interval} indicates how often we want to receive mail. 
For example, if an application is posting mail at 20 times per second, but we
are only interested in the latest value say once per second, then an interval
of \var{1.0} may be specified to achieve this. By default the interval is zero
meaning we will receive {\em all} mail for this variable. 

\pskip

\noindent
Registering for the same mail multiple times has no ill effect. However, if you
wish to change the interval for an alread-registered variable, you may need to 
unregister the variable first, and then re-register with the new frequency. An 
app may (unlikely) miss posted mail in the meanwhile. Very rarely, if ever, is
this an issue.

\vspace{0.08in}
\begin{fileverb}
 bool    Register(string varname, double interval=0)
\end{fileverb}

\vspace{0.08in}
\begin{fileverb}
 bool    Register(string varname_pattern, string appname_pattern, double interval=0)
\end{fileverb}

%====================================================================
\subsection*{The \func{UnRegister()} function}

To unregister for mail, this function is used. If a user is no longer
interested in certain mail, the same thing can also be achieved by
simply ignoring mail of this type in the \var{OnNewMail()}. But if
you're concerned about the size of your in-box, you can simply
unregister for the mail using this function.

\vspace{0.08in}
\begin{fileverb}
 bool    UnRegister(string varname)
\end{fileverb}

%====================================================================
\subsection*{The \func{SetAppFreq()} function}

\vspace{0.08in}
\begin{fileverb}
 void    SetAppFreq(double frequency, double max_frequency
\end{fileverb}

%====================================================================
\subsection*{The \func{GetAppFreq()} function}

\vspace{0.08in}
\begin{fileverb}
 double  GetAppFreq()
\end{fileverb}

%====================================================================
\subsection*{The \func{GetAppStartTime()} function}

\vspace{0.08in}
\begin{fileverb}
 double  GetAppStartTime()
\end{fileverb}

%====================================================================
\subsection*{The \func{GetAppName()} function}

\vspace{0.08in}
\begin{fileverb}
 string  GetAppName()
\end{fileverb}

%====================================================================
\subsection*{The \func{GetMissionFileName()} function}

\vspace{0.08in}
\begin{fileverb}
 string  GetMissionFileName()
\end{fileverb}

%====================================================================
\subsection*{The \func{GetCPULoad()} function}

\vspace{0.08in}
\begin{fileverb}
 double  GetCPULoad()
\end{fileverb}

%====================================================================
\subsection*{The \func{getIterateCount()} function}

\vspace{0.08in}
\begin{fileverb}
 int     getIterateCount()
\end{fileverb}

%====================================================================
\subsection*{The \func{GetLastIterateTime()} function}

\vspace{0.08in}
\begin{fileverb}
 double  GetLastIterateTime()
\end{fileverb}

%====================================================================
\subsection*{The \func{GetTimeSinceIterate()} function}

\vspace{0.08in}
\begin{fileverb}
 double  GetTimeSinceIterate()
\end{fileverb}


%====================================================================
\subsection*{The \func{MOOSTime()} function}

\vspace{0.08in}
\begin{fileverb}
 double  MOOSTime()
\end{fileverb}

%====================================================================
\subsection*{The \func{GetMOOSTimeWarp()} function}

\vspace{0.08in}
\begin{fileverb}
 double GetMOOSTimeWarp()
\end{fileverb}