xorpdev_101.tex

xorp源码hg

     */
    bool send_lookup_route_by_dest4(
        const char*     dst_xrl_target_name,
        const IPv4&     addr,
        const bool&     unicast,
        const bool&     multicast,
        const LookupRouteByDest4CB&   cb
    );
}
\end{lstlisting}

\newpage

\begin{lstlisting}[caption={Extracts from {\stt xorp/static\_routes/xrl\_static\_routes\_node.cc} %
                                     \label{lst:sr.send} } ]{}
void
XrlStaticRoutesNode::send_rib_route_change()
{
    bool success = true;
...
    StaticRoute& static_route = _inform_rib_queue.front();
...
    //
    // Send the appropriate XRL
    //
    if (static_route.is_add_route()) {
        if (static_route.is_ipv4()) {
            if (static_route.is_interface_route()) {
...
            } else {
		success = _xrl_rib_client.send_add_route4(
		    _rib_target.c_str(),
		    StaticRoutesNode::protocol_name(),
		    static_route.unicast(),
		    static_route.multicast(),
		    static_route.network().get_ipv4net(),
		    static_route.nexthop().get_ipv4(),
		    static_route.metric(),
		    static_route.policytags().xrl_atomlist(),
		    callback(this, &XrlStaticRoutesNode::send_rib_route_change_cb));
                if (success)
                    return;
            }
        }
...
}

void
XrlStaticRoutesNode::send_rib_route_change_cb(const XrlError& xrl_error)
{
    switch (xrl_error.error_code()) {
    case OKAY:
	//
	// If success, then send the next route change
	//
	_inform_rib_queue.pop_front();
	send_rib_route_change();
	break;

    case COMMAND_FAILED:
	//
	// If a command failed because the other side rejected it,
	// then print an error and send the next one.
	//
	...
	break;

    case NO_FINDER:
    case RESOLVE_FAILED:
    case SEND_FAILED:
	...
	break;

    case BAD_ARGS:
    case NO_SUCH_METHOD:
    case INTERNAL_ERROR:
	...
	break;

    case REPLY_TIMED_OUT:
    case SEND_FAILED_TRANSIENT:
	...
	break;
    }
}


\end{lstlisting}

\newpage

\noindent We actually create the callback using the call:\\
{\stt callback(this, \&XrlStaticRoutesNode::send\_rib\_route\_change\_cb)}\\
In the context of 
Listing \ref{lst:sr.send}, {\stt this} refers to a pointer to the
current instance of {\stt XrlStaticRoutesNode}.  So, what this
callback does is to wrap a pointer to the method {\stt
send\_rib\_route\_change\_cb()} on the current instance of {\stt
XrlStaticRoutesNode}.  Later on, when the response returns, the
XrlRouter will call the {\stt send\_rib\_route\_change\_cb()} method on
this specific instance of {\stt XrlStaticRoutesNode} and supply it
with a parameter of type {\stt const XrlError\&}.

In the implementation of {\stt send\_rib\_route\_change\_cb()} we can see
that we check the value of the {\stt xrl\_error} parameter to see
whether the XRL call was actually successful or not.
If the return error code is {\stt OKAY} we send the next route change.
Otherwise, we take different actions based on the error type.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Returning values in XRLs}

Because the \SRI process is so simple, none of the XRLs it calls
actually return any information in the response.  However, it's rather
common that we want to make a request of a target and get back some
information.  This is quite easy to do, but just requires a different
callback that can receive the relevant parameters.

In Listing \ref{lst:rib.xif} we saw that the XRL
{\stt lookup\_route\_by\_dest4}
returns one value of type {\stt ipv4} called {\stt nexthop}.  XRLs can
actually return multiple parameters - this is merely a simple
example.

