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

{\tt \#include $<$NMSG/nmsgLib.h$>$}\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
\subsection*{Functions}
\begin{CompactItemize}
\item 
int \hyperlink{nmsgLib_8c_25bf2c1f0b7a13933dd287217f2ac91f}{nmsgCheck} (void $\ast$hndl)
\begin{CompactList}\small\item\em Check a network connection handle. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_5825f59b8d3fe194da574ca42123ca38}{nmsgClose} (void $\ast$hndl, int force)
\begin{CompactList}\small\item\em Terminate a message client or server. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_b260e1d6c2b2a5f9c5c9e7679f1825ea}{nmsgConnect} (void $\ast$$\ast$hndl, const char $\ast$node, int port)
\begin{CompactList}\small\item\em Connect to a message server. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_760bb4dc4613df085bb7fd2f3d3ed093}{nmsgConnectAsy} (void $\ast$$\ast$hndl, const char $\ast$node, int port, int prio, \hyperlink{nmsgLib_8h_7fb49de7485ac2f9380cf3ce0bb8d4f9}{nmsgConnCB\_\-t} connRtn, \hyperlink{nmsgLib_8h_cd045829aacd8819c592ec5ea3492a7f}{nmsgDiscCB\_\-t} discRtn, void $\ast$uParm)
\begin{CompactList}\small\item\em Connect asynchronously (robustly) to a message server. \item\end{CompactList}\item 
const char $\ast$ \hyperlink{nmsgLib_8c_fe1bfca2cf3723a010fcb51e8df9012a}{nmsgErrorMsg} (int status)
\begin{CompactList}\small\item\em Obtain the text of an error message. \item\end{CompactList}\item 
void \hyperlink{nmsgLib_8c_ac6d5bd6e40a2b55f09e57d4b13bc63a}{nmsgErrorReport} (int status, const char $\ast$func)
\begin{CompactList}\small\item\em Display an error message. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_55b2221322b47b41f9404c23fe59fcaa}{nmsgListen} (void $\ast$$\ast$hndl, int port, int maxConn, int maxData, int prio, \hyperlink{nmsgLib_8h_7fb49de7485ac2f9380cf3ce0bb8d4f9}{nmsgConnCB\_\-t} connRtn, \hyperlink{nmsgLib_8h_cd045829aacd8819c592ec5ea3492a7f}{nmsgDiscCB\_\-t} discRtn, \hyperlink{nmsgLib_8h_5ae50803942223e24a3bd3406fde75a8}{nmsgRcveCB\_\-t} rcveRtn, void $\ast$uParm)
\begin{CompactList}\small\item\em Establish a message server. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_f38393f16a9ad082e681ef440cddbe46}{nmsgRemoteIP} (void $\ast$hndl, int $\ast$ip)
\begin{CompactList}\small\item\em Get the IP address of the remote end. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_c02e377443f8404d36f8beed75a2e622}{nmsgSend} (void $\ast$hndl, \hyperlink{structnmsgBuff__s}{nmsgBuff\_\-t} $\ast$msg)
\begin{CompactList}\small\item\em Send a message and return immediately. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_f66406f1031d4de9f4125241f069b3e5}{nmsgSendW} (void $\ast$hndl, \hyperlink{structnmsgBuff__s}{nmsgBuff\_\-t} $\ast$msg, \hyperlink{structnmsgBuff__s}{nmsgBuff\_\-t} $\ast$$\ast$replyP, \hyperlink{structnmsgBuff__s}{nmsgBuff\_\-t} $\ast$reply, int maxData)
\begin{CompactList}\small\item\em Send a message and receive reply. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_a96f2724ad6d35da14aad7666cc4d68c}{nmsgStats} (void $\ast$hndl, \hyperlink{structnmsgStats__s}{nmsgStats\_\-t} $\ast$stats)
\begin{CompactList}\small\item\em Get connection statistics. \item\end{CompactList}\item 
int \hyperlink{nmsgLib_8c_d12b00b6a96b50f3c79d88b99917f333}{nmsgWait} (void $\ast$hndl, \hyperlink{structnmsgBuff__s}{nmsgBuff\_\-t} $\ast$$\ast$replyP, \hyperlink{structnmsgBuff__s}{nmsgBuff\_\-t} $\ast$reply, int maxData)
\begin{CompactList}\small\item\em Wait for a reply to a sent message. \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]\end{Desc}


