iosubs.c File Reference

AzCam client API, server I/O utilities. More...

#include "azcam.h"

Functions
int	OpenAzCam (azcam_t *cam, char *reply)
	Open a TCP socket connection to an AzCamServer.
void	CloseAzCam (azcam_t *cam)
	Terminate an AzCam client session and close the server socket.
int	WriteAzCam (azcam_t *cam, char *cmdstr)
	Write data to an AzCam server TCP socket.
int	ReadAzCam (azcam_t *cam, char *msgstr)
	Read data from an AzCam server TCP socket.
int	AzCamCommand (azcam_t *cam, char *cmdstr, char *reply)
	Send a command to the AzCam server and await a reply.

---

Detailed Description

AzCam client API, server I/O utilities.

A set of basic TCP socket I/O routines that define the common communications layer for the AzCam client API.

Author:

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

Date:

2005 May 3

---

Function Documentation

int OpenAzCam (  azcam_t *  cam, char *  reply )

Open a TCP socket connection to an AzCamServer. Parameters: cam  pointer to an azcam struct with the AzCam server parameters reply  string to carry any messages from the open process Returns: File descriptor of the open comm port connection, or -1 if an error, with any error message text in reply. Performs the necessary initialization functions to open a TCP socket connection to an AzCam server. To use, you must fill in the relevant data members of the azcam struct. The cam->Host and cam->Port members are used to define the server TCP address. For socket communications we use INET streams (SOCK_STREAM) with a persistent client connection. See also: CloseAzCam()

void CloseAzCam (  azcam_t *  cam  )

Terminate an AzCam client session and close the server socket. Parameters: cam  pointer to an azcam struct with the AzCam server parameters (see OpenAzCam()) Sends the "CloseConnection" command to the AzCam server and closes the client TCP socket. See also: OpenAzCam().

int WriteAzCam (  azcam_t *  cam, char *  cmdstr )

Write data to an AzCam server TCP socket. Parameters: cam  pointer to an azcam struct with the AzCam server parameters cmdstr  message string to write Returns: Number of bytes written if successful, 0 or -1 if unsuccessful. Writes the message string provided to the AzCam server described by the cam struct. An AzCam client session must have been previously initiated using the OpenAzCam() function. On errors, it returns an error message in cmdstr. See also: ReadAzCam()

int ReadAzCam (  azcam_t *  cam, char *  msgstr )

Read data from an AzCam server TCP socket. Parameters: cam  Pointer to an azcam struct with the AzCam server parameters msgstr  Message string to carry the input string Returns: The number of characters read, or <0 if an error. -1 on error or timeout, with msgstr containing the error message text. Uses select() to read data from the specified comm port with the timeout interval specified. Note that because TCP sockets are streams rather than line-buffered, the data can arive in bursts depending on the system state and the degree of stream synchronization. As such we read in chunks of data w/o blocking until we have read everything from the port, which means looking for the \r (ASCII 13 = Ctrl+M) or \n terminator. This makes the logic tricky, but robust against most comm glitches. Use of a timeout allows us to break out of cases where the message is unterminated because of a comm fault, not because of the usual stream buffering/sync issues. Note: If select() is interrupted by Ctrl+C, it returns an error message in the reply string.

int AzCamCommand (  azcam_t *  cam, char *  cmdstr, char *  reply )

Send a command to the AzCam server and await a reply. Parameters: cam  pointer to an azcam struct with the AzCam server parameters cmdstr  command to send reply  string returned by the AzCam server Returns: Number of bytes written if successful, 0 or -1 if unsuccessful. Sends a command to the AzCam server and waits for a reply up to a specified timeout interval (defined by #azcam::timeout). On reply, the message is parsed into components. A successful command receives a reply prefixed by "OK" followed (most times) by a message string with information (e.g., the parameters requested). Errors are prefixed by "ERROR", followed by error message text. This routine does no processing of the return reply, but instead packages it as a string (with the OK/ERROR tag removed) for further handling by the calling routine. See also: WriteAzCam(), ReadAzCam()

---