GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> NMSG / V4-0-2 > nmsg / sun-gcc


Interface   Data Structures   File List   Data Fields   Globals  

nmsgLib.c File Reference

Routines for handling formatted network messages. More...

#include <NMSG/nmsgLib.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>
#include <netinet/in.h>
#include <pthread.h>
#include <errno.h>
#include <string.h>
#include <stdio.h>

Functions

int nmsgCheck (void *hndl)
 Check a network connection handle.
int nmsgClose (void *hndl, int force)
 Terminate a message client or server.
int nmsgConnect (void **hndl, const char *node, int port)
 Connect to a message server.
int nmsgConnectAsy (void **hndl, const char *node, int port, int prio, nmsgConnCB_t connRtn, nmsgDiscCB_t discRtn, void *uParm)
 Connect asynchronously (robustly) to a message server.
const char * nmsgErrorMsg (int status)
 Obtain the text of an error message.
void nmsgErrorReport (int status, const char *func)
 Display an error message.
int nmsgListen (void **hndl, int port, int maxConn, int maxData, int prio, nmsgConnCB_t connRtn, nmsgDiscCB_t discRtn, nmsgRcveCB_t rcveRtn, void *uParm)
 Establish a message server.
int nmsgRemoteIP (void *hndl, int *ip)
 Get the IP address of the remote end.
int nmsgSend (void *hndl, nmsgBuff_t *msg)
 Send a message and return immediately.
int nmsgSendW (void *hndl, nmsgBuff_t *msg, nmsgBuff_t **replyP, nmsgBuff_t *reply, int maxData)
 Send a message and receive reply.
int nmsgStats (void *hndl, nmsgStats_t *stats)
 Get connection statistics.
int nmsgWait (void *hndl, nmsgBuff_t **replyP, nmsgBuff_t *reply, int maxData)
 Wait for a reply to a sent message.


Detailed Description

Routines for handling formatted network messages.

Author:
Owen H Saxton
Id

Function Documentation

int nmsgCheck ( void *  hndl  ) 

Check a network connection handle.

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

Parameters:
hndl The handle for the connection.
Return values:
1 The handle is valid.
0 The handle is invalid.

int nmsgClose ( void *  hndl,
int  force 
)

Terminate a message client or server.

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

Parameters:
hndl The handle of the connection or server.
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.
Return values:
NMSG_SUCCESS Success.
NMSG_INVHNDL Invalid network handle.

int nmsgConnect ( void **  hndl,
const char *  node,
int  port 
)

Connect to a message server.

This routine establishes a network connection to a message server.

Parameters:
hndl The address of a pointer to receive the identifying handle for the network connection.
node The address of the name of the node containing the message server.
port The port number on which to establish the connection.
Return values:
NMSG_SUCCESS The connection was established successfully.
NMSG_NOMEMORY Insuffucuent memory available.
NMSG_UNKNHOST Host is unknown.
NMSG_NOSEMCRE Unable to create sync. semaphore (VxWorks)
NMSG_xxx Various connection errors.

int nmsgConnectAsy ( void **  hndl,
const char *  node,
int  port,
int  prio,
nmsgConnCB_t  connRtn,
nmsgDiscCB_t  discRtn,
void *  uParm 
)

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.

Parameters:
hndl The address of a pointer to receive the identifying handle for the network connection.
node The address of the name of the node containing the message server.
port The port number on which to establish the connection.
prio The priority of the connection task, where applicable. If 0, the default value (100) is used.
connRtn The address of a routine to be called when the connection has been made.
discRtn The address of a routine to be called when the connection is broken.
uParm A parameter to be passed to the connect and disconnect callback routines.
Return values:
NMSG_SUCCESS The connection was established successfully.
NMSG_NOMEMORY Insuffucuent memory available.
NMSG_UNKNHOST Host is unknown.
NMSG_NOSEMCRE Unable to create sync. semaphore (VxWorks)
NMSG_NOTASKCR Unable to spawn connection task.

