\chapter{The high-level interconnect API}\label{chap:h-in}

\index{high-level interconnect}

\section{Introduction}

In this chapter, we discuss the {\tt h\_in}-API offered by the NoTA reference

implementation.

The {\tt h\_in}-API found in the NoTA reference implementation is inspired by

the BSD Socket API, famously documented by

Stevens~\cite{Stevens2003}. Generally, the name of the NoTA-function is the

same as the corresponding BSD function, prefixed with {\tt H}, and taking an

extra \texttt{h\_in\_t*}-value as its first parameter.

However, as mentioned before, there can be semantic differences between the

{\tt h\_in}-function and their BSD-counterparts, so you should carefully read

the documentation -- we try to point out those differences. 

\Note{in many cases, using the stub-generator (chapter

\ref{chap:stubgen}), is an easier alternative to developing NoTA-services than

using the {\tt h\_in}-API discussed here, directly. However, the stub

generator is not perfect, and details of {\tt h\_in} may leak through, for

example when debugging a system. Therefore, a good understanding of what the

{\tt h\_in} is very useful for understanding NoTA programming as a whole.}

\section{NoTA socket functions}

In this section, we discuss all of the NoTA socket\index{socket} functions

that the {\tt h\_in}-API offers, in (roughly) the order of appearance in a

typical program. 

Before we go into the functions, first a general note about error

handling. Errors are an unavoidable aspect of programming after all, and in

particular network-related programming.

The {\tt h\_in}-API emulates the BSD-API, including its error-handling -

usually you can get information about errors by inspecting \texttt{errno}, and

you can get an human-readable version of that by using the

\texttt{strerror}-function call. The man-pages on your systems have the

details -- such as the need for some include files to use \texttt{errno} and \texttt{strerror}:

\begin{lstlisting}

#include <errno.h>

#include <string.h>

\end{lstlisting}

Now, let's go through the function the \texttt{h\_in}-API provides.

\subsection{{\tt Hgetinstance()}}

\begin{lstlisting}

  h_in_t* Hgetinstance (void);

\end{lstlisting}

The first thing you need to do when you write a NoTA-program, is acquiring a

NoTA {\em instance pointer}. The function to do so is called {\tt

Hgetinstance}; it does not have a counterpart in the BSD-socket API.

Note that you can call this function multiple times, but in the same process

it will always return the same pointer. Also note that there is no need to

free the instance pointer; the instance pointer and related resources will be

freed automatically upon process termination.

\begin{lstlisting}

  h_in_t *inst = Hgetinstance ();

\end{lstlisting}

Both AN and SN need to get the instance pointer before doing anything else, as

all other NoTA-function require you to pass this pointer.

\subsubsection{Errors}

In case of error, \texttt{Hgetinstance} will return \texttt{NULL}. You can

inspect \texttt{errno} to find out more. A common reason for a failing

\texttt{Hgetinstance} would be some issue with the runtime-environment; please

see appendix~\ref{chap:running} for some possible causes and solutions.

\subsection{{\tt Hsocket()}}

\begin{lstlisting}

int Hsocket(h_in_t* core, int domain, int type, int protocol);

\end{lstlisting}

To connect to other NoTA-node, the NoTA reference implementation provides {\em

  sockets}, very similar to BSD-sockets\index{socket}. The reason for this is

that it provides a familiar API for programmers with a

UNIX\index{UNIX}-background and there is a lot of documentation available for

programmers coming from different backgrounds. The {\tt Hsocket}-call is

analogous to the {\tt socket(3)} call of the BSD socket API.

NoTA sockets come in two flavors:

\begin{itemize}

\item there are {\em stream sockets}, which are meant for streaming bulk data,

  and

\item {\em message sockets}, which, instead are use for sending {\em NoTA

    messages} (to be discussed later in this chapter).

\end{itemize}

NoTA guarantees the message borders on message sockets - that means, messages

are received as a whole; in contrast, when you use a stream socket, you might

get only a subset of the message, and getting the rest would require reading

more from the socket.

\begin{lstlisting}

 /* stream socket */

 int sock = Hsocket (inst, AF_NOTA, SOCK_STREAM, 0);

\end{lstlisting}

\begin{lstlisting}

 /* message socket */

 int sock = Hsocket (inst, AF_NOTA, SOCK_SEQPACKET, 0);

\end{lstlisting}

