\hypertarget{nmsgLib_8c}{
\section{nmsg\-Lib.c File Reference}
\label{nmsgLib_8c}\index{nmsgLib.c@{nmsgLib.c}}
}
Routines for handling formatted network messages. 

{\tt \#include \char`\"{}NMSG/nmsg\-Lib.h\char`\"{}}\par
{\tt \#include $<$stdlib.h$>$}\par
{\tt \#include $<$unistd.h$>$}\par
{\tt \#include $<$sys/types.h$>$}\par
{\tt \#include $<$sys/socket.h$>$}\par
{\tt \#include $<$netdb.h$>$}\par
{\tt \#include $<$netinet/in.h$>$}\par
{\tt \#include $<$pthread.h$>$}\par
{\tt \#include $<$errno.h$>$}\par
{\tt \#include $<$string.h$>$}\par
{\tt \#include $<$stdio.h$>$}\par


Include dependency graph for nmsg\-Lib.c:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=125pt]{nmsgLib_8c__incl}
\end{center}
\end{figure}
\subsection*{Functions}
\begin{CompactItemize}
\item 
int \hyperlink{nmsgLib_8c_a0}{nmsg\-Connect} (void $\ast$$\ast$hndl, char $\ast$node, int port)
\begin{CompactList}\small\item\em Connect to a message server. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a1}{nmsg\-Connect\-Asy} (void $\ast$$\ast$hndl, char $\ast$node, int port, \hyperlink{nmsgLib_8h_a3}{nmsg\-Conn\-CB\_\-t} conn\-Rtn, \hyperlink{nmsgLib_8h_a4}{nmsg\-Disc\-CB\_\-t} disc\-Rtn, void $\ast$u\-Parm)
\begin{CompactList}\small\item\em Connect asynchronously (robustly) to a message server. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a2}{nmsg\-Listen} (void $\ast$$\ast$hndl, int port, int max\-Conn, int max\-Data, \hyperlink{nmsgLib_8h_a3}{nmsg\-Conn\-CB\_\-t} conn\-Rtn, \hyperlink{nmsgLib_8h_a4}{nmsg\-Disc\-CB\_\-t} disc\-Rtn, \hyperlink{nmsgLib_8h_a5}{nmsg\-Rcve\-CB\_\-t} rcve\-Rtn, void $\ast$u\-Parm)
\begin{CompactList}\small\item\em Establish a message server. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a3}{nmsg\-Close} (void $\ast$hndl, int force)
\begin{CompactList}\small\item\em Terminate a message client or server. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a4}{nmsg\-Send\-W} (void $\ast$hndl, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$msg, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$$\ast$reply\-P, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$reply, int max\-Data)
\begin{CompactList}\small\item\em Send a message and receive reply. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a5}{nmsg\-Send} (void $\ast$hndl, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$msg)
\begin{CompactList}\small\item\em Send a message and return immediately. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a6}{nmsg\-Wait} (void $\ast$hndl, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$$\ast$reply\-P, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$reply, int max\-Data)
\begin{CompactList}\small\item\em Wait for a reply to a sent message. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a7}{nmsg\-Remote\-IP} (void $\ast$hndl)
\begin{CompactList}\small\item\em Get the IP address of the remote end. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a8}{nmsg\-Stats} (void $\ast$hndl, \hyperlink{structnmsgStats__s}{nmsg\-Stats\_\-t} $\ast$stats)
\begin{CompactList}\small\item\em Get connection statistics. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a9}{nmsg\-Check} (void $\ast$hndl)
\begin{CompactList}\small\item\em Check a network connection handle. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Routines for handling formatted network messages. 

\begin{Desc}
\item[Author:]Owen H Saxton\end{Desc}
\begin{Desc}
\item[Id]\hyperlink{nmsgLib_8c}{nmsg\-Lib.c},v 1.8 2007/08/30 21:23:45 saxton Exp \end{Desc}


\subsection{Function Documentation}
\hypertarget{nmsgLib_8c_a9}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgCheck@{nmsgCheck}}
\index{nmsgCheck@{nmsgCheck}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgCheck]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Check (void $\ast$ {\em hndl})}}
\label{nmsgLib_8c_a9}


