isisclient.h File Reference

ISIS client API header file. More...

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <ctype.h>
#include <string.h>
#include <time.h>
#include <math.h>
#include <errno.h>
#include <termios.h>
#include <fcntl.h>
#include <sys/time.h>
#include <sys/times.h>
#include <sys/file.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <arpa/inet.h>
#include <netinet/in.h>
#include <sys/socket.h>
#include <netdb.h>

Go to the source code of this file.

Data Structures
struct	client_info
	ISIS client runtime configuration table. More...
Defines
#define	ISIS_MSGSIZE   2048
	Maximum size of an IMPv2 message.
#define	ISIS_NODESIZE   9
	Maximum size of an IMPv2 host node name.
#define	LONG_STR_SIZE   4096
	Length of a generic long string (longer than ISIS_MSGSIZE).
#define	MED_STR_SIZE   256
	Length of a generic medium-sized string.
#define	BIG_STR_SIZE   512
	Length of a generic "big" string, bigger than medium, smaller than long.
#define	SHORT_STR_SIZE   32
	Length of a generic short string.
Typedefs
typedef client_info	isisclient_t
	ISIS client runtime configuration table.
typedef enum IMPv2_MsgType	MsgType
Enumerations
enum	IMPv2_MsgType {   REQ, EXEC, STATUS, DONE,   ERROR, WARNING, FATAL }
Functions
char *	ISISMessage (char *fromID, char *destID, MsgType msgtype, char *msgbody)
	Create an IMPv2 message string.
int	SplitMessage (char *msgstr, char *fromID, char *destID, MsgType *msgtype, char *msgbody)
	Split a raw IMPv2 message string into components.
int	InitISISServer (isisclient_t *)
	Initialize the ISIS server address information database.
int	OpenClientSocket (isisclient_t *)
	Open an ISIS client socket for this client application.
int	ReadClientSocket (isisclient_t *, char *)
	Read a message waiting on the ISIS client socket.
int	SendToISISServer (isisclient_t *, char *)
	Send a message to the active ISIS server.
int	ReplyToRemHost (isisclient_t *, char *)
	Reply to a remote host that sent us a previous message.
void	CloseClientSocket (isisclient_t *)
	Close the ISIS client socket.
int	OpenSerialPort (char *)
	Open a serial port.
void	CloseSerialPort (int)
	Close an open serial port.
int	SetSerialPort (int, int, int, int, int)
	Set the serial port attributes.
int	WriteSerialPort (int, char *)
	Write a message string to a serial port.
int	ReadSerialPort (int, char *)
	Read data from a serial port.
void	FlushSerialPort (int, int)
	Read data from a serial port.
void	LeftStr (char *substr, char *str, int nchar)
	Extract the n left-most characters from a given string.
void	RightStr (char *substr, char *str, int nchar)
	Extract the n right-most characters from a given string.
void	MidStr (char *substr, char *str, int start, int nchar)
	Extract n characters starting in the middle of a string.
void	SubStr (char *substr, char *str, int first, int last)
	Extracts a substring from inside a larger string.
void	UpperCase (char *str)
	Convert all characters in a string up uppercase.
void	GetArg (char *cmdstr, int argnum, char *argstr)
	Extract the n-th argument from a command string with arguments separated by spaces.
char *	UTCDate (void)
	Return the UTC date in ISO8601 format.
char *	UTCTime (void)
	Return the UTC Time in ISO8601 format.
char *	ISODate (void)
	Return the UTC date and time in ISO8601 format.
char *	UTCDateTag (void)
	Create a CCYYMMDD date tag string.
char *	GetFineTime (void)
	Return UTC time with microsecond precision.
double	SysTimestamp (void)
	Return elapsed time since UTC 1970 Jan 1 with microsecond precision.
int	MilliSleep (long)
	Pause execution for a certain number of msec.

---

Detailed Description

ISIS client API header file.

This is the main header file for the ISIS client applications library (libisis.a). Client applications only need to include isisclient.h, which encapsulates all of the various bits a client needs to become a basic ISIS client application.

The main client library is divided into 4 modules:

• isismessage.c IMPv2 message handling routines
• isissocket.c ISIS UDP socket I/O handling routines
• isisserial.c Serial port I/O handling routines
• isisutils.c Handy client application utilties (string and time handling)

---

Define Documentation

#define ISIS_MSGSIZE   2048

Maximum size of an IMPv2 message.

#define ISIS_NODESIZE   9

Maximum size of an IMPv2 host node name.

#define LONG_STR_SIZE   4096

Length of a generic long string (longer than ISIS_MSGSIZE).

#define MED_STR_SIZE   256

Length of a generic medium-sized string.

#define BIG_STR_SIZE   512