Stream sockets are more efficient for bulk data; message sockets are more

efficient (and easier to use) for NoTA messages.

If you plan to use \texttt{SOCK\_SEQPACKET}, see the important notes about

that in the discussion about \texttt{Hrecv}. Here we note that \textbf{both

  sides} of a connection must have the \textbf{same} type, either

\texttt{SOCK\_STREAM} or \texttt{SOCK\_SEQPACKET}.

As with BSD-sockets, sockets are represented by small integers, and need to be

closed ({\tt Hclose}) when done with them.

\subsubsection{Errors}

In case of error, \texttt{Hsocket} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if \texttt{inst} is invalid, or some internal error occurred;

\item \texttt{EAFNOSUPPORT} if \texttt{domain} not is \texttt{AF\_NOTA};

\item \texttt{EPROTONOSUPPORT} if \texttt{type} not either

  \texttt{SOCK\_STREAM} or \texttt{SOCK\_SEQPACKET}, or if \texttt{protocol}

  not is \texttt{0} (zero);

\item \texttt{ENONET} if the \texttt{inst} is not ready yet.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{socket}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Hclose()}}

\begin{lstlisting}

int Hclose(h_in_t* core, int sock);

\end{lstlisting}

When you no longer need a NoTA socket, you should close it, so NoTA can free

any related resources. Closing a NoTA sockets is done using the {\tt Hclose()}

call (similar to the UNIX\index{UNIX}{\tt close(3)}-call for file descriptors.

\begin{lstlisting}

int rv = Hclose (inst, sock);

\end{lstlisting}

We'd like to emphasize that closing unused NoTA sockets is important as they

consume quite some system resources. Also, in many cases, a NoTA-socket will

embed operating system sockets, and there are only of limited number of those

available (for example, Linux allows \texttt{1024} file descriptors

(sockets) per process when using default settings).

\subsubsection{Errors}

As with {\tt close(3)}, it is recommended that you {\bf do} check the return

value of this call. 

In case of error, \texttt{Hclose} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if \texttt{inst} is invalid, or some internal error

  occurred, 

\item \texttt{EFAULT} if \texttt{inst} is busy or a number of other problems

  occurred;

\item \texttt{ENOTSOCK} if \texttt{sock} is not a NoTA-socket;

\item \texttt{EBUSY} if \texttt{sock} is busy.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{close}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Hconnect()}}

\begin{lstlisting}

int Hconnect(h_in_t* core, int sockid, struct sockaddr* addr,

              socklen_t addrlen);

\end{lstlisting}

Application nodes use the {\tt Hconnect}-function to connect to service

nodes, very similar to what the {\tt connect(3)} call does in the BSD API. 

\begin{lstlisting}

static nota addr t addr = { 1, 1 }; /* NoTA-address */

int rv = Hconnect (inst, sock, (struct sockaddr*)&addr, sizeof(addr));

\end{lstlisting}

This call will (try to) connect to some NoTA-id, which is a structure of three

values; the {\tt h\_in} defines it as follows:

\begin{lstlisting}

typedef unsigned int sid_t;

typedef unsigned int vdid_t;

struct nota_addr {

  sid_t        sid;       /* service identifier */

  unsigned int port;      /* port of the sid */

  vdid_t       device;    /* virtual device id */

};

typedef struct nota_addr nota_addr_t;

\end{lstlisting}

The virtual device id is not currently in use; the other two values are:

\begin{itemize}

\item the {\em service id}(SID)\index{service-id}. This number uniquely

  references a specific Service Node - unique within the context of a NoTA

  network.

\item the {\em port number}\index{port-number}. Similar to a TCP/UDP-port

  number, this number identifies a specific service exposed by a service

  node. For example, a Service Node could have one port open for commands

  ({\tt play()}, {\tt pause()}), and another one for actually streaming the

  data.

\end{itemize}

The recommended way to get these numbers is by using the resource manager (to

be discussed in chapter~\ref{chap:rm}); however, for simple examples you can

define them manually as well.

Also note that \texttt{Hsocket} is a \emph{blocking} call. If, for example, no

\texttt{NOTA\_LMANAGER} has been defined (see appendix~\ref{chap:running}),

the call might hang your application, and you cannot mark the socket as

'non-blocking'.

\subsubsection{Errors}

In case of error, \texttt{Hconnect} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if \texttt{inst} is invalid, or some internal error

  occurred, 

