isissocket.c File Reference

ISIS client socket utilties. More...

#include "isisclient.h"

Functions
int	InitISISServer (isisclient_t *client)
	Initialize the ISIS server address information database.
int	OpenClientSocket (isisclient_t *client)
	Open an ISIS client socket for this client application.
int	ReadClientSocket (isisclient_t *client, char *msgstr)
	Read a message waiting on the ISIS client socket.
int	SendToISISServer (isisclient_t *client, char *msgstr)
	Send a message to the active ISIS server.
int	ReplyToRemHost (isisclient_t *client, char *msgstr)
	Reply to a remote host that sent us a previous message.
void	CloseClientSocket (isisclient_t *client)
	Close the ISIS client socket.

---

Detailed Description

ISIS client socket utilties.

ISIS clients and servers use Unix Datagram Protocol (UDP) sockets for interprocess communications. This is a set of simple functions for using UDP sockets with and ISIS client application. They encapsulate a number of useful basic functions for opening, closing, reading, and sending datagrams via sockets, relieving writers of ISIS client applications from the pain of getting all the arcane socket(), bind(), etc. calls right.

To make communications with a fixed ISIS server more efficient, we store the server's socket address database in a global #ISISserver sockaddr_in struct created by a call to InitISISServer(). This way we do not have to pay the overhead of resolving the hostname (e.g., by querying a DNS server or translating an IP number) each time we send a datagram to an ISIS server.

Similarly, we also build the #ISISclient global sockaddr_in struct when we open a client application's socket (OpenClientSocket()).

Author:

R. Pogge, OSU Astronomy Dept. (pogge@astronomy.ohio-state.edu)

Date:

2003 September 10

Overhauled 2004 July 22

---

Function Documentation

int InitISISServer (  isisclient_t *  client  )

Initialize the ISIS server address information database. Parameters: client  pointer to an isis_client struct Returns: 0 if successful, -1 if cannot resolve the server hostname Uses the information in client->isisHost and client->isisPort to setup the network socket communications database for an ISIS server. To communicate with an active ISIS server, a client application needs to build a socket address database (sockaddr_in struct) with the correct host addressing information for the ISIS server. This information is stored in the isisAddr, a sockaddr_in struct that is a member of the isis_client struct. This routine handles host name resolution and builds the database. We do this once so that we can store all data resulting from DNS lookups, so we don't have to rebuild this info every time (saving time). See also: SendToISISServer()

int OpenClientSocket (  isisclient_t *  client  )

Open an ISIS client socket for this client application. Parameters: client  pointer to an isisclient struct Returns: 0 if success, -1 if an error. Open a UDP (datagram) network socket and bind it to a specific port on localhost for subsequent communications with an active ISIS server. Puts the file descriptor to the open socket in the #FD member of the client struct. ISIS communications uses connectionless datagram sockets. Once the client socket is opened and bound to its port, the global #ISISclient sockaddr_in struct is created with the socket address database. This way we do not need to regenerate the database each time we read the socket. If port=0 (deprecated), it assigns the client the next free port. Technically this is allowed, and the standard ISIS server will know how to route messages to this client, but if the client is being run in a standalone mode, it will be difficult for the remote application to know which port the client's socket is bound to. See also: CloseClientSocket()

int ReadClientSocket (  isisclient_t *  client, char *  msgstr )

Read a message waiting on the ISIS client socket. Parameters: client  pointer to an isisclient struct msgstr  Message string to load, size <= ISIS_MSGSIZE Returns: Number of bytes read if successful, -1 if an error. Reads pending input on the client socket into msgstr. This routine does no message format validation, and assumes that msgstr is a well-formed and properly terminated IMPv2 message string. The hostname and port number of the sending host are extracted and put into the hostname and port variables. This allows the calling application to craft replies to a remote host and send them back directly if the application is a "standalone" client. If instead the application is an ISIS client, it should send any replies back to the ISIS server (see InitISISServer() and SendToISISServer() functions). hostname is returned as an unresolved IP address. See also: SendToISISServer(), ReplyToRemHost()

int SendToISISServer (  isisclient_t *  client, char *  msgstr )

Send a message to the active ISIS server. Parameters: client  pointer to an isisclient struct msgstr  message string to transmit, size <= ISIS_MSGSIZE Returns: Number of bytes transmitted if successful, 0 if no socket has been opened or attempting to send a zero-length string, -1 if an error occurred. Transmits "msgstr" to the ISIS server via the ISIS client socket. This routine does no message format validation, and assumes that msgstr is a well-formed and properly terminated IMPv2 protocol message string (see ISISMessage()). The ISIS server address database must have been initialized by calling InitISISServer(). The ISISserver sockaddr_in struct is defined in global scope in the isissocket.h header file. If sending a message to an ISIS node other than the ISIS server proper, use the ReplyToRemHost() function. See also: ReplyToRemHost()

int ReplyToRemHost (  isisclient_t *  client, char *  msgstr )

Reply to a remote host that sent us a previous message. Parameters: client  Pointer to an isisclient struct msgstr  Message string to transmit, size<ISIS_MSGSIZE Returns: Number of bytes sent if successful, 0 if no socket has been opened or attempting to send a zero-length string, -1 if an error occurred. Transmits "msgstr" to the last remote host (client->remHost:remPort) that contacted the application. This routine presumes that the receiving host knows what to make of an ISIS-format message string (e.g., generated by ISISMessage()). It makes no attempt to validate the contents of msgstr, assuming that was done upstream. If sending a message to the ISIS server proper, use the SendToISISServer() function. See also: SendToISISServer()

void CloseClientSocket (  isisclient_t *  client  )

Close the ISIS client socket. Parameters: client  Pointer to an isisclient struct Closes the ISIS client socket opened with OpenClientSocket(). While currently very simple, in the future it could perform other teardown tasks as required. See also: OpenClientSocket()

---