\chapter{Using the stub-generator: an example}\label{chap:stubgen-example}

\index{stub-generator} 

\section{Introduction}

In this chapter we'll redo the Caesar-Cypher example of

chapter~\ref{chap:h-in-example}, now using the stub-generator. You will see

that it saves quite a bit of work. Also, as the emphasis is less on byte-level

details, it's easier to think about what our ANs and SNs should actually

accomplish.

\section{Writing the service definition}

\subsection{Messages and types}

Let's look at the messages for the Caesar Cypher again. Using the shorthand

notation that we invented in the previous chapter, they would look something

like:

\begin{verbatim}

   in:  [0x0001] caesar_crypt_req       (nota:bdata text, nota:int8 shift);

   out: [0x0002] caesar_crypt_rsp       (nota:bdata text);

   out: [0x0003] caesar_crypt_error_rsp (caesar:error_t code);

\end{verbatim}

So, we define three messages, one to be implemented by the SN, and the two

others to be implemented by the AN.

Furthermore, we define on custom type, \texttt{caesar:status\_t}, which

describes an error code.

\subsection{Writing some XML}

The next step is to rewrite our shorthand notation into the proper service

file syntax. 

\subsubsection{Definitions}

First, we need to write the \texttt{definitions}-element; as we mentioned in

the previous chapter, it's attributes are ignored for now, but for

informational value, we fill in the \texttt{name}-attribute:

\begin{verbatim}

    <definitions name="caesar">

\end{verbatim}

\subsubsection{Types}

Then comes the \texttt{types}-section, for custom types. In this case, we only

have one custom type, \texttt{caesar:error\_t}, which is a simple enumeration;

we write:

\begin{lstlisting}[language=XML]

  <types>

    <simpleType name="caesar:error_t">

      <restriction base="nota:uns8">

      <enumeration value="0x1000">E_GENERAL_ERROR</enumeration>

      <enumeration value="0x1010">E_INVALID_DATA</enumeration>

      <enumeration value="0x1020">E_INVALID_SHIFT</enumeration>      

      </restriction>

    </simpleType>

  </types>

\end{lstlisting}

\subsubsection{Messages}

Now all that is left is to write down the XML for \texttt{caesar\_crypt\_req},

\texttt{caesar\_crypt\_rsp} and \texttt{caesar\_crypt\_error\_rsp}. With what

we have learned so far, we think the definition of these messages should be

pretty straightforward.

\begin{lstlisting}[language=XML]

  <message name="caesar_crypt_req" code="0x0001" direction="in">

    <documentation>

     request Caesar crypt operation on data

    </documentation>

    <part name="text" type="nota:bdata">

      <documentation>

        Data to crypt or encrypt

      </documentation>

    </part>

    <part name="shift" type="nota:int8">

      <documentation>

	Positions to shift (rotate) 

      </documentation>

    </part>

  </message>

  <message name="caesar_crypt_cnf" code="0x0002" direction="out">

    <documentation>

      Return the encrypted or decrypted data

    </documentation>

    <part name="text" type="nota:bdata">

      <documentation>

        Encrypted or decrypted data

      </documentation>

    </part>

  </message>

  <message name="caesar_crypt_error_rsp" code="0x0003" direction="out">

    <documentation>

      Return an error code

    </documentation>

    <part name="code" type="caesar:error_t">

      <documentation>

	Error code in case some encryption/decryption operation went wrong

      </documentation>

    </part>

  </message>

\end{lstlisting}

And that was all. You can find the complete \texttt{caesar.xml} in appendix~\ref{chap:example}.

\section{Generating the stubs}

As discussed in chapter~\ref{chap:stubgen}, we can use the stub-generator to

generate stubs\index{stub}, i.e. machine generated source code files that take

care of lot of the low-level plumbing code. Let's see what happens.

\begin{lstlisting}[language=sh]

   nota-stubgen3.pl -platform posix . ./caesar.xml

\end{lstlisting}

will create:

\begin{itemize}