\item \texttt{EFAULT} if \texttt{inst} is busy or a number of other problems

  occurred;

\item \texttt{ECONNREFUSE}  the other side of the connection was not

  listening, or not accepting connections;

\item \texttt{ENETUNREACH} if \texttt{sock} cannot reach the

  network\footnote{the internal error is that IA cannot be retrieved; further

  discussion is beyond the scope of this document};

\item \texttt{ENOTSOCK} if \texttt{sock} is not a NoTA-socket.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{connect}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Hsend()}}

\begin{lstlisting}

 int Hsend(h_in_t* core, int sockid, const void* buf, int len, int flags);

\end{lstlisting}

Now, let's assume we have connected to some Service Node (using {\tt

  Hconnect()}. We can send some data to it, using the {\tt Hsend}-function,

similar to what the {\tt send(3)} function does in the BSD-API.

\begin{lstlisting}    

    const char* str = ¨Hello, world!¨;

    int sent = Hsend (inst, sock, str, strlen(str), 0);

\end{lstlisting}

This will send the data through the socket. The function returns the number of

bytes actually sent (in case of streaming sockets, this may be smaller than

the amount requested), or -1 in case of error. In case of errors, you {\tt

errno} to get some information about what went wrong.

Most of the arguments should be straightforward to understand, but let's look

at the last one, {\tt flags}. This parameter should be either zero (default

behavior), or {\tt MSG\_DONTWAIT}. In the latter case, we're sending data in

{\em non-blocking}-mode\index{non-blocking}: if the data cannot be sent

immediately (that is, it would block if we would try), the function will

return with a value of {\tt EAGAIN} (think: '\textit{try again later}').

{\bf Important note}: in the above example, we are sending some simple string

over the NoTA-socket; this is a valid way when sending opaque data to some

Service Node. However, to send specific messages to other NoTA-nodes (for

example, sending a {\tt play()} or {\tt pause()} message to an music player

SN), we need the the NoTA service signal syntax which is discussed in

section~\ref{sec:notaservicesignals}.

Another important thing to remember is that for scalability and dealing with

many sockets at the same time, you might want to use {\tt Hselect()}, to be

discussed later.

\subsubsection{Errors}

In case of error, \texttt{Hsend} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if \texttt{inst} is invalid, or some internal error

  occurred, 

\item \texttt{EFAULT} if \texttt{inst} is busy or a number of other problems

  occurred;

\item \texttt{EMSGSIZE} if the message size is exceeding the

  maximum\footnote{currently defined at \texttt{4096}} (on

  \texttt{SOCK\_SEQPACKET}-sockets; 

\item \texttt{ENOTCONN} if the socket is not connected;

\item \texttt{ENOTSOCK} if \texttt{sock} is not a NoTA-socket.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{send}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Hrecv()}}

\begin{lstlisting}

 int Hrecv(h_in_t* core, int sockid, void* buf, int len, int flags);

\end{lstlisting}

To receive data from a NoTA socket, we can use the {\tt Hrecv}-function, which

is the NoTA-version of {\tt recv(3)}.

Let's assume we are connected to some Service Node, we've sent it some message

(see section~\label{sec:notaservicesignals}), and we are now waiting for the

the SN to send us some bytes in reply. For this, we need {\tt Hrecv}. An

example:

\begin{lstlisting}    

  char buf[10];

  int received = Hrecv (inst, sock, buf, sizeof(buf), 0);

\end{lstlisting}

This will get us up to 10 bytes from the socket. 

\subsubsection{Blocking or not}

The {\bf flags} argument influences how the \texttt{Hrecv} operates; if you specify

{\tt MSG\_DONTWAIT}, we receive data in {\em non-blocking}-mode; that is, if

data cannot be received immediately, the function will return with a value of

{\tt EAGAIN}, instead of blocking, which is the default. If you specify {\tt

  MSG\_WAITALL}, the function will not return until the function received {\tt

  len} bytes. In practice, this is of limited use. You can specify multiple

flags by doing a bitwise-OR, just like with the BSD-{\tt recv}.

\subsubsection{Using \texttt{MSG\_PEEK} and \texttt{MSG\_TRUNC}}

Two other important flags to \texttt{Hrecv} are \texttt{MSG\_PEEK} and

