/** \page guiServerProtocol guiServer Interface Protocol \brief Detailed description of the communications protocol used to drive DiFX via the guiServer. \tableofcontents The DiFX GUI controls DiFX using a network connection to the guiServer application running on the DiFX host. Effectively the GUI is only a visual front end - guiServer is where the actual control takes place. This document describes the network connection(s) and communication protocol that act between the DiFX GUI and guiServer - presumably any piece of software could exploit this interface and control DiFX externally. \section protocolConnecting Connecting GuiServer needs to be started on the DiFX "host". The host can be any machine that has access to the DiFX applications (vex2difx, mpifxcorr, etc.). The user that starts guiServer must be able to run these applications. Once start, guiServer maintains an open TCP server socket at a port specifed by: Once a client connection is made on this port a thread is spawned to handle the communications, and the server waits for new connections - all typical TCP stuff. In theory any number of client connections may be made to guiServer. \subsection protocolConnectionProtocol Connection Protocol The top-level connection between guiServer and its client is bi-directional. All communication, whether from client to server or the reverse, follows a fairly trivial "packet" protocol where each instruction, request, data block, whatever, is transmitted as follows:
Packet ID
 Integer (network byte order)
 A unique integer identifying the packet
Data bytes
 Integer (network byte order)
 Number of bytes that follow
Data
 byte data (undefined order)
 Packet content
The Packet ID should be recognized on both sides of the connection - the guiServer software will ignore any packet it does not understand (however it will use the "data bytes" number to completely read through and discard the data). In addition to the top-level connection, guiServer and the GUI can make a number of other connections using this same protocol. What defines the difference between the connections is the list of Packet IDs and what they mean. This "packet" protocol rests on top of the TCP/IP "packet" structure, and should not be confused with it. \section protocolTopLevelPackets Top-Level Packets The following Packet IDs are recognized by client, server, or both at the top-level connection. With each Packet ID is its integer value, whether guiServer and/or the client is expected to recognize and respond to it, and a brief description. Follow the links for each to get more information.
Packet ID
 Int Value
 guiServer
 client
 Description
\ref relayPacket "RELAY_PACKET" 1
 X
 X
 Turn on/off multicast relay, or relay multicast packet to client
\ref relayCommandPacket "RELAY_COMMAND_PACKET" 2
 X
Broadcast XML to DiFX processes using multicast
\ref commandPacket "COMMAND_PACKET" 3
 X
Send a command to guiServer (usually to run a DiFX function)
\ref informationPacket "INFORMATION_PACKET" 4
X
 guiServer information for client
\ref informationPacket "WARNING_PACKET" 5
X
 guiServer warning for client
\ref informationPacket "ERROR_PACKET" 6
X
 guiServer error for client
\ref multicastSettingsPacket "MULTICAST_SETTINGS_PACKET" 7
 X
Change the multicast settings for the guiServer DiFX monitor
\ref guiServerVersion "GUISERVER_VERSION" 8
 X
 X
 Request version information from guiServer or report it to the client
\ref guiServerDifxVersion "GUISERVER_DIFX_VERSION" 9
X
 Report version of DiFX used to build guiServer
\ref availableDifxVersion "AVAILABLE_DIFX_VERSION" 10
X
 Report a version of DiFX software the guiServer can use
\ref difxBase "DIFX_BASE" 11
X
 Base of DiFX software on the host running guiServer
\ref guiServerEnvironment "GUISERVER_ENVIRONMENT" 12
X
 Environment variable accessible to guiServer
\ref difxSetupPath "DIFX_SETUP_PATH" 13
 X
Path to the "execute" script
\ref startDifxMonitor "START_DIFX_MONITOR" 14
 X
Start a guiServer thread to monitor a job
\ref difxRunLabel "DIFX_RUN_LABEL" 15
 X
The "label" of the DiFX version that should be used.
\ref guiServerUser "GUISERVER_USER" 16
X
 User that started guiServer
\subsection relayPacket RELAY_PACKET This is a bi-directional packet type - both guiServer and the client can use it. It is used in the relay of DiFX multicast (UDP) traffic on the DiFX host to the client. If sent to guiServer, the packet data is expected to be a single integer in network byte order, either 1 to turn on, or 0 to turn off multicast relay. If packet relay is on, every multicast message that guiServer sees will be relayed to the client with a RELAY_PACKET, the data being a string containing the multicast message. All DiFX multicast messages are XML, and will have to be parsed by the client to be useful.
\subsection relayCommandPacket RELAY_COMMAND_PACKET Many DiFX processes accept XML instructions over the multicast network (primarily mk5daemon, but I believe there are others). For the most part guiServer replaces the functionality of this system, but there may be commands that it cannot perform. This packet type can be used in those cases. If received by guiServer, the data (an XML string) will be sent as a multicast, to be picked up or ignored by DiFX processes as they see fit. \subsection informationPacket INFORMATION_PACKET, WARNING_PACKET, ERROR_PACKET These packets are generated by guiServer. They contain information, a warning, or an error that guiServer encountered in the form of a string. \subsection multicastSettingsPacket MULTICAST_SETTINGS_PACKET This packet can be used to change the group and port settings for multicast messages that guiServer receives from DiFX. When set properly, guiServer will then be able to collect (and relay to the GUI) broadcast messages from other DiFX processes (such as \ref runMk5daemon "mk5daemon"). There are default values for these items; for the group: For the port:
The packet data is a string, with the group first and the port second, separated by a newline character. When this packet is received, guiServer will change the settings for its multicast monitoring. \section handshakingPackets Initial Handshaking Packets When the GUI makes a connection to guiServer, it requests information about guiServer and its environment. This triggers a series of packets with different Packat IDs from guiServer to the client. It isn't critical that you do this when making a connection, but it can tell you lots of information about how guiServer will run DiFX. \subsection guiServerVersion GUISERVER_VERSION This packet, with zero-length data, is used by the client to request version information from guiServer. It triggers the following packets, so the client needs to be ready to receive them. Once this request is received by guiServer, it will respond using the same Packet ID, but with string data containing the version of guiServer (or "unknown" if it can't be determined). This is a guiServer-specific version - it doesn't match the DiFX version. \subsection guiServerDifxVersion GUISERVER_DIFX_VERSION This packet contains, as a string, the version of DiFX that the guiServer was compiled under. \subsection difxBase DIFX_BASE This packet contains the "base" of the DiFX software on the DiFX host (as a string). This value comes from the environment variable "DIFX_BASE" (as defined on the DiFX host). It can also be set using the "-b" argument when guiServer is started. \subsection guiServerUser GUISERVER_USER This packet contains the user that started guiServer. The value is the result of a \"getlogin()\" function call. \subsection availableDifxVersion AVAILABLE_DIFX_VERSION This packet contains the name of a DiFX version that guiServer has access to. There can be any number of these. The values are found by guiServer through listing all files matching the name: \verbatim[DIFX_BASE]/*/setup_difx.*\endverbatim The names of the extensions of the \"setup_difx.EXTENSION\" files are assumed to be DiFX version names. \subsection guiServerEnvironment GUISERVER_ENVIRONMENT This packet contains an environment variable, and its value, separated by \"=\" in a string. One of these packets is sent by guiServer for each environment variable it has access to. \subsection difxSetupPath DIFX_SETUP_PATH This packet contains the path to an "execution script" that is used by guiServer to run DiFX functions. When guiServer runs a DiFX program (as an example, use vex2difx), it inserts this script in a system command as follows: 
	[DIFX_SETUP_PATH] vex2difx [ARGS]