\subsection{Function Documentation}
\hypertarget{nmsgLib_8c_25bf2c1f0b7a13933dd287217f2ac91f}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgCheck@{nmsgCheck}}
\index{nmsgCheck@{nmsgCheck}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgCheck (void $\ast$ {\em hndl})}}
\label{nmsgLib_8c_25bf2c1f0b7a13933dd287217f2ac91f}


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_5825f59b8d3fe194da574ca42123ca38}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgClose@{nmsgClose}}
\index{nmsgClose@{nmsgClose}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgClose (void $\ast$ {\em hndl}, int {\em force})}}
\label{nmsgLib_8c_5825f59b8d3fe194da574ca42123ca38}


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 NMSG\_\-SUCCESS}]Success. \item[{\em NMSG\_\-INVHNDL}]Invalid network handle. \end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_b260e1d6c2b2a5f9c5c9e7679f1825ea}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgConnect@{nmsgConnect}}
\index{nmsgConnect@{nmsgConnect}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgConnect (void $\ast$$\ast$ {\em hndl}, const char $\ast$ {\em node}, int {\em port})}}
\label{nmsgLib_8c_b260e1d6c2b2a5f9c5c9e7679f1825ea}


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 NMSG\_\-SUCCESS}]The connection was established successfully. \item[{\em NMSG\_\-NOMEMORY}]Insuffucuent memory available. \item[{\em NMSG\_\-UNKNHOST}]Host is unknown. \item[{\em NMSG\_\-NOSEMCRE}]Unable to create sync. semaphore (VxWorks) \item[{\em NMSG\_\-xxx}]Various connection errors. \end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_760bb4dc4613df085bb7fd2f3d3ed093}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgConnectAsy@{nmsgConnectAsy}}
\index{nmsgConnectAsy@{nmsgConnectAsy}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgConnectAsy (void $\ast$$\ast$ {\em hndl}, const char $\ast$ {\em node}, int {\em port}, int {\em prio}, {\bf nmsgConnCB\_\-t} {\em connRtn}, {\bf nmsgDiscCB\_\-t} {\em discRtn}, void $\ast$ {\em uParm})}}
\label{nmsgLib_8c_760bb4dc4613df085bb7fd2f3d3ed093}


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 prio}]The priority of the connection task, where applicable. If 0, the default value (100) is used.\item[{\em connRtn}]The address of a routine to be called when the connection has been made.\item[{\em discRtn}]The address of a routine to be called when the connection is broken.\item[{\em uParm}]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 NMSG\_\-SUCCESS}]The connection was established successfully. \item[{\em NMSG\_\-NOMEMORY}]Insuffucuent memory available. \item[{\em NMSG\_\-UNKNHOST}]Host is unknown. \item[{\em NMSG\_\-NOSEMCRE}]Unable to create sync. semaphore (VxWorks) \item[{\em NMSG\_\-NOTASKCR}]Unable to spawn connection task. \end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_fe1bfca2cf3723a010fcb51e8df9012a}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgErrorMsg@{nmsgErrorMsg}}
\index{nmsgErrorMsg@{nmsgErrorMsg}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ nmsgErrorMsg (int {\em status})}}
\label{nmsgLib_8c_fe1bfca2cf3723a010fcb51e8df9012a}


Obtain the text of an error message. 

This routine returns a pointer to the message corresponding to a given NMSG status code.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em status}]The NMSG status code.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The address of the corresponding message text. \end{Desc}
\hypertarget{nmsgLib_8c_ac6d5bd6e40a2b55f09e57d4b13bc63a}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgErrorReport@{nmsgErrorReport}}
\index{nmsgErrorReport@{nmsgErrorReport}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void nmsgErrorReport (int {\em status}, const char $\ast$ {\em func})}}
\label{nmsgLib_8c_ac6d5bd6e40a2b55f09e57d4b13bc63a}


Display an error message. 