\texttt{MSG\_TRUNC}. The first one causes the \texttt{Hrecv} \textbf{not} to

consume the read data -- if you read again, you will get the same data. The

use of \texttt{MSG\_PEEK} is not necessarily implemented for all transports,

which can lead to problems. We therefore discourage its use in most cases.

There is one exception to this: when using \texttt{SOCK\_SEQPACKET}, it is

often useful to find out the size of the next \emph{message}, so sufficient buffer

space can be allocated. We discuss messages only later in this chapter, but

here it suffices today that NoTA-messages are of \emph{variable-length}, and one

cannot determine the actual length of the whole message without parsing

it. This would make parsing message very tedious and involving many little

\texttt{Hrecv}s, error checking an so on.

Thankfully, there is a way to get the length of the next available

message\footnote{The BSD-API also offers \texttt{recvmsg} and

  \texttt{sendmsg}, but they don't have NoTA counterparts}: using the

\texttt{MSG\_TRUNC}-flag. This flag causes \texttt{Hrecv} return the length

of the \emph{next available message} - even if this length is more than the

\texttt{len}-argument to \texttt{Hrecv}. So, what happens when the message

size is bigger than the buffer size? 

Good question. Look at the name of the flag again - \texttt{MSG\_TRUNC} -

indeed, the rest of the data will be \emph{truncated}, i.e., thrown away. That

is usually not what we want, so we can use \texttt{MSG\_PEEK} for that.

The pattern to read a full message in one go would then be:

\begin{lstlisting}    

  sock = Hsocket (inst, AF_NOTA, SOCK_SEQPACKET, 0);

  [...] /* waiting for some message...*/

   int size = Hrecv (inst, sock, dummy, 1, MSG_TRUNC|MSG_PEEK);

   if (size > 0) {

         /* get a 'buf' of a least `size' bytes */ 

         read = Hrecv (inst, sock, buf, size, 0);

         /* now we should have the full message in `buf` */

   } else ....

\end{lstlisting}

Again, you'll probably need to go through chapter~\ref{chap:messages} (about

NoTA messages) to fully appreciate this - just take a mental note now.

\subsubsection{Errors}

In case of error, \texttt{Hrecv} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if \texttt{inst} is invalid, or some internal error

  occurred, 

\item \texttt{EFAULT} if \texttt{inst} is busy or a number of other problems

  occurred;

\item \texttt{ENOTSOCK} if \texttt{sock} is not a NoTA-socket.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{recv}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Hbind()}}

\begin{lstlisting}

 int Hbind(h_in_t* core, int sockfd, struct sockaddr* my_addr,

           socklen_t addrlen);

\end{lstlisting}

To bind our socket to a certain (NoTA) port, we need {\em Hbind} to that port,

similar to what BSD's {\tt bind(3)} does. This would look something like the

following:

\begin{lstlisting}

static nota_addr_t addr = { 1, 1 };

int rv = Hbind (inst, sock, (struct sockaddr*)&addr, 

                sizeof(addr)); 

\end{lstlisting}

{\tt Hbind} is useful for NoTA Service Nodes, to make them available for

application nodes. After you have successfully called {\tt Hbind}, you should

call {\tt Hlisten} to actually start the listening. Application nodes could

use {\tt Hbind} as well, to specify the port {\em they} would like to use -

but often, we don't really care about that.

It's important to remember that while they have the same function, NoTA ports

are {\bf not} the same as TCP/UDP-ports. 

Also note that \texttt{Hbind} is a \emph{blocking} call. If, for example, no

\texttt{NOTA\_LMANAGER} has been defined (see appendix~\ref{chap:running}),

the call might hang your application, and you cannot mark the socket as

'non-blocking'.

\subsubsection{Errors}

In case of error, \texttt{Hbind} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if there is something wrong with the parameters, 

\item \texttt{EFAULT} if the \texttt{sock} could not be found, or something

  else is wrong;

\item \texttt{EBADF} if \texttt{sock} is invalid;

\item \texttt{ENOTSOCK} if \texttt{sock} is of the wrong type;

\item \texttt{EADDRINUSE} if the address has already been bound;

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{bind}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Hlisten()}}

\begin{lstlisting}

 int Hlisten(h_in_t* core, int sockid, int backlog);

\end{lstlisting}

After you have bound a socket to some port with {\tt Hbind}, you can put the