Note that the string used for the DIFX_SETUP_PATH can be anything you want - as long as it contains some method of executing the commands that follow it. The purpose of the DIFX_SETUP_PATH is to allow guiServer to execute different versions of DiFX. The execution script is used to source the proper setup file for the version (putting in place all of the correct values for environment variables), then execute the command. \subsection startDifxMonitor START_DIFX_MONITOR This packet tells guiServer to start a new thread containing a "DiFX monitor". The packet contains a port number (in string form) for a server port opened by the application sending the START_DIFX_MONITOR packet (e.g. the GUI). The DiFX monitor thread will immediately attempt to make a TCP client connection to the specified port (using the IP address the packet came from). When that is successful, an interactive session is started between the client (the thread) and the server that follows the same "packet protocol" described \ref protocolConnectionProtocol "above", but with a different set of packet IDs and functions:
Packet ID Int Value thread server Description
MESSAGE 0


WARNING
 1


ERROR
 2


INPUT_FILE_PATH
 3


CLOSE_CONNECTION
 4


NUM_BASELINES
 5


NUM_FREQUENCIES
 6


BASELINE
 7


FREQUENCY
 8


NUM_SCANS
 9


SCAN
 10


TELESCOPE_1
 11


TELESCOPE_2
 12


CORRELATION_PRODUCTS
 13


NUM_PHASE_CENTERS
 14


PHASE_CENTER
 15


NUM_PULSAR_BINS
 16


PULSAR_BIN
 17


NUM_POL_PRODUCTS
 18


POL_PRODUCT
 19


NEW_PRODUCT
 20


AUTOCORRELATION
 21


PRODUCT_REQUEST
 22


START_PRODUCT_REQUEST
 23


END_PRODUCT_REQUEST
 24


VISIBILITY_DATA
 25


AMPLITUDE_DATA
 26


PHASE_DATA
 27


LAG_DATA
 28


END_VISIBILITY_BLOCK
 29


JOB_NAME
 30


OBS_CODE
 31


SCAN_IDENTIFIER
 32


SCAN_START_TIME
 33


SCAN_END_TIME
 34


SOURCE
 35


SOURCE_RA
 36


SOURCE_DEC
 37


\subsection difxRunLabel DIFX_RUN_LABEL This packet contains the "label" (as a string) of the DiFX version that should be used when guiServer runs any DiFX function. The label was used to determine which "setup" script to execute as part of any DiFX command. However this functionality has been replaced (and made more flexible) by the \ref difxSetupPath "DIFX_SETUP_PATH" packet, so this packet probably has no effect at this time. \subsection commandPacket COMMAND_PACKET */