Length of a generic "big" string, bigger than medium, smaller than long.

#define SHORT_STR_SIZE   32

Length of a generic short string.

---

Typedef Documentation

typedef struct client_info isisclient_t

ISIS client runtime configuration table. Contains the runtime parameters common to all ISIS client applications. Defines the isisclient_t typedef to be used by client applications.

typedef enum IMPv2_MsgType MsgType

MsgType is a global typedef used by isismessage utilities and any user routines must access IMPv2 message-type codes.

---

Enumeration Type Documentation

enum IMPv2_MsgType

This enum is used by ISIS client routines to specify the IMPv2 message type. Enumeration values: REQ  Command Request. EXEC  Executive Command Request. STATUS  Informational Status message. DONE  Command completion acknowledgment. ERROR  Error message. WARNING  Warning message. FATAL  Fatal error condition message.

---

Function Documentation

char* ISISMessage (  char *  fromID, char *  destID, MsgType  msgtype, char *  msgbody )

Create an IMPv2 message string. Parameters: fromID  ISIS node name of the client application destID  ISIS node name of the intended recipient msgtype  IMPv2 message type code (see IMPv2_MsgType) msgbody  Body of the message to create Returns: a character pointer to the message string. Creates a message string in the proper IMPv2 format with the correct termination (\r = ASCII 13). See also: SplitMessage()

int SplitMessage (  char *  msgstr, char *  fromID, char *  destID, MsgType *  msgtype, char *  msgbody )

Split a raw IMPv2 message string into components. Parameters: msgstr  Raw IMPv2 message string fromID  Address of the sending ISIS node destID  Address of the destination ISIS node msgtype  IMPv2 message type code (see IMPv2_MsgType) msgbody  Body of the message Returns: 0 if message is a valid message (proper format), -1 if invalid This function decomposes a raw message string into its component parts. If the message does not have a valid format, it returns -1. Note that the validation stages do not include validating the message terminator (\r = ASCII 13). Instead we just assume proper termination and strip off the terminator character if present, but say nothing if absent. See also: ISISMessage()

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()

int OpenSerialPort (  char *  ttydev  )

Open a serial port. Parameters: ttydev  Name of the port (e.g., /dev/ttya) Returns: File descriptor of the open serial port or -1 if failed Opens the named serial port for unblocking read/write (the only mode we support), and returns the file descriptor of the open port. All error messages are reported internally. This function only opens the port; port attributes (speed, parity, etc.) need to be set subsequently using the SetSerialPort() call

void CloseSerialPort (  int  ttyFD  )

Close an open serial port. Parameters: ttyFD  file descriptor of an open serial port (see OpenSerialPort()) Closes an open serial port. Used as a simple wrapper for the close() function to provide a logical functional opposite to OpenSerialPort().

int SetSerialPort (  int  ttyFD, int  speed, int  databits, int  stopbits, int  parity )

Set the serial port attributes. Parameters: ttyFD  File descriptor of the open port (see OpenSerialPort()) speed  Port speed in baud, one of (1200,2400,4800,9600,19200,38400) databits  Number of data bits (5, 6, 7, or 8) stopbits  Number of stop bits (1 or 2) parity  Port parity, 0 = noparity, 1 = enable parity Returns: 0 if successful, -1 if an error. Sets the attributes of the open serial port: speed, data bits (character size mask), stop bits (1 or 2), and partiy (no parity, or parity generation on output/checking on input). The normal mode for most tty ports we use in the data-taking system are set to 9600 baud, 8 data bits, 1 stop bit, no parity corresponding to speed=9600, databits=8, stopbits=2, parity=0. The port must have already been opened using OpenSerialPort(). See also: OpenSerialPort()

int WriteSerialPort (  int  ttyFD, char *  msgstr )

Write a message string to a serial port. Parameters: ttyFD  file descriptor of an open serial port (see OpenSerialPort()) msgstr  message string to write Returns: Number of bytes written if successful, 0 or -1 if unsuccessful. Writes the message string provided to the serial port given by ttyFD. This port must have been previously opened and setup using the OpenSerialPort() and SetSeriaPort() functions. See also: ReadSerialPort()

int ReadSerialPort (  int  ttyFD, char *  msgstr )

Read data from a serial port. Parameters: ttyFD  file descriptor of an open serial port (see OpenSerialPort()) msgstr  message string to carry the input string Returns: Number of bytes read if successful, 0 or -1 if unsuccessful. Reads characters from the serial port ttyFD and loads them into msgstr. This port must have been previously opened and setup using the OpenSerialPort() and SetSeriaPort() functions. This function is most often used in the context of a select() loop to watch for activity on one or more open serial ports, though it may be used generally as required. See also: WriteSerialPort()

void FlushSerialPort (  int  ttyFD, int  ntimes )