socket in listening mode with {\tt Hlisten}, similar to BSD's {\tt

  listen(3)}. You can specify the maximum number of outstanding connections

with the {\tt backlog} parameter.

\begin{lstlisting}

int rv = Hlisten (core, sock, 1); 

\end{lstlisting}

After this, your socket is ready to accept connections. This is mostly useful

for service nodes. After setting your socket to listening mode, you can start

the actual listening with {\tt Haccept}.

\subsubsection{Errors}

In case of error, \texttt{Hlisten} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if there is something wrong with the parameters, 

\item \texttt{EFAULT} if the \texttt{sock} could not be found, or something

  else is wrong;

\item \texttt{ENOTSOCK} if \texttt{sock} is of the wrong type;

\item \texttt{ENOTSUP} if \texttt{sock} does not support listening.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{listen}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Haccept()}}

\begin{lstlisting}

 int Haccept(h_in_t* core, int sockid, struct sockaddr* addr,

              socklen_t* addrlen);

\end{lstlisting}

Now, after we have bound our socket to a port (using {\tt Hbind}), and set it

to listening mode (using {\tt Hlisten)}), we are now ready to accept

connections from clients. This final step is done with {\tt Haccept}, which

blocks\index{blocking} until some client (application node) opens a

connection. When the connection is accepted, {\tt Haccept} returns the {\em

  peer socket}, that is, a socket on which the communication with the client

can take place.

For example:

\begin{lstlisting}

	peersock = Haccept (inst, sock, NULL, NULL);

\end{lstlisting}

In a diversion from BSD's {\tt accept(3)}, {\tt Haccept} does {\bf not} return

any information about this peer socket in its last two arguments. {\tt

  Haccept} includes them for the sake of following BSD as close as possible,

but the actual parameters are ignored.

Note that {\tt Haccept} is a synchronous, {\bf blocking}\index{blocking}

call. Thus, in order to be able to serve multiple clients (Application

Nodes), some multiprocessing mechanism is needed, such as forking or

threading.

\subsubsection{Errors}

In case of error, \texttt{Haccept} returns a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if there is something wrong with the parameters; 

\item \texttt{EFAULT} if the \texttt{sock} could not be found, or something

  else is wrong;

\item \texttt{ENOTSOCK} if \texttt{sock} is not a socket, or of the wrong

  type;

\item \texttt{ENOTCONN} if \texttt{sock} is not connected.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{accept}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Hselect()}}

\begin{lstlisting}

  int Hselect(h_in_t* inst, int nfd, fd_set* read_fds, fd_set* write_fds,

              fd_set* error_fds, struct timeval* tv);

\end{lstlisting}

The {\tt Hselect} function allows you to multiplex over sets of NoTA

sockets. That is, it monitors sets of NoTA sockets, and finds out which ones

are ready for reading or writing, and for which ones errors

occurred. '\emph{Ready}' here means that they can be either read or written

without blocking.

The final {\tt tv} argument (a {\tt struct timeval*}) specifies the maximum

amount of time {\tt Hselect} is allowed to take\footnote{Note that the actual

  timeout the reference implementation uses {\tt ceil(tv->tv\_sec +

    tv->tv\_usec)}; timeout values with sub-second resolution are not

  possible.}. 

A value of zero means that the function will \textbf{instantly return};

passing \texttt{NULL}-pointer means that \texttt{Hselect} should wait

indefinitely until one some changes for one of the sockets it manages --

becomes ready for reading or writing, or some error occurred.

For dealing with the {\tt fd\_set}-arguments, the familiar {\tt FD\_}-macros

can be used:

\begin{itemize}

\item {\tt FD\_ZERO} - clears a set;

\item {\tt FD\_SET} - add a given NoTA socket to the set;

\item {\tt FD\_CLEAR} - remove a given NoTA socket from the set;

\item {\tt FD\_ISSET} - is the given NoTA socket an element of the set?

\end{itemize}

Like its counterpart \texttt{select}, \texttt{Hselect} is a rather complicated

function; hopefully we can clarify with the example below. It describes a

function \texttt{is\_socket\_ready\_for\_reading}, that check whether one

specific socket can now be read without blocking, while the

\texttt{Hselect}-call itself blocks for up to two seconds.