This routine outputs to stderr the message corresponding to a given NMSG status code.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em status}]The NMSG status code.\item[{\em func}]The function name to be displayed at the start of the message. \end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_55b2221322b47b41f9404c23fe59fcaa}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgListen@{nmsgListen}}
\index{nmsgListen@{nmsgListen}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgListen (void $\ast$$\ast$ {\em hndl}, int {\em port}, int {\em maxConn}, int {\em maxData}, int {\em prio}, {\bf nmsgConnCB\_\-t} {\em connRtn}, {\bf nmsgDiscCB\_\-t} {\em discRtn}, {\bf nmsgRcveCB\_\-t} {\em rcveRtn}, void $\ast$ {\em uParm})}}
\label{nmsgLib_8c_55b2221322b47b41f9404c23fe59fcaa}


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 maxConn}]The maximum number of concurrent connections that the server will allow.\item[{\em maxData}]The maximum number of data bytes that can be transferred in a single message.\item[{\em prio}]The priority of the listener (server) and receiver tasks, where applicable. If 0, the default value (100) is used.\item[{\em connRtn}]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 discRtn}]The address of a routine to be called when a connection is broken.\item[{\em rcveRtn}]The address of a routine to be called whenever a message is received.\item[{\em uParm}]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 NMSG\_\-SUCCESS}]The connection was established successfully. \item[{\em NMSG\_\-NOMEMORY}]Insuffucuent memory available. \item[{\em NMSG\_\-NOTASKCR}]Unable to spawn listener task. \item[{\em NMSG\_\-xxx}]Various system errors. \end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_f38393f16a9ad082e681ef440cddbe46}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgRemoteIP@{nmsgRemoteIP}}
\index{nmsgRemoteIP@{nmsgRemoteIP}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgRemoteIP (void $\ast$ {\em hndl}, int $\ast$ {\em ip})}}
\label{nmsgLib_8c_f38393f16a9ad082e681ef440cddbe46}


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.\item[{\em ip}]The addressof an integer to receive the IP address.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em NMSG\_\-SUCCESS}]Success. \item[{\em NMSG\_\-INVHNDL}]Invalid network handle. \end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_c02e377443f8404d36f8beed75a2e622}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgSend@{nmsgSend}}
\index{nmsgSend@{nmsgSend}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgSend (void $\ast$ {\em hndl}, {\bf nmsgBuff\_\-t} $\ast$ {\em msg})}}
\label{nmsgLib_8c_c02e377443f8404d36f8beed75a2e622}


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 nmsgBuff\_\-t structure type.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em NMSG\_\-SUCCESS}]Success. \item[{\em NMSG\_\-INVHNDL}]Invalid network handle. \item[{\em NMSG\_\-NOTCONN}]Not connected to server. \item[{\em NMSG\_\-INVSEMA}]Invalid semaphore. \item[{\em NMSG\_\-DISCONN}]Server connection was broken. \end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_f66406f1031d4de9f4125241f069b3e5}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgSendW@{nmsgSendW}}
\index{nmsgSendW@{nmsgSendW}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgSendW (void $\ast$ {\em hndl}, {\bf nmsgBuff\_\-t} $\ast$ {\em msg}, {\bf nmsgBuff\_\-t} $\ast$$\ast$ {\em replyP}, {\bf nmsgBuff\_\-t} $\ast$ {\em reply}, int {\em maxData})}}
\label{nmsgLib_8c_f66406f1031d4de9f4125241f069b3e5}


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 nmsgBuff\_\-t structure type.\item[{\em replyP}]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 maxData}]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 NMSG\_\-SUCCESS}]Success. \item[{\em NMSG\_\-INVHNDL}]Invalid network handle. \item[{\em NMSG\_\-NOTCONN}]Not connected to server. \item[{\em NMSG\_\-INVSEMA}]Invalid semaphore. \item[{\em NMSG\_\-DISCONN}]Server connection was broken. \end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_a96f2724ad6d35da14aad7666cc4d68c}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgStats@{nmsgStats}}
\index{nmsgStats@{nmsgStats}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgStats (void $\ast$ {\em hndl}, {\bf nmsgStats\_\-t} $\ast$ {\em stats})}}
\label{nmsgLib_8c_a96f2724ad6d35da14aad7666cc4d68c}


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 NMSG\_\-SUCCESS}]Success. \item[{\em NMSG\_\-INVHNDL}]Invalid network handle. \end{description}
\end{Desc}
\hypertarget{nmsgLib_8c_d12b00b6a96b50f3c79d88b99917f333}{
\index{nmsgLib.c@{nmsgLib.c}!nmsgWait@{nmsgWait}}
\index{nmsgWait@{nmsgWait}!nmsgLib.c@{nmsgLib.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int nmsgWait (void $\ast$ {\em hndl}, {\bf nmsgBuff\_\-t} $\ast$$\ast$ {\em replyP}, {\bf nmsgBuff\_\-t} $\ast$ {\em reply}, int {\em maxData})}}
\label{nmsgLib_8c_d12b00b6a96b50f3c79d88b99917f333}


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 replyP}]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 maxData}]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 NMSG\_\-SUCCESS}]Success. \item[{\em NMSG\_\-INVHNDL}]Invalid network handle. \item[{\em NMSG\_\-NOTCONN}]Not connected to server. \item[{\em NMSG\_\-INVSEMA}]Invalid semaphore. \item[{\em NMSG\_\-DISCONN}]Server connection was broken. \end{description}
\end{Desc}