Read data from a serial port. Parameters: ttyFD  file descriptor of an open serial port (see OpenSerialPort()) ntimes  number of times to read the port for flushing Reads the serial port ntimes to attempt to flush any extraneous port junk. This port must have been previously opened and setup using the OpenSerialPort() and SetSeriaPort() functions. Assumes that the buffer size is at least the default BUFSIZ defined in stdio.h Whether or not this is a good idea remains to be seen.

void LeftStr (  char *  substr, char *  str, int  nchar )

Extract the n left-most characters from a given string. Parameters: substr  Substring to extract str  Original string nchar  Number of characters to extract

void RightStr (  char *  substr, char *  str, int  nchar )

Extract the n right-most characters from a given string. Parameters: substr  Substring to extract str  Original string nchar  Number of characters to extract

void MidStr (  char *  substr, char *  str, int  start, int  nchar )

Extract n characters starting in the middle of a string. Parameters: substr  Substring to extract str  Original string start  Starting character in str nchar  Number of characters to extract See also: SubStr()

void SubStr (  char *  substr, char *  str, int  first, int  last )

Extracts a substring from inside a larger string. Parameters: substr  Substring to extract str  Original string first  First character in str to extract last  Last character in str to extract See also: MidStr()

void UpperCase (  char *  str  )

Convert all characters in a string up uppercase. Parameters: str  String to be converted to uppercase

void GetArg (  char *  cmdstr, int  argnum, char *  argstr )

Extract the n-th argument from a command string with arguments separated by spaces. Parameters: cmdstr  Command string with space-separated arguments argnum  Number of the argument to extract (1..n) argstr  Argument string to return Returns the n-th argument in a command string that contains a series of command-line arguments separated by spaces. Provides a very simple command parsing capability. The command looks like cmd arg1 arg2 .. argN With the command verb itself being considerd argument "0". Returns a null string in argstr if argnum is out of range.

char* UTCDate (  void   )

Return the UTC date in ISO8601 format. Reads the system clock and returns the UTC date in ISO8601-compliant CCYY-MM-DD format, where CCYY is the year (century and year), MM is the month number (01..12), and DD is the day of the month (01..28/29/30/31). See also: UTCDateTag(), ISODate()

char* UTCTime (  void   )

Return the UTC Time in ISO8601 format. Reads the system clock and returns the UTC time in ISO8601-compliant time to the nearest second in hh:mm:ss format. See also: GetFineTime(), ISODate()

char* ISODate (  void   )

Return the UTC date and time in ISO8601 format. Reads the system clock and returns the UTC date and time in full ISO8601-compliant date/time format: CCYY-MM-DDThh:mm:ss where: CCYY-MM-DD is the UTC date hh:mm:ss is the UTC time to the nearest second We omit the zone specification described by ISO8601 since this only reads UTC time. See also: UTCDate(), UTCTime(), UTCDateTag()

char* UTCDateTag (  void   )

Create a CCYYMMDD date tag string. Reads the system timeclock and returns the UTC date in CCYYMMDD format. This is a hyphen-free variant on the standard ISO8601 format date specification. See also: UTCDate(), ISODate()

char* GetFineTime (  void   )

Return UTC time with microsecond precision. Reads the system's UTC time clock and returns a pointer to a string with the fine-grained UTC time in hh:mm:ss.ssssss format. Based on gf_time() from Stevens, W.R., 1998, Unix Network Programming, Vol 2, Prentice Hall, Figure 15.6, but I make a string, and extract time to microsec instead of msec. Note: It returns microsecond precision, accuracy is quite another matter... See also: UTCTime(), ISODate()

double SysTimestamp (  void   )

Return elapsed time since UTC 1970 Jan 1 with microsecond precision. Reads the system's time clock and returns a double-precision value with the time in seconds and microseconds since UTC 1970 January 1. The primary use of this function is to create a fine-grained numerical timestamp for the system, but other uses are possible. Note: It returns microsecond precision, accuracy is quite another matter... See also: GetFineTime()

int MilliSleep (  long  msec  )

Pause execution for a certain number of msec. Parameters: msec  - time to sleep in milliseconds Returns: 0 if successful, -1 if there were problems. errno says what is bothering it. Acts as a convenience function for using nanosleep(), the POSIX.1b conformal way of suspending a process for a certain time. nanosleep() is a replacement for the obsolete usleep() when a sleep interval more fine-grained than sleep() is required. sleep() only allows intervals in integer seconds, which is not short enough for some applications. For most of what we do, msec are the appropriate interval, and nanosleep() can be somewhat involved to setup. This function encapsulates the nasty setup for calling nanosleep() as a convenience for users. See "man 2 nanosleep" for details on the nanosleep() function.

---