Check a network connection handle. 

This routine checks whether a network handle is valid or not.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The handle for the connection.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 1}]The handle is valid. \item[{\em 0}]The handle is invalid.\end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_a3}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgClose@{nmsgClose}}
\index{nmsgClose@{nmsgClose}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgClose]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Close (void $\ast$ {\em hndl}, int {\em force})}}
\label{nmsgLib_8c_a3}


Terminate a message client or server. 

This routine closes a network connection or stops a network server.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The handle of the connection or server.\item[{\em force}]For a client connection, if TRUE, the connection is closed even if another task is in the process of sending a message. If FALSE, the closing waits until any activity has ceased. Not used for a server.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success. \item[{\em -1}]An error occurred.\end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_a0}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgConnect@{nmsgConnect}}
\index{nmsgConnect@{nmsgConnect}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgConnect]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Connect (void $\ast$$\ast$ {\em hndl}, char $\ast$ {\em node}, int {\em port})}}
\label{nmsgLib_8c_a0}


Connect to a message server. 

This routine establishes a network connection to a message server.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The address of a pointer to receive the identifying handle for the network connection.\item[{\em node}]The address of the name of the node containing the message server.\item[{\em port}]The port number on which to establish the connection.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]The connection was established successfully. \item[{\em -1}]An error occurred.\end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_a1}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgConnectAsy@{nmsgConnectAsy}}
\index{nmsgConnectAsy@{nmsgConnectAsy}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgConnectAsy]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Connect\-Asy (void $\ast$$\ast$ {\em hndl}, char $\ast$ {\em node}, int {\em port}, \hyperlink{nmsgLib_8h_a3}{nmsg\-Conn\-CB\_\-t} {\em conn\-Rtn}, \hyperlink{nmsgLib_8h_a4}{nmsg\-Disc\-CB\_\-t} {\em disc\-Rtn}, void $\ast$ {\em u\-Parm})}}
\label{nmsgLib_8c_a1}


Connect asynchronously (robustly) to a message server. 

This routine establishes a robust network connection to a message server. The connection is done asynchronously, and the attempt is retried periodically if the initial attempt fails, or if the connection is broken.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The address of a pointer to receive the identifying handle for the network connection.\item[{\em node}]The address of the name of the node containing the message server.\item[{\em port}]The port number on which to establish the connection.\item[{\em conn\-Rtn}]The address of a routine to be called when the connection has been made.\item[{\em disc\-Rtn}]The address of a routine to be called when the connection is broken.\item[{\em u\-Parm}]A parameter to be passed to the connect and disconnect callback routines.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]The connection process was started successfully. \item[{\em -1}]An error occurred.\end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_a2}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgListen@{nmsgListen}}
\index{nmsgListen@{nmsgListen}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgListen]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Listen (void $\ast$$\ast$ {\em hndl}, int {\em port}, int {\em max\-Conn}, int {\em max\-Data}, \hyperlink{nmsgLib_8h_a3}{nmsg\-Conn\-CB\_\-t} {\em conn\-Rtn}, \hyperlink{nmsgLib_8h_a4}{nmsg\-Disc\-CB\_\-t} {\em disc\-Rtn}, \hyperlink{nmsgLib_8h_a5}{nmsg\-Rcve\-CB\_\-t} {\em rcve\-Rtn}, void $\ast$ {\em u\-Parm})}}
\label{nmsgLib_8c_a2}


Establish a message server. 

This routine establishes a network message server (listener).

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The address of a pointer to receive the identifying handle for the network listener.\item[{\em port}]The port number on which to establish the server.\item[{\em max\-Conn}]The maximum number of concurrent connections that the server will allow.\item[{\em max\-Data}]The maximum number of data bytes that can be transferred in a single message.\item[{\em conn\-Rtn}]The address of a routine to be called when a new connection has been made. The connection will be rejected if this routine returns ERROR status.\item[{\em disc\-Rtn}]The address of a routine to be called when a connection is broken.\item[{\em rcve\-Rtn}]The address of a routine to be called whenever a message is received.\item[{\em u\-Parm}]A parameter to be passed to the connect, disconnect and receive callback routines.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]The message server was started successfully. \item[{\em -1}]An error occurred.\end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_a7}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgRemoteIP@{nmsgRemoteIP}}
\index{nmsgRemoteIP@{nmsgRemoteIP}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgRemoteIP]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Remote\-IP (void $\ast$ {\em hndl})}}
\label{nmsgLib_8c_a7}