const char* nmsgErrorMsg ( int  status  ) 

Obtain the text of an error message.

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

Parameters:
status The NMSG status code.
Returns:
The address of the corresponding message text.

void nmsgErrorReport ( int  status,
const char *  func 
)

Display an error message.

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

Parameters:
status The NMSG status code.
func The function name to be displayed at the start of the message.

int nmsgListen ( void **  hndl,
int  port,
int  maxConn,
int  maxData,
int  prio,
nmsgConnCB_t  connRtn,
nmsgDiscCB_t  discRtn,
nmsgRcveCB_t  rcveRtn,
void *  uParm 
)

Establish a message server.

This routine establishes a network message server (listener).

Parameters:
hndl The address of a pointer to receive the identifying handle for the network listener.
port The port number on which to establish the server.
maxConn The maximum number of concurrent connections that the server will allow.
maxData The maximum number of data bytes that can be transferred in a single message.
prio The priority of the listener (server) and receiver tasks, where applicable. If 0, the default value (100) is used.
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.
discRtn The address of a routine to be called when a connection is broken.
rcveRtn The address of a routine to be called whenever a message is received.
uParm A parameter to be passed to the connect, disconnect and receive callback routines.
Return values:
NMSG_SUCCESS The connection was established successfully.
NMSG_NOMEMORY Insuffucuent memory available.
NMSG_NOTASKCR Unable to spawn listener task.
NMSG_xxx Various system errors.

int nmsgRemoteIP ( void *  hndl,
int *  ip 
)

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.

Parameters:
hndl The handle for the connection.
ip The addressof an integer to receive the IP address.
Return values:
NMSG_SUCCESS Success.
NMSG_INVHNDL Invalid network handle.

int nmsgSend ( void *  hndl,
nmsgBuff_t msg 
)

Send a message and return immediately.

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

Parameters:
hndl The handle for the connection.
msg The address of message to be sent. It must be formatted using the nmsgBuff_t structure type.
Return values:
NMSG_SUCCESS Success.
NMSG_INVHNDL Invalid network handle.
NMSG_NOTCONN Not connected to server.
NMSG_INVSEMA Invalid semaphore.
NMSG_DISCONN Server connection was broken.

int nmsgSendW ( void *  hndl,
nmsgBuff_t msg,
nmsgBuff_t **  replyP,
nmsgBuff_t reply,
int  maxData 
)

Send a message and receive reply.

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

Parameters:
hndl The handle for the connection.
msg The address of message to be sent. It must be formatted using the nmsgBuff_t structure type.
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.
reply The address of an area to receive the reply to the message, or NULL if no area is to be used.
maxData The maximum number of data bytes that can be put into the supplied reply area.
Return values:
NMSG_SUCCESS Success.
NMSG_INVHNDL Invalid network handle.
NMSG_NOTCONN Not connected to server.
NMSG_INVSEMA Invalid semaphore.
NMSG_DISCONN Server connection was broken.

int nmsgStats ( void *  hndl,
nmsgStats_t stats 
)

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.

Parameters:
hndl The handle for the connection.
stats The address of an area to receive the statistics block.
Return values:
NMSG_SUCCESS Success.
NMSG_INVHNDL Invalid network handle.

int nmsgWait ( void *  hndl,
nmsgBuff_t **  replyP,
nmsgBuff_t reply,
int  maxData 
)

Wait for a reply to a sent message.

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

Parameters:
hndl The handle for the connection.
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.
reply The address of an area to receive the reply to the message, or NULL if no area is to be used.
maxData The maximum number of data bytes that can be put into the supplied reply area.
Return values:
NMSG_SUCCESS Success.
NMSG_INVHNDL Invalid network handle.
NMSG_NOTCONN Not connected to server.
NMSG_INVSEMA Invalid semaphore.
NMSG_DISCONN Server connection was broken.


Generated on Thu Aug 19 14:52:05 2010 by  doxygen 1.5.3