Initial commit

1 files changed, 171 insertions, 0 deletions

diff --git a/vendor/voclient/voapps/README.samp b/vendor/voclient/voapps/README.samp
new file mode 100644
index 00000000..326eccb0
--- /dev/null
+++ b/vendor/voclient/voapps/README.samp
@@ -0,0 +1,171 @@
+
+
+VOSAMP -- SAMP cmdline tool
+
+
+  Usage:
+
+	% vosamp [-hvd] [-t to] [-p pattern] [-f file] <cmd> [args ...]
+
+  	where	<cmd>			command to process
+  	     	-h			print help summary
+  	     	-v			verbose output
+  	     	-d			debug output
+
+  	     	-m			handle multiple messages
+  	     	-s <sender>		handly only msgs from <sender>
+
+  	     	-t <to>			send to specified app (or all)
+  	     	-p <pattern>		message pattern:  sync|async|notify
+  	     	-f <file>		send all commands in the file
+
+  Commands:
+
+    snoop 				    print all received messages
+    send <mtype> [<args> ...]		    generalized <mtype> message send
+
+    status 				    print Hub availability
+    list 				    list all registered clients
+    access <appName>			    print <appName> availability
+    handle <mtype>			    wait for <mtype> message
+
+    exec <cmd>			    	    execute a client command
+    setenv  <name> <value>		    set an environment value
+    getenv  <name>			    get an environment value
+    setparam <name> <value>		    set a parameter value
+    getparam <name>			    get a parameter value
+
+    load <url>			    	    load the image/table
+    loadImage <url>			    load the named image
+    loadVOTable <url>			    load the named VOTable
+    loadFITS <url>			    load the named FITS bintable
+    loadSpec <url>			    load the named spectrum
+    loadResource <ivorn>		    load the named VO Resource
+
+    pointAt <ra> <dec>		    	    point at given coords
+    showRow [<url>] [<tblId>] <row>	    highlight specified row
+    selectRows [<url>] [<tblId>] <rows>     select specified rows
+    bibcode <bibcode> 		    	    load the bibcode
+
+
+==============================================================================
+
+
+VOSESSION -- Session manager for inter-desktop messaging
+
+    VOSAMP reads its command either from stdin, a named command file (e.g.
+as from a VOSAMP-shell interpreter), or from a socket created when the proxy
+process is created.  This socket is created on an inet port that may be
+visible to the whole internet, or on a private port restricted by local
+system administrators to trusted clients (e.g. port 8080 if that is a
+general service provided by a site, or the default port 4000 for sites
+willing to open a firewall hole).
+
+    An example sequence of SAMP commands would be something like
+
+	% vosamp listClients
+	% vosamp loadVOTable foo.xml
+
+where the first command establishes a SAMP connection, and the second would
+forward the CLI command to the (already running) proxy client without
+establishing a new-application context.
+
+    In this model, a proxy VOSAMP app reading from an inet socket opens
+the possibility of using this proxy from a remote host that can send a
+command from a trusted machine.  For example,
+
+   On host A:
+	% vosamp start		# start proxy client on host A (140.252.1.86)
+
+   On host B:
+	% vosamp --proxy=140.252.1.86:4000 loadVOTable foo.xml
+
+where the '140.252.1.86' is the machine running the intial VOSAMP task,
+'4000' is the inet port that proxy is reading commands, and the remainder
+of the commandline are args to be passed thru as it they were issued from
+the local host.  Local data (e.g. the 'foo.xml' file) is sent to the remote
+before executing the command, file:// URL's are rewritten so the file
+reference remains valid on the remote machine (http:// URLs are unchanged).
+
+
+SAMP Session Manager:	(In development)
+
+    By using the proxy client, we can send commands to a VOSAMP application
+from a remote machine, but this is not quite the same as federating two (or
+more) desktops in a shared session.  We are also limited by the ability to
+bypass firewalls in order to connect to the proxy client.  The solution then
+is to have a public "session manager" service that serves as an alternate
+input source to the proxy client and will acto to forward message from one
+machine to the others.  For example,
+
+			    +-------------+
+                            | Session Mgr |
+			    +-------------+
+                                   ^
+                                 /   \
+                                /     \
+    +-------------------------+         +-------------------------+
+    |  Topcat  \              |         |               /  Topcat |
+    |            Hub - VOSAMP |         |  VOSAMP - Hub           |
+    |  Aladin  /              |         |               \  IRAF   |
+    +-------------------------+         +-------------------------+
+               Host A                            Host B
+
+Since the session manager is on a public host, the VOSAMP on each machine
+makes an outgoing client connection and sets up that socket to receive
+commands and subscribes to all message types so that SAMP messages received
+on the local machine can be forwarded back to the session manager and then
+on to other machines in the session.  For example, the Aladin on Host A
+broadcasts an image.load.FITS message, the VOSAMP on Host forwards the
+message to the session manager than then passes it on to the VOSAMP on
+Host B for rebroadcast.  In this way the message is seen on both desktops
+transparently.  When local data is being used, this is uploaded to the 
+session manager for storage in a web-accessible area, the forwarded message
+is then rewritten to use the URL and is accessed only when needed.
+
+    Sessions are created/joined with no special setup required, e.g.
+
+	% vosamp --session=foo			e.g. commandline tool
+or	
+	voc.vosamp ("session=foo")		e.g. from language API
+
+The VOSAMP in this case would contact the session manager to join the list
+of machines in session 'foo', this session would be created if it did not
+already exist and sessions quietly end when the VOSAMP proxies timeout due
+to inactivity or are shut down explicitly.  There is no need for formal
+security since it is up to the parties in the session to agree on and share
+the session name of their choosing.  Applications written using the language
+bindings can participate in sessions by simply calling the VOSAMP task to
+create the proxy regardless of whether it is used explicitly for messaging.
+
+
+
+=============================================================================
+
+#define	DEF_PORT	4433		/* Session Mgr contact port	*/
+
+#define	MAX_SESSIONS	64		/* Max sessions to manage	*/
+#define	MAX_CLIENTS	64		/* Max clients in each session	*/
+
+#define	SZ_IPSTR	16		/* Size of an IP string		*/
+
+
+typedef struct {
+    int	   port;			/* connection port		*/
+    char   hostIP[SZ_IPSTR];		/* host IP address		*/
+} Client, *ClientP;
+
+
+typedef struct {
+    int	    nclients;			/* number of clients		*/
+    Client *clients[MAX_CLIENTS];	/* clients in session		*/
+    char    dataCache[SZ_LINE];		/* path to local data cache	*/
+} Session, *SessionP;
+
+
+#define	CALLBACK	0	/* mgr sends callback port		*/
+#define	QUIT		1	/* mgr sends disconnect/client retires	*/
+#define	SEND		2	/* mgr/client forwards cmd		*/
+#define	READY		3	/* mgr ready on port			*/
+
+