Get the IP address of the remote end. 

This routine returns the IP address of the remote end of a connection. It can be used on either end of a connection.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The handle for the connection.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The IP address of the remote end of the connection, or -1 if the handle is invalid.\end{Desc}
\hypertarget{nmsgLib_8c_a5}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgSend@{nmsgSend}}
\index{nmsgSend@{nmsgSend}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgSend]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Send (void $\ast$ {\em hndl}, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$ {\em msg})}}
\label{nmsgLib_8c_a5}


Send a message and return immediately. 

This routine sends a message on a network connection and returns without waiting for a reply.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The handle for the connection.\item[{\em msg}]The address of message to be sent. It must be formatted using the nmsg\-Buff\_\-t structure type.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success. \item[{\em -1}]An error occurred.\end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_a4}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgSendW@{nmsgSendW}}
\index{nmsgSendW@{nmsgSendW}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgSendW]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Send\-W (void $\ast$ {\em hndl}, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$ {\em msg}, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$$\ast$ {\em reply\-P}, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$ {\em reply}, int {\em max\-Data})}}
\label{nmsgLib_8c_a4}


Send a message and receive reply. 

This routine sends a message on a network connection and waits for a reply.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The handle for the connection.\item[{\em msg}]The address of message to be sent. It must be formatted using the nmsg\-Buff\_\-t structure type.\item[{\em reply\-P}]The address of a pointer to receive the address of the reply. If a reply area is supplied and it is big enough, this will be the address of this area. Otherwise a sufficiently large reply area is allocated and its address returned here. In this latter case, the memory must be relinquished using free() after it is no longer needed.\item[{\em reply}]The address of an area to receive the reply to the message, or NULL if no area is to be used.\item[{\em max\-Data}]The maximum number of data bytes that can be put into the supplied reply area.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success. \item[{\em -1}]An error occurred.\end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_a8}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgStats@{nmsgStats}}
\index{nmsgStats@{nmsgStats}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgStats]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Stats (void $\ast$ {\em hndl}, \hyperlink{structnmsgStats__s}{nmsg\-Stats\_\-t} $\ast$ {\em stats})}}
\label{nmsgLib_8c_a8}


Get connection statistics. 

This routine returns a block of connection statistics containing the number of connects, disconnects, messages sent/received, bytes sent and bytes received.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The handle for the connection.\item[{\em stats}]The address of an area to receive the statistics block.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success. \item[{\em -1}]The handle is invalid.\end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_a6}{
\index{nmsgLib.c@{nmsg\-Lib.c}!nmsgWait@{nmsgWait}}
\index{nmsgWait@{nmsgWait}!nmsgLib.c@{nmsg\-Lib.c}}
\subsubsection[nmsgWait]{\setlength{\rightskip}{0pt plus 5cm}int nmsg\-Wait (void $\ast$ {\em hndl}, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$$\ast$ {\em reply\-P}, \hyperlink{structnmsgBuff__s}{nmsg\-Buff\_\-t} $\ast$ {\em reply}, int {\em max\-Data})}}
\label{nmsgLib_8c_a6}


Wait for a reply to a sent message. 

This routine waits for a reply to a previously sent message.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hndl}]The handle for the connection.\item[{\em reply\-P}]The address of a pointer to receive the address of the reply. If a reply area is supplied and it is big enough, this will be the address of this area. Otherwise a sufficiently large reply area is allocated and its address returned here. In this latter case, the memory must be relinquished using free() after it is no longer needed.\item[{\em reply}]The address of an area to receive the reply to the message, or NULL if no area is to be used.\item[{\em max\-Data}]The maximum number of data bytes that can be put into the supplied reply area.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success. \item[{\em -1}]An error occurred.\end{description}
\end{Desc}