In Listing \ref{lst:ribxif.hh} we can see that the callback we need to
suuply to {\stt send\_lookup\_route\_by\_dest4()} is of type:\\ {\stt
XorpCallback2<void, const XrlError\&, const IPv4*>::RefPtr}\\ This is
just like the callback we have already seen, except that the method
the callback will call must take two arguments.  The first must be of
type {\stt const XrlError\&} and the second must be of type {\stt
const IPv4*}.  Although \SRI has no such callback method, if it did it
might look like the function {\stt lookup\_route\_by\_dest4\_cb} in
Listing \ref{lst:lookup}.  The callback itself to be passed into {\stt
send\_lookup\_route\_by\_dest4()} is created in exactly the same way as
the one we passed into {\stt send\_add\_route4()}.

\begin{lstlisting}[caption={Hypothetical callback for  {\stt
	send\_lookup\_route\_by\_dest4()} \label{lst:lookup} }]{} %
void
XrlStaticRoutesNode::lookup_route_by_dest4_cb(const XrlError& xrl_error,
                                              const IPv4* nexthop)
{
    if (xrl_error == XrlError::OKAY()) {
        printf("the nexthop is %s\n", nexthop->str().c_str());
    }
...
}
\end{lstlisting}

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The XLOG Logging Facility}
\label{xlog}

The XORP XLOG facility is used for log messages generation, similar to
syslog. The log messages may be output to multiple output streams
simultaneously. Below is a description of how to use the log utility.

\begin{itemize}

  \item The xlog utility assumes that \verb=XORP_MODULE_NAME= is defined
  (per module). To do so, you must have in your directory a file like
  ``foo\_module.h'', and inside it should contain something like:

\begin{verbatim}
#define XORP_MODULE_NAME "BGP"
\end{verbatim}

  This file then has to be included by each *.c and *.cc file,
  and MUST be the first of the included local files.

  \item Before using the xlog utility, a program MUST initialize it
  first (think of this as the xlog constructor):

\begin{verbatim}
int xlog_init(const char *process_name, const char *preamble_message);
\end{verbatim}

  Further, if a program tries to use xlog without initializing it
  first, the program will exit.

  \item To add output streams, you MUST use one of the following (or both):

\begin{verbatim}
int xlog_add_output(FILE* fp);
int xlog_add_default_output(void);
\end{verbatim}

  \item To change the verbosity of all xlog messages, use:

\begin{verbatim}
xlog_set_verbose(xlog_verbose_t verbose_level);
\end{verbatim}

  where ``verbose\_level'' is one of the following (\verb=XLOG_VERBOSE_MAX=
  excluded):

\begin{verbatim}
typedef enum {
    XLOG_VERBOSE_LOW = 0,       /* 0 */
    XLOG_VERBOSE_MEDIUM,        /* 1 */
    XLOG_VERBOSE_HIGH,          /* 2 */
    XLOG_VERBOSE_MAX
} xlog_verbose_t;
\end{verbatim}

  Default value is \verb=XLOG_VERBOSE_LOW= (least details).
  Larger value for ``verbose\_level'' adds more details to the
  preamble message (e.g., file name, line number, etc, about the place
  where the log message was initiated).

  Note that the verbosity level of message type \verb=XLOG_LEVEL_FATAL= (see
  below) cannot be changed and is always set to the most verbose level
  (\verb=XLOG_VERBOSE_HIGH=).

  \item To change the verbosity of a particular message type, use:

\begin{verbatim}
void xlog_level_set_verbose(xlog_level_t log_level,
	xlog_verbose_t verbose_level);
\end{verbatim}

  where ``log\_level'' is one of the following (\verb=XLOG_LEVEL_MIN=
  and \verb=XLOG_LEVEL_MAX= excluded):

\begin{verbatim}
typedef enum {
    XLOG_LEVEL_MIN = 0,         /* 0 */
    XLOG_LEVEL_FATAL = 0,       /* 0 */
    XLOG_LEVEL_ERROR,           /* 1 */
    XLOG_LEVEL_WARNING,         /* 2 */
    XLOG_LEVEL_INFO,            /* 3 */
    XLOG_LEVEL_TRACE,           /* 4 */
    XLOG_LEVEL_MAX
} xlog_level_t;
\end{verbatim}

  Note that the verbosity level of message type \verb=XLOG_LEVEL_FATAL=
  cannot be changed and is always set to the most verbose level
  (\verb=XLOG_VERBOSE_HIGH=).

  \item To start the xlog utility, you MUST use:

\begin{verbatim}
int xlog_start(void);
\end{verbatim}

  \item To enable or disable a particular message type, use:

\begin{verbatim}
int xlog_enable(xlog_level_t log_level);
int xlog_disable(xlog_level_t log_level);
\end{verbatim}

  By default, all levels are enabled.
  Note that \verb=XLOG_LEVEL_FATAL= cannot be disabled.

  \item To stop the logging, use:

\begin{verbatim}
int xlog_stop(void);
\end{verbatim}

  Later you can restart it again by \verb=xlog_start()=

  \item To gracefully exit the xlog utility, use

\begin{verbatim}
int     xlog_exit(void);
\end{verbatim}

  (think of this as the xlog destructor).

\end{itemize}

Listing \ref{lst:xlog.main} contains an example of using the XLOG facility.

\begin{lstlisting}[caption={An example of using the XLOG facility %
                                     \label{lst:xlog.main} } ]{}
int
main(int argc, char *argv[])
{
    //
    // Initialize and start xlog
    //
    xlog_init(argv[0], NULL);
    xlog_set_verbose(XLOG_VERBOSE_LOW);	// Least verbose messages
    // Increase verbosity of the error messages
    xlog_level_set_verbose(XLOG_LEVEL_ERROR, XLOG_VERBOSE_HIGH);
    xlog_add_default_output();
    xlog_start();

    // Do something

    //
    // Gracefully stop and exit xlog
    //
    xlog_stop();
    xlog_exit();

    exit (0);
}
\end{lstlisting}

Typically, a developer would use the macros described below
to print a message, add an assert statement, place a marker, etc.
If a macro accepts a message to print, the format of the message is same
as printf(3). The only difference is that the xlog utility automatically
adds \verb='\n'=, (i.e. end-of-line) at the end of each string
specified by \verb=format=:

\begin{itemize}

  \item \verb=XLOG_FATAL(const char *format, ...)=
  \newline
  Write a FATAL message to the xlog output streams and abort the program.

  \item \verb=XLOG_ERROR(const char *format, ...)=
  \newline
  Write an ERROR message to the xlog output streams.

  \item \verb=XLOG_WARNING(const char *format, ...)=
  \newline
  Write a WARNING message to the xlog output streams.

  \item \verb=XLOG_INFO(const char *format, ...)=
  \newline
  Write an INFO message to the xlog output streams.

  \item \verb=XLOG_TRACE(int cond_boolean, const char *format, ...)=
  \newline
  Write a TRACE message to the xlog output stream, but only
  if \verb=cond_boolean= is not 0.

  \item \verb=XLOG_ASSERT(assertion)=
  \newline
  The XORP replacement for assert(3), except that it cannot be
  conditionally disabled and logs error messages through the standard
  xlog mechanism. It calls \verb=XLOG_FATAL()= if the assertion fails.

  \item \verb=XLOG_UNREACHABLE()=
  \newline
  A marker that can be used to indicate code that should never be executed.

  \item \verb=XLOG_UNFINISHED()=
  \newline
  A marker that can be used to indicate code that is not yet implemented
  and hence should not be run.

\end{itemize}

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The {\it rtrmgr} Template Files}
\label{rtrmgr_templates}

TODO: add description how to write rtrmgr template files.

For the time being, the developer can check the ``XORP Router Manager Process
(rtrmgr)'' document for information about the template semantics, and can use
file {\stt xorp/etc/templates/static\_routes.tp} as an example.

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%     APPENDIX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\appendix
\section{Modification History}

\begin{itemize}

  \item July 19, 2004: Initial version 1.0 completed.

  \item April 13, 2005: Updated to match XORP release 1.1.
   Added the XLOG logging facility section.

  \item March 8, 2006: Updated the version to 1.2, and the date.

  \item August 2, 2006: Updated to match XORP release 1.3: the XRL-related
  sample code is modified to match the original code.

  \item March 20, 2007: Updated the version to 1.4, and the date.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%     BIBLIOGRAPHY
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\bibliography{../tex/xorp}
\bibliographystyle{plain}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}