---

GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > NMSG / V3-1-0

Constituent: nmsg     Tag: i845e

---

         

---

nmsgLib.h File Reference

Definitions for the network message routines. More...

This graph shows which files directly or indirectly include this file:

Data Structures
struct	nmsgHead_s
	Network message header. More...
struct	nmsgBuff_s
	Prototype message buffer. More...
struct	nmsgStats_s
	Network statistics block. More...
Typedefs
typedef nmsgHead_s	nmsgHead_t
	Network message header.
typedef nmsgBuff_s	nmsgBuff_t
	Prototype message buffer.
typedef nmsgStats_s	nmsgStats_t
	Network statistics block.
typedef int	nmsgConnCB_t (void *hndl, void **uParm)
	Connect callback routine.
typedef int	nmsgDiscCB_t (void *hndl, void **uParm)
	Disconnect callback routine.
typedef int	nmsgRcveCB_t (void *hndl, void **uParm, nmsgBuff_t *msg, char **dataP)
	Receive message callback routine.
Enumerations
enum	{ NMSG_MAGIC = 0x6e4d7347 }
	Magic word value definition. More...
Functions
int	nmsgConnect (void **hndl, char *node, int port)
	Connect to a message server.
int	nmsgConnectAsy (void **hndl, char *node, int port, nmsgConnCB_t connRtn, nmsgDiscCB_t discRtn, void *uParm)
	Connect asynchronously (robustly) to a message server.
int	nmsgListen (void **hndl, int port, int maxConn, int maxData, nmsgConnCB_t connRtn, nmsgDiscCB_t discRtn, nmsgRcveCB_t rcveRtn, void *uParm)
	Establish a message server.
int	nmsgClose (void *hndl, int force)
	Terminate a message client or server.
int	nmsgSendW (void *hndl, nmsgBuff_t *msg, nmsgBuff_t **replyP, nmsgBuff_t *reply, int maxData)
	Send a message and receive reply.
int	nmsgSend (void *hndl, nmsgBuff_t *msg)
	Send a message and return immediately.
int	nmsgWait (void *hndl, nmsgBuff_t **replyP, nmsgBuff_t *reply, int maxData)
	Wait for a reply to a sent message.
int	nmsgRemoteIP (void *hndl)
	Get the IP address of the remote end.
int	nmsgStats (void *hndl, nmsgStats_t *stats)
	Get connection statistics.
int	nmsgCheck (void *hndl)
	Check a network connection handle.

---

Detailed Description

Definitions for the network message routines.

Author:

Owen H Saxton

Id

nmsgLib.h,v 1.7 2007/08/30 21:12:01 saxton Exp

---

Typedef Documentation

typedef int nmsgConnCB_t(void *hndl, void **uParm)

Connect callback routine. This routine, if supplied to the listen or asynchronous connection routine, is called whenever a network connection is established. Parameters: hndl  The handle for the network connection. uParm  The user parameter supplied in the call to the listen or connection routine. Return values: 0  Accept the connection. -1  Reject the connection (for listen callback only).

typedef int nmsgDiscCB_t(void *hndl, void **uParm)

Disconnect callback routine. This routine, if supplied to the listen or asynchronous connection routine, is called whenever the network connection is broken. Parameters: hndl  The handle for the network connection. uParm  The user parameter supplied in the call to the listen or connection routine. Returns: The return value is ignored.

typedef int nmsgRcveCB_t(void *hndl, void **uParm, nmsgBuff_t *msg, char **dataP)

Receive message callback routine. This routine is called whenever a message is received on the server (listener) side of a network connection. It processes the message and generates a reply. Normally the whole reply is placed in the area occupied by the incoming message, and can contain data up to the maximum length established in the original listen call. However, the data portion of the reply may alternatively be supplied in a piece of allocated memory and has no restriction on its size in this case. Parameters: hndl  The handle for the network connection. uParm  The user parameter supplied in the call to the listen routine. msg  The address of the received message. dataP  The address of a pointer to optionally receive the address of an alternate data area. This area must have been allocated via a call to malloc(). Returns: The return value is ignored.

---

Enumeration Type Documentation

anonymous enum

Magic word value definition. Enumerator: NMSG_MAGIC  "nMsG"

---

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: 0  Success. -1  An error occurred.

int nmsgConnect (  void **  hndl, 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: 0  The connection was established successfully. -1  An error occurred.

int nmsgConnectAsy (  void **  hndl, char *  node, int  port, 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. 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: 0  The connection process was started successfully. -1  An error occurred.

int nmsgListen (  void **  hndl, int  port, int  maxConn, int  maxData, 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. 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: 0  The message server was started successfully. -1  An error occurred.

int nmsgRemoteIP (  void *  hndl  )

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. Returns: The IP address of the remote end of the connection, or -1 if the handle is invalid.

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: 0  Success. -1  An error occurred.

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: 0  Success. -1  An error occurred.

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: 0  Success. -1  The handle is invalid.

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: 0  Success. -1  An error occurred.

---