\item For the application node: \texttt{caesar\_user.c} and

  \texttt{caesar\_user.h}. 

  For each message in the service description with

  \texttt{direction=\"in\"}, a wrapper function is generated. For messages

  with \texttt{direction=\"out\"} a declaration is generated, for which we

  need to write an implementation. In both cases, the stub-generator takes

  care of translating the bytes in function arguments and vice versa;

\item For the Service Node: \texttt{caesar\_service.c} and

  \texttt{caesar\_service.h}.

  The code that is generated is similar to that for application node, but with

  the \texttt{direction=\"in\"} and \texttt{direction=\"out\"} swapped'

\item \texttt{caesar\_common.h}: common definitions for \texttt{user} and

  \texttt{service}.

\end{itemize}

\section{Writing the Service Node}

Now, let's take a look at the implementing the service node. As seen in the

previous section, we have \texttt{caesar\_service.c} and

\texttt{caesar\_service.h}. Looking at the header file

(\texttt{caesar\_service.h}), we find the following\footnote{if you worry

  about the double \texttt{caesar\_}-prefix: this is due to the message having

  caesar in their names, and also as the overall namespace. Nothing to worry

  about}

\begin{lstlisting}[language=c,caption={\texttt{caesar\_service.h} (fragment)}]

/* Stubs that can be used to send messages */

/*       Return the encrypted or decrypted data */

/*         Encrypted or decrypted data */

int caesar_caesar_crypt_cnf( struct context_pointer* context, uns8* text, 

			     uns16 text_len );

/*       Return an error code */

/*      Error code in case some encryption/decryption operation went wrong */

int caesar_caesar_crypt_error_rsp( struct context_pointer* context, 

				   error_code_t code );

/* Skeleton prototypes; user must implement them. */

void caesar_caesar_crypt_req_process( struct context_pointer* context, 

				      uns8* text, uns16 text_len, int8 shift );

\end{lstlisting}

So, all we need to do is implement the last function

\texttt{caesar\_caesar\_crypt\_req\_process}.

\texttt{caesar\_service.c} contains the plumbing code, and you \textbf{could}

add your implementation there. However, it's better to put your own

implementation in a separate \texttt{.c}-file. This is much easier if your

WSDL ever changes and you need to regenerate the stubs.

In general, it is not a very good idea to change the WSDL after your code has

left the development phase - interfaces should be stable. If you \emph{do}

change interfaces that are used by others, make sure you don't leave your name

in the source code.

It's also a good idea to put the service-startup code in a separate file; so,

we add two files: \texttt{caesar\_service\_impl.c} (with our implementation of

the \texttt{caesar\_service.h}-functions) and  \texttt{caesar-sn.c}, which

contains \texttt{main()} and the starts the service.

\section{Writing an application node}

\begin{lstlisting}[language=c,caption={\texttt{caesar\_user.h}(fragment)}]

/* Stubs that can be used to send messages */

/*      request Caesar crypt operation on data */

/*         Data to crypt or encrypt */

/*      Positions to shift (rotate)  */

int caesar_caesar_crypt_req( struct context_pointer* context, uns8* text, 

			     uns16 text_len, int8 shift );

/* Skeleton prototypes; user must implement them. */

void caesar_caesar_crypt_cnf_process( struct context_pointer* context, 

				      uns8* text, uns16 text_len );

void caesar_caesar_crypt_error_rsp_process( struct context_pointer* context, 

					    error_code_t code );

\end{lstlisting}

Analogous to what we did for the SN, we add two files:

\texttt{caesar\_user\_impl.c} (with our implementation of the

\texttt{caesar\_user.h}-functions) and \texttt{caesar-an.c}, which contains

\texttt{main()} and the starts the application node.

We need to implement So, all we need to do is implement the last function

\texttt{caesar\_caesar\_crypt\_cnf\_process} and

\texttt{caesar\_caesar\_crypt\_error\_rsp\_process}.

\section{Building and running}

Now that we have written the code for AN and SN, it'd be nice to compile and

run them.

\subsection{Makefile}

The easiest way to build the AN and SN is by creating a \texttt{Makefile}. The

details of writing Makefiles is out of the scope of this guide, 

\subsection{running}

\section{Questions}

To test your understanding of this chapter, you could try to answer some of

these questions. You can find the answers to these question in

appendix~\ref{chap:answers}.

\begin{enumerate}

\item Why is it not a good idea to add you own code to

  \texttt{caesar\_service.c} or \texttt{caesar\_user.c}?

\end{enumerate}