If you \textbf{don't} want to block at all, you should set the

\texttt{tv}-parameters to \texttt{\{0,0\}}. If you set it to \texttt{NULL},

there is no timeout (i.e., \texttt{Hselect} may block indefinitely in that

case).

\begin{lstlisting}

int

is_socket_ready_for_reading (fd_set fds_socks, int socks_num, int sock) 

{

	int rv;

        struct timeval tv = { 2, 0 }; /* wait two seconds at most */

        fd_set read_fds = fds_socks; /* fd_sets are just numbers  */

        rv = Hselect (inst, sock_num, 

		      &read_fds, /* read  */

		      NULL,      /* write */  

		      NULL,      /* error */

		      &tv);      /* timeout */

	if (rv < 0) 

		/* error handling... */;

	/* return 1 if socket is ready for reading, 0 otherwise */

	return FD_ISSET(sock, read_fds);

}

\end{lstlisting}

\subsubsection{Errors}

In case of error, \texttt{Hselect} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if there is something wrong with the parameters; 

\item \texttt{EFAULT} if the \texttt{sock} could not be found, or something

  else is wrong;

\item \texttt{EBADF}  if there's some invalid socket in any of the sets;

\item \texttt{ENOMEM} if there's not enough memory available.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{select}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Hsetsockopt()}}

\begin{lstlisting}

 int Hsetsockopt(h_in_t* core, int sockid, int level, int optname,

                  void* optval, socklen_t optlen);

\end{lstlisting}

With the {\tt Hsetsockopt}-function, one can manipulate various NoTA socket

details, similar to BSD's {\tt setsockopt(3)}. 

Currently, the only option one can set on a NoTA socket is {\tt SO\_PASSCRED};

also, the {\bf level}-parameter must be equal to {\tt SOL\_SOCKET}.

\begin{lstlisting}

 const char* str = ¨JOSHUA¨;

 rv = Hsetsockopt(inst, sock, SOL_SOCKET, SO_PASSCRED, str, strlen(str));

\end{lstlisting}

The {\tt SO\_PASSCRED}-parameter can be read on the other side of the

connection (with {\tt Hgetsockopt()}, and as such be use for somewhat secure

authentication if there is some out-of-band mechanism for sharing the secret

securely beforehand.

\subsubsection{Errors}

In case of error, \texttt{Hsetsockopt} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if there is something wrong with the parameters; note,

  currently level \textbf{must} be \texttt{SOL\_SOCKET} and \texttt{optname}

  \textbf{must} be \texttt{SO\_PASSCRED};

\item \texttt{EFAULT} if the \texttt{sock} could not be found, or something

  else is wrong.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{setsockopt}-function may provide some suggestion as to what went wrong.

\subsection{{\tt Hgetsockopt()}}

\begin{lstlisting}

  int Hgetsockopt(h_in_t* core, int sockid, int level, int optname,

                  void* optval, socklen_t* optlen);

\end{lstlisting}

With the {\tt Hgetsockopt}-function, you can retrieve various NoTA socket

details, similar to BSD's {\tt getsockopt(3)}.

Currently, the only option available on a NoTA socket is {\tt SO\_PASSCRED};

also, the {\bf level} parameter must be equal to {\tt SOL\_SOCKET}.

\begin{lstlisting}

  char buf[16];

  rv = Hgetsockopt(inst, sock, SOL_SOCKET, SO_PASSCRED,

                   &buf, sizeof(buf));

\end{lstlisting}

The {\tt SO\_PASSCRED}-parameter (which may be set with {\tt Hsetsockopt} on

the other side of the connection) can be used for authentication purposes,

using some pre-shared secret with 'the other side'.

\subsubsection{Errors}

In case of error, \texttt{Hgetsockopt} will return a negative value, and

\texttt{errno} will contain an error code:

\begin{itemize}

\item \texttt{EINVAL} if there is something wrong with the parameters; note,

  currently level \textbf{must} be \texttt{SOL\_SOCKET} and \texttt{optname}

  \textbf{must} be \texttt{SO\_PASSCRED}; also \texttt{*optlen} must be $>$ 0;

\item \texttt{EFAULT} if the \texttt{sock} could not be found, or something

  else is wrong.

\end{itemize}

Other errors may occur as well. The errors of the BSD's

\texttt{getsockopt}-function may provide some suggestion as to what went wrong.

\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 Can you list some differences between the BSD socket API and the

  NoTA H\_in API?

    \item Which API function can you use to send data to another node?

\end{enumerate}