XPA supports host-based access control for each XPA access point. You can enable/disable access control using the XPA_ACL environment variable. You can specify access to specific XPA access points for specific machines using the XPA_DEFACL and XPA_ACLFILE environment variables. By default, an XPA access point is accessible only to processes running on the same machine (same as X Windows).
When INET sockets are in use (the default, as specified by the XPA_METHOD environment variable), XPA supports a host-based access control mechanism for individual access points. This mean that access can be specified for get, set, or info operations for each access point on a machine by machine basis. For LOCAL sockets, access is restricted (by definition) to the host machine.
XPA access control is enabled by default, but can be turned off by setting the XPA_ACL environment variable to false. In this case, any process can access any XPA server.
Assuming that access control is turned on, the ACL for an individual XPA access point is set up when that access point is registered (although it can be changed later on; see below). This can be done in one of two ways: Firstly, the XPA_ACLFILE environment variable can defined to point to a file of access controls for individual access points. The format of this file is:
class:name ip aclThe first argument is a template that specifies the class:name of the access point covered by this ACL. See XPA Access Points and Templates for more information about xpa templates.
The second argument is the IP address (in human-readable format) of the machine which is being given access. This argument can be * to match all IP addresses. It also can be $host to match the IP address of the current host.
The third argument is a string combination of s, g, or i to allow xpaset, xpaget, or xpainfo access respectively. The ACL argument can be + to give sgi access or it can be - to turn off all access.
For example,
*:xpa1 somehost sg *:xpa1 myhost + * * gwill allow processes on the machine somehost to make xpaget and xpaset calls, allow processes on myhost to make any call, and allow all other hosts to make xpaget (but not xpaset) calls. Secondly, if the XPA_ACLFILE does not exist, then a single default value for all access points can be specified using the XPA_DEFACL environment variable. The default value for this variable is:
#define XPA_DEFACL "*:* $host +"meaning that all access points are fully accessible to all processes on the current host. Thus, in the absence of any ACL environment variables, processes on the current host have full access to all access points created on that host. This parallels the X11 xhost mechanism.
Access to an individual XPA access point can be changed using the -acl parameter for that access point. For example:
xpaset -p xpa1 -acl "somehost -"will turn off all access control for somehost to the xpa1 access point, while:
xpaset -p XPA:xpa1 -acl "beberly gs"will give beberly xpaget and xpaset access to the access point whose class is XPA and whose name is xpa1.
Similarly, the current ACL for a given access point can be retrieved using:
xpaget xpa1 -aclOf course, you must have xpaget access to this XPA access point to retrieve its ACL.
Note that the XPA access points registered in the xpans program also behave according to the ACL rules. That is, you cannot use xpaget to view the access points registered with xpans unless you have the proper ACL.
Note also when a client request is made to an XPA server, the access control is checked when the initial connection is established. This access in effect at this time remains in effect so long as the client connection is maintained, regardless of whether the access fro that XPA is changed later on.
We recognize that host-based access control is only relatively secure and will consider more stringent security (e.g., private key) in the future if the community requires such support.
This ChangeLog covers the XPA 2 implementation. It will be updated as we continue to develop and improve XPA. The up-to-date version can be found here.
New features include:
xpaget xpamb -info foowill return info about the previously stored data named foo. If neither switch is present, then the name is assumed to be an XPA access point.
if [catch { xparec "" version } version] {
puts "pre-2.1.0e"
} else {
puts [split $version .]
}
to help differentiate between XPA versions within Tcl code.
setenv XPA_NSINET host:port[,port[,port]]to allow specification of the XPA access point port for xpans, as well as the proxy data port.
[data] | xpaset [server] -clipboard add|append [clipboard_name] xpaset -p [server] -clipboard delete [clipboard_name] xpaget [server] -clipboard [clipboard_name]Use "add" to create a new clipboard or replace the contents of an existing one. Use "append" to append to an existing clipboard.
This document describes changes that will affect users who migrate from XPA 1.0 to XPA 2.0.
There have been a few changes that affect users who upgrade XPA from version 1.0 to version 2.0. These changes are detailed below.
cat foo.fits | xpaset SAOtng fits
instead of:
cat foo.fits | xpaset SAOtng
echo "file foo.fits" | xpaset -n SAOtng
xpaset -p SAOtng colormap I8
will send the paramlist to the SAOtng callback without reading from stdin.
Sending/receiving data to/from an XPA access point is easy: you generally only need to call the XPAGet() or XPASet() subroutines.
#include <xpa.h> int XPAGet(XPA xpa, char *template, char *paramlist, char *mode, char **bufs, size_t *lens, char **names, char **messages, int n); int XPASet(XPA xpa, char *template, char *paramlist, char *mode, char *buf, size_t len, char **names, char **messages, int n); int XPAInfo(XPA xpa, char *template, char *paramlist, char *mode, char **names, char **messages, int n); int XPAAccess(XPA xpa, char *template, char *paramlist, char *mode, char **names, char **messages, int n); int XPAGetFd(XPA xpa, char *template, char *paramlist, char *mode, int *fds, char **names, char **messages, int n); int XPASetFd(XPA xpa, char *template, char *paramlist, char *mode, int fd, char **names, char **messages, int n); XPA XPAOpen(char *mode); void XPAClose(XPA xpa); int XPANSLookup(XPA xpa, char *template, char *type, char ***classes, char ***names, char ***methods, char ***infos);
#include <xpa.h>in the software module that defines or accesses an XPA access point and then will link against the libxpa.a library:
gcc -o foo foo.c libxpa.aXPA has been compiled using both C and C++ compilers.
Client communication with XPA public access points generally is accomplished using XPAGet() or XPASet() within a program (or xpaget and xpaset at the command line). Both routines require specification of the name of the access point. If a template is used to specify the access point name (e.g., "ds9*"), then communication will take place with all servers matching that template.
#include <xpa.h>
int XPAGet(XPA xpa,
char *template, char *paramlist, char *mode,
char **bufs, size_t *lens, char **names, char **messages,
int n);
Retrieve data from one or more XPA servers whose class:name identifier matches the specified template.
A template of the form "class1:name1" is sent to the XPA name server, which returns a list of at most n matching XPA servers. A connection is established with each of these servers and the paramlist string is passed to the server as the data transfer request is initiated. If an XPA struct is passed to the call, then the persistent connections are updated as described above. Otherwise, temporary connections are made to the servers (which will be closed when the call completes).
The XPAGet() routine then retrieves data from at most n XPA servers, places these data into n allocated buffers and places the buffer pointers in the bufs array. The length of each buffer is stored in the lens array. A string containing the class:name and ip:port is stored in the name array. If a given server returned an error or the server callback sends a message back to the client, then the message will be stored in the associated element of the messages array. NB: if specified, the name and messages arrays must be of size n or greater.
The returned message string will be of the form:
XPA$ERROR error-message (class:name ip:port)or
XPA$MESSAGE message (class:name ip:port)
Note that when there is an error stored in an messages entry, the corresponding bufs and lens entry may or may not be NULL and 0 (respectively), depending on the particularities of the server.
The return value will contain the actual number of servers that were processed. This value thus will hold the number of valid entries in the bufs, lens, names, and messages arrays, and can be used to loop through these arrays. In names and/or messages is NULL, no information is passed back in that array.
The bufs, names, and messages arrays should be freed upon completion (if they are not NULL);
The mode string is of the form: "key1=value1,key2=value2,..." The following keywords are recognized:
key value default explanation ------ -------- -------- ----------- ack true/false true if false, don't wait for ack from server (after callback completes) doxpa true/false true client processes xpa requests
The ack keyword is not very useful, since the server completes the callback in order to return the data anyway. It is here for completion (and perhaps for future usefulness).
Normally, an XPA client will process incoming XPA server requests while awaiting the completion of the client request. Setting this variable to "false" will prevent XPA server requests from being processed by the client.
Example:
#include <xpa.h>
#define NXPA 10
int i, got;
size_t lens[NXPA];
char *bufs[NXPA];
char *names[NXPA];
char *messages[NXPA];
got = XPAGet(NULL, "ds9", "file", NULL, bufs, lens, names, messages,
NXPA);
for(i=0; i<got; i++){
if( messages[i] == NULL ){
/* process buf contents */
ProcessImage(bufs[i], ...);
free(bufs[i]);
}
else{
/* error processing */
fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]);
}
if( names[i] )
free(names[i]);
if( messages[i] )
free(messages[i]);
}
#include <xpa.h>
int XPASet(XPA xpa,
char *template, char *paramlist, char *mode,
char *buf, size_t len, char **names, char **messages,
int n);
Send data to one or more XPA servers whose class:name identifier matches the specified template.
A template of the form "class1:name1" is sent to the XPA name server, which returns a list of at most n matching XPA servers. A connection is established with each of these servers and the paramlist string is passed to the server as the data transfer request is initiated. If an XPA struct is passed to the call, the persistent connections are updated as described above. Otherwise, temporary connections are made to the servers (which will be closed when the call completes).
The XPASet() routine transfers data from buf to the XPA servers. The length of buf (in bytes) should be placed in the len variable.
A string containing the class:name and ip:port of each of these server is returned in the name array. If a given server returned an error or the server callback sends a message back to the client, then the message will be stored in the associated element of the messages array. NB: if specified, the name and messages arrays must be of size n or greater.
The returned message string will be of the form:
XPA$ERROR [error] (class:name ip:port)or
XPA$MESSAGE [message] (class:name ip:port)
The return value will contain the actual number of servers that were processed. This value thus will hold the number of valid entries in the names and messages arrays, and can be used to loop through these arrays. In names and/or messages is NULL, no information is passed back in that particular array.
The mode string is of the form: "key1=value1,key2=value2,..." The following keywords are recognized:
key value default explanation ------ -------- -------- ----------- ack true/false true if false, don't wait for ack from server (after callback completes) verify true/false false send buf from XPASet[Fd] to stdout doxpa true/false true client processes xpa requests
The ack keyword is useful in cases where one does not want to wait for the server to complete, e.g. if a lot of processing needs to be done by the server on the passed data or when the success of the server operation is not relevant to the client.
Normally, an XPA client will process incoming XPA server requests while awaiting the completion of the client request. Setting this variable to "false" will prevent XPA server requests from being processed by the client.
Example:
#include <xpa.h>
#define NXPA 10
int i, got;
size_t len;
char *buf;
char *names[NXPA];
char *messages[NXPA];
...
[fill buf with data and set len to the length, in bytes, of the data]
...
/* send data to all access points */
got = XPASet(NULL, "ds9", "fits", NULL, buf, len, names, messages, NXPA);
/* error processing */
for(i=0; i<got; i++){
if( messages[i] ){
fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]);
}
if( names[i] ) free(names[i]);
if( messages[i] ) free(messages[i]);
}
#include <xpa.h>
int XPAInfo(XPA xpa,
char *template, char *paramlist, char *mode,
char **names, char **messages, int n);
Send a short paramlist message to one or more XPA servers whose class:name identifier matches the specified template.
A template of the form "class1:name1" is sent to the XPA name server, which returns a list of at most n matching XPA servers. A connection is established with each of these servers and the paramlist string is passed to the server as the data transfer request is initiated. If an XPA struct is passed to the call, then the persistent connections are updated as described above. Otherwise, temporary connections are made to the servers (which will be closed when the call completes).
The XPAInfo() routine does not send data from a buf to the XPA servers. Only the paramlist is sent. The semantics of the paramlist is not formalized, but at a minimum is should tell the server how to get more information. For example, it might contain the class:name of the XPA access point from which the server (acting as a client) can obtain more info using XPAGet.
A string containing the class:name and ip:port of each server is returned in the name array. If a given server returned an error or the server callback sends a message back to the client, then the message will be stored in the associated element of the messages array. The returned message string will be of the form:
XPA$ERROR error-message (class:name ip:port)or
XPA$MESSAGE message (class:name ip:port)
The return value will contain the actual number of servers that were processed. This value thus will hold the number of valid entries in the names and messages arrays, and can be used to loop through these arrays. In names and/or messages is NULL, no information is passed back in that array.
The following keywords are recognized:
key value default explanation ------ -------- -------- ----------- ack true/false true if false, don't wait for ack from server
When ack is false, XPAInfo() will not wait for an error return from the XPA server. This means, in effect, that XPAInfo will send its paramlist string to the XPA server and then exit: no information will be sent from the server to the client. This UDP-like behavior is essential to avoid race conditions in cases where XPA servers are sending info messages to other servers. If two servers try to send each other an info message at the same time and then wait for an ack, a race condition will result and one or both will time out.
Example:
(void)XPAInfo(NULL, "IMAGE", "ds9 image", NULL, NULL, NULL, 0);
#include <xpa.h>
int XPAGetFd(XPA xpa,
char *template, char *paramlist, char *mode,
int *fds, char **names, char **messages, int n);
Retrieve data from one or more XPA servers whose class:name identifier matches the specified template and write it to files associated with one or more standard I/O fds (i.e, handles returned by open()).
A template of the form "class1:name1" is sent to the XPA name server, which returns a list of at most ABS(n) matching XPA servers. A connection is established with each of these servers and the paramlist string is passed to the server as the data transfer request is initiated. If an XPA struct is passed to the call, then the persistent connections are updated as described above. Otherwise, temporary connections are made to the servers (which will be closed when the call completes).
The XPAGetFd() routine then retrieves data from the XPA servers, and write these data to the fds associated with one or more fds (i.e., results from open). Is n is positive, then there will be n fds and the data from each server will be sent to a separate fd. If n is negative, then there is only 1 fd and all data is sent to this single fd. (The latter is how xpaget is implemented.)
A string containing the class:name and ip:port is stored in the name array. If a given server returned an error or the server callback sends a message back to the client, then the message will be stored in the associated element of the messages array. NB: if specified, the name and messages arrays must be of size n or greater.
The returned message string will be of the form:
XPA$ERROR error-message (class:name ip:port)or
XPA$MESSAGE message (class:name ip:port)
Note that when there is an error stored in an messages entry, the corresponding bufs and lens entry may or may not be NULL and 0 (respectively), depending on the particularities of the server.
The return value will contain the actual number of servers that were processed. This value thus will hold the number of valid entries in the bufs, lens, names, and messages arrays, and can be used to loop through these arrays. In names and/or messages is NULL, no information is passed back in that array.
The mode string is of the form: "key1=value1,key2=value2,..." The following keywords are recognized:
key value default explanation ------ -------- -------- ----------- ack true/false true if false, don't wait for ack from server (after callback completes)
The ack keyword is not very useful, since the server completes the callback in order to return the data anyway. It is here for completion (and perhaps for future usefulness).
Example:
#include <xpa.h>
#define NXPA 10
int i, got;
int fds[NXPA];
char *names[NXPA];
char *messages[NXPA];
for(i=0; i<NXPA; i++)
fds[i] = open(...);
got = XPAGetFd(NULL, "ds9", "file", NULL, fds, names, messages, NXPA);
for(i=0; i<got; i++){
if( messages[i] != NULL ){
/* error processing */
fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]);
}
if( names[i] )
free(names[i]);
if( messages[i] )
free(messages[i]);
}
#include <xpa.h>
int XPASetFd(XPA xpa,
char *template, char *paramlist, char *mode,
int fd, char **names, char **messages, int n)
Read data from a standard I/O fd and send it to one or more XPA
servers whose class:name identifier matches the specified
template.
A
template
of the form "class1:name1" is sent to the
XPA name server, which returns a list of at most n matching XPA
servers. A connection is established with each of these servers and
the paramlist string is passed to the server as the data transfer
request is initiated. If an XPA struct is passed to the call, then the
persistent connections are updated as described above. Otherwise,
temporary connections are made to the servers (which will be closed
when the call completes).
The XPASetFd() routine then reads bytes from the specified fd
until EOF and sends these bytes to the XPA servers.
The final parameter n specifies the maximum number of servers to contact.
A string containing the class:name and ip:port of each server is returned in
the name array. If a given server returned an error, then the error
message will be stored in the associated element of the messages array.
NB: if specified, the name and messages arrays must be of size n or greater.
The return value will contain the actual number of servers that were
processed. This value thus will hold the number of valid entries in
the names and messages arrays, and can be used to loop through these
arrays. In names and/or messages is NULL, no information is passed back
in that array.
The mode string is of the form: "key1=value1,key2=value2,..."
The following keywords are recognized:
The ack keyword is useful in cases where one does not want to wait for
the server to complete, e.g. is a lot of processing needs to be done
on the passed data or when the success of the server operation is not
relevant to the client.
Example:
XPAOpen() allocates a persistent XPA struct that can be used with
calls to XPAGet(), XPASet(), XPAInfo(), XPAGetFd(), and
XPASetFd(). Persistence means that a connection to an XPA server is
not closed when one of the above calls is completed but will be
re-used on successive calls. Using XPAOpen() therefore saves the time
it takes to connect to a server, which could be significant with slow
connections or if there will be a large number of exchanges with a
given access point. The mode argument currently is ignored ("reserved
for future use").
An XPA struct is returned if XPAOpen() was successful; otherwise NULL
is returned. This returned struct can be passed as the first argument
to XPAGet(), etc. Those calls will update the list of active XPA
connections. Already connected servers (from a previous call) are
left connected and new servers also will be connected. Old servers
(from a previous call) that are no longer needed are disconnected.
The connected servers will remain connected when the next call to
XPAGet() is made and connections are once again updated.
Example:
XPAClose closes the persistent connections associated with this XPA struct
and frees all allocated space. It also closes the open sockets connections
to all XPA servers that were opened using this handle.
Example:
XPA routines act on a class:name identifier in such a way
that all access points that match the identifier are processed. It is
sometimes desirable to choose specific access points from the
candidates that match the
template. In order to do this, the
XPANSLookup routine can be called to return a list of matches, so that
specific class:name instances can then be fed to XPAGet(), XPASet(), etc.
The first argument is an optional XPA struct. If non-NULL, the
existing name server connection associated with the specified xpa is
used to query the xpans name server for matching templates. Otherwise,
a new (temporary) connection is established with the name server.
The second argument to XPANSLookup is the class:name
template
to match.
The third argument for XPANSLookup() is the type of access and can be
any combination of:
The call typically specifies only one of these at a time.
The final arguments are pointers to arrays that will be filled
in and returned by the name server. The name server will allocate and
return arrays filled with the classes, names, and methods of all XPA
access points that match the template
and have the specified type. Also returned are info strings, which
generally are used internally by the client routines. These can be
ignored (but the strings must be freed). The function returns the
number of matches. The returned value can be used to loop through the
matches:
Example:
The specified
template
also can be a host:port specification, for example:
In this case, no connection is made to the name server. Instead, the
call will return one entry such that the ip array contains the ip for
the specified host and the port array contains the port. The class
and name entries are set to the character "?", since the class and
name of the access point are not known.
The XPAAccess routine returns the public access points that match the
specified second argument template and
have the specified access type.
A
template
of the form "class1:name1" is sent to the
XPA name server, which returns a list of at most n matching XPA
servers. A connection is established with each of these servers and
the paramlist string is passed to the server as the data transfer
request is initiated. If an XPA struct is passed to the call, then the
persistent connections are updated as described above. Otherwise,
temporary connections are made to the servers (which will be closed
when the call completes).
The XPAAccess() routine retrieves names from at most n XPA servers
that match the specified template and that were checked for access
using the specified mode. The return string contains both the
class:name and ip:port. If a given server returned an error or the
server callback sends a message back to the client, then the message
will be stored in the associated element of the messages array.
NB: if specified, the name and messages arrays must be of size n or greater.
The returned message string will be of the form:
Note that names of matching registered access points are always
returned but may not be valid; it is not sufficient to assume that the
returned number of access points is the number of valid access points.
Rather, it is essential to check the messages array for error
messages. Any string in the messages array is an error message and
indicated that the associated access point is not available.
For example, assume that a server registers a number of access points
but delays entering its event loop. If a call to XPAAccess() is made
before the event loop is entered, the call will timeout (after waiting
for the long timeout period) and return an error of the form:
NB: This routine only works with XPA servers built with XPA 2.1.x and later.
Servers with older versions of XPA will return the error message:
XPA$ERROR invalid xpa command in initialization string
If you get this error message, then the old server actually is ready
for access, since it got to the point of fielding the query! The
xpaaccess program, for example, ignores this message in order to work
properly with older servers.
The third argument for XPAAccess() is the type of access and can be
any combination of:
The mode string argument is of the form: "key1=value1,key2=value2,..."
The following keywords are recognized:
The ack keyword is not very useful, since the server completes the callback
in order to return the data anyway. It is here for completion (and perhaps
for future usefulness).
This document describes tips for converting from xpa 1.0 (Xt-based
xpa) to xpa 2.0 (socket-based xpa).
The following are tips for converting from xpa 1.0 (Xt-based xpa) to
xpa 2.0 (socket-based xpa). The changes are straight-forward and
almost can be done automatically (we used editor macros for most of
the conversion).
The following environment variables are supported by XPA:
By default, this option is turned off, because we judge that the added
code complication and overhead involved will not be justified by the
amount of its use. Moreover, processing XPA requests within socket IO
can lead to non-intuitive results, since incoming server requests will
not necessarily be processed to completion in the order in which they
are received.
The XPA_LONG_TIMEOUT variable controls the long
timeout and is used to prevent hangs in cases where communication
between the client and server that is not controlled by the
XPA interface itself. Transfer of data between client and server, or a
client's wait for a status message after completion of the server
callback, are two examples of this sort of communication. By default,
the long timeout is set to 180 seconds.
Setting the value to -1 will disable long timeouts and allow
an infinite amount of time.
Once defined, the first registration of an XPA access point will
ensure that an instance of the
XPA Name Server (xpans)
is running that handles that connection method. All new access points
will use the new connection method but existing access points will use
the original method.
The port used by xpans to register its XPA access point normally is
taken to be one greater than the port on which it receives new access
points from XPA servers. You can specify a specific access point port
using the syntax machine:port1,port2, i.e., the access point port is
specified after the comma. For example, $host:12345,23456 will listen
for new access ports on 12345 and will accept XPA commands on 23456.
Specification of specific ports is useful, for example, when a machine
outside a firewall needs to communicate with a machine inside a
firewall. In such a case, the firewall should be configured to allow
socket connections to both the command and data port from the outside
machine, and the inside XPA program should be started up with the
outside machine in its ACL list. Then, when the inside program is
started with specified ports, outside XPA programs can use
"machine:port" to contact the inside access points, instead of the
access point names. That is, the machine outside the firewall does not
need access to the XPA name server:
This support is somewhat experimental. If you run into problems, please
let us know.
The XPA_SHORT_TIMEOUT variable
controls the short timeout and is used to prevent hangs
in cases where the XPA protocol requires internal communication between
the client and server that is controlled by the XPA interface
itself. Authentication is an example of this sort of communication,
as is the establishment of a data channel between the two processes.
The default value for the short is 30 seconds (which is
a pretty long time, actually). Setting the value to -1 will disable
short timeouts and allow an infinite amount of time.
In general, it is a bad idea to run an XPA-enabled server program
using a version of XPA newer than the basic xpaset, xpaget, xpaaccess,
xpans programs. This sort of mismatch usually will not work due to
protocol changes.
The XPA source code directory contains two test programs,
stest.c, and ctest.c that can serve as
examples for writing XPA servers and clients, respectively.
They also can be used to test various features of XPA.
To build the XPA test programs, execute:
The stest program can be executed with no arguments to start
an XPA server that contains the access points: xpa, xpa1,
c_xpa (containing sub-commands cmd1 and cmd2), and i_xpa.
You then can use xpaset and xpaget to interact with these access points:
The file test.tcl in the XPA source directory gives examples for using the
XPATclInterface.
The XPA messaging system provides seamless communication between many
kinds of Unix programs, including X programs and Tcl/Tk programs. It
also provides an easy way for users to communicate with XPA-enabled
programs by executing XPA client commands in the shell or by utilizing
such commands in scripts. Because XPA works both at the programming
level and the shell level, it is a powerful tool for unifying any
analysis environment: users and programmers have great flexibility in
choosing the best level or levels at which to access XPA services, and
client access can be extended or modified easily at any time.
A program becomes an XPA-enabled server by defining named points of
public access through which data and commands can be exchanged with
other client programs (and users). Using standard TCP sockets as a
transport mechanism, XPA supports both single-point and broadcast
messaging to and from these servers. It supports direct communication
between clients and servers, or indirect communication via an
intermediate message bus emulation program. Host-based access control
is implemented, as is as the ability to communicate with XPA servers
across a network.
XPA implements a layered interface that is designed to be useful both
to software developers and to users. The interface consists of a
library of XPA client and server routines for use in C/C++ programs and
a suite of high-level user programs built on top of these libraries.
Using the XPA library, access points can be added to Tcl/Tk programs,
Xt programs, or to Unix programs that use the XPA event loop or any
event loop based on select(). Client access subroutines can be added
to any Tcl/Tk, Xt, or Unix program. Client access also is supported at
the command line via a suite of high-level programs.
Choose from the following topics:
key value default explanation
------ -------- -------- -----------
ack true/false true if false, don't wait for ack from server (after callback completes)
verify true/false false send buf from XPASet[Fd] to stdout
#include <xpa.h>
#define NXPA 10
int i, got;
int fd;
char *names[NXPA];
char *messages[NXPA];
fd = open(...);
got = XPASetFd(NULL, "ds9", "fits", NULL, fd, names, messages, NXPA);
for(i=0; i<got; i++){
if( messages[i] != NULL ){
/* error processing */
fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]);
}
if( names[i] )
free(names[i]);
if( messages[i] )
free(messages[i]);
}
XPAOpen: allocate a persistent client handle
#include <xpa.h>
XPA XPAOpen(char *mode);
#include <xpa.h>
XPA xpa;
xpa = XPAOpen(NULL);
XPAClose: close a persistent XPA client handle
#include <xpa.h>
void XPAClose(XPA xpa);
#include <xpa.h>
XPA xpa;
XPAClose(xpa);
XPANSLookup: lookup registered XPA access points
#include <xpa.h>
int XPANSLookup(XPA xpa,
char *template, char type,
char ***classes, char ***names,
char ***methods, char ***infos)
type explanation
------ -----------
g xpaget calls can be made on this access point
s xpaset calls can be made on this access point
i xpainfo calls can be made on this access point
#include <xpa.h>
char **classes;
char **names;
char **methods;
char **infos;
int i, n;
n = XPANSLookup(NULL, "foo*", "g", &classes, &names, &methods, &infos);
for(i=0; i<n; i++){
[more specific checks on possibilities ...]
[perhaps a call to XPAGet for those that pass, etc. ...]
/* don't forget to free alloc'ed strings when done */
free(classes[i]);
free(names[i]);
free(methods[i]);
free(infos[i]);
}
/* free up arrays alloc'ed by names server */
if( n > 0 ){
free(classes);
free(names);
free(methods);
free(infos);
}
myhost:12345
XPAAccess: return XPA access points matching
template (XPA 2.1 and above)
#include <xpa.h>
int XPAAccess(XPA xpa,
char *template, char *paramlist, char *mode,
char **names, char **messages, int n);
XPA$ERROR error-message (class:name ip:port)
XPA$ERROR: timeout waiting for server authentication (XPA:xpa1)
The error means that the XPA access point has been registered but is
not yet available (because events are not being processed). When the
server finally enters its event loop, subsequent calls to XPAAccess()
will return successfully.
type explanation
------ -----------
g xpaget calls can be made on this access point
s xpaset calls can be made on this access point
i xpainfo calls can be made on this access point
key value default explanation
------ -------- -------- -----------
ack true/false true if false, don't wait for ack from server (after callback completes)
Last updated: March 10, 2007
imexam-0.9.1/cextern/xpa/doc/convert.html 0000644 0006325 0002007 00000007671 13640457670 022141 0 ustar sosey STSCI\science 0000000 0000000
XPAConvert: Converting the XPA API to 2.0
Summary
Description
#ifdef XPA_VERSION
static void XPAReceiveFile(client_data, call_data, paramlist, buf, len)
void *client_data;
void *call_data;
char *paramlist;
char *buf;
int len;
#else
static void XPAReceiveFile(w, client_data, call_data, paramlist, buf, len)
Widget w;
XtPointer client_data;
XtPointer call_data;
char *paramlist;
char *buf;
int len;
#endif
xpa = NewXPACommand(toplevel, NULL, prefix, NULL);
is changed to:
xpa = XPACmdNew(xclass, name);
AddXPACommand(xpa, "file",
"\tdisplay a new file\n\t\t requires: filename",
NULL, NULL, NULL, XPAReceiveFile, text, NULL);
is changed to:
XPACmdAdd(xpa, "file",
"\tdisplay a new file\n\t\t requires: filename",
NULL, NULL, NULL, XPAReceiveFile, text, NULL);
/* add the xpas to the Xt loop */
XPAXtAddInput(app, NULL);
/* process events */
XtAppMainLoop(app);
xpa = NewXPA(saotng->xim->toplevel, prefix, xparoot,
"FITS data or image filename\n\t\t options: file type",
XPASendData, new, NULL,
XPAReceiveData, new, "SE");
is changed to:
sprintf(tbuf, "%s.%s", prefix, xparoot);
xpa = XPANew("SAOTNG", tbuf,
"FITS data or image filename\n\t\t options: file type",
XPASendData, new, NULL,
XPAReceiveData, new, "SE");
XPAXtAddInput(XtWidgetToApplicationContext(saotng->xim->toplevel), xpa);
XPAInternalReceiveCommand(im->saotng->xim->toplevel,
im->saotng, im->saotng->commands,
"zoom reset", NULL, 0);
is changed to:
XPACmdInternalReceive(im->saotng, im->saotng->commands,
"zoom reset", NULL, 0);
DestroyXPA(im->dataxpa);
is changed to:
XPAFree(im->dataxpa);
Last updated: September 10, 2003
imexam-0.9.1/cextern/xpa/doc/env.html 0000644 0006325 0002007 00000040246 13640457670 021244 0 ustar sosey STSCI\science 0000000 0000000
XPAEnv: Environment Variables for XPA Messaging
Summary
Describes the environment variables which can be used to tailor the overall
XPA environment.
Description
xpaget ds9 colormap
you might get information from your own ds9 as well as
from another user running ds9 on the same machine. The
XPA_NSUSERS variable controls whether you want such access
to the access points of other users.
By default, only your own access points are returned, so
that, in the example above, you would only get the colormap information
from the ds9 you registered. If, however, you had set the value of the
XPA_NSUSERS variable to eric,fred, then you would be
able to communicate with both eric and fred's access points. Note that
this variable can be overridden using the -u switch on the
xpaget, xpaset, and xpainfo programs.
class:template port1[ port2]
where port1 is the main (command) port for the access point and
port2 is the (secondary) data port. If port2 is not specified,
it defaults to a value of 0 (meaning the system assigns the port).
export XPA_PORT="DS9:ds9 12345 12346" # on machine "inside"
cat foo.fits | xpaset inside:12345 fits # on machine "outside"
Note that 2 ports are required for full XPA communication and
therefore 2 ports should be specified to go through a firewall. The
second port assignment is not important if you simply are assigning
the command port in order to communicate commands with a known
port (e.g., to bypass the xpans name server). If only one (command)
port is specified, the system will negotiate a random data port and
everything will work properly.
class:template port1 [port2]
where port1 is the main port for the access point and
port2 is the data port. If port2 is not specified, it defaults
to a value of 0 (meaning the system assigns the port). See
XPA_PORT above for an explanation of user-specified ports.
Last updated: December 23, 2009
imexam-0.9.1/cextern/xpa/doc/examples.html 0000644 0006325 0002007 00000004101 13640457670 022260 0 ustar sosey STSCI\science 0000000 0000000
XPACode: Where to Find Example/Test Code
Summary
Description
make All
in the XPA source directory to generate the stest and
ctest programs. (NB: this should work on all platforms,
although we have had problems with unresolved externals on one
Sun/Solaris machine, for reasons still unknown.)
cat xpa.c | xpaset xpa # send to xpa
cat xpa.c | xpaset "xpa*" # send to xpa and xpa1
xpaget xpa # receive from xpa
xpaget xpa* # receive from xpa and xpa1
etc. You also can use ctest to do the same thing, or to iterate:
ctest -s -l 100 xpa # send to xpa 100 times
ctest -s -l 100 "xpa*" # send to xpa and xpa1 100 times
ctest -g -l 100 xpa # receive from xpa 100 times
ctest -g -l 100 "xpa*" # receive from xpa and xpa1 100 times
More options are available: see the stest.c and ctest.c code itself, which
were used extensively to debug XPA.
Last updated: September 10, 2003
imexam-0.9.1/cextern/xpa/doc/help.html 0000644 0006325 0002007 00000014602 13640457670 021401 0 ustar sosey STSCI\science 0000000 0000000
XPA: Public Access to Data and Algorithms
Summary
This document is the Table of Contents for XPA.
Description
Last updated: September 10, 2003
imexam-0.9.1/cextern/xpa/doc/html2man 0000755 0006325 0002007 00000015327 13640457670 021240 0 ustar sosey STSCI\science 0000000 0000000 #!/usr/bin/perl
#
# See COPYRIGHT
#
# Script to generate a pod file from an html source (the same one as for text files too)
# and later this pod file it passed through pod2man
#
# Use:
# html2man [
- to paragraph break
# - to B<>
# - to I<>
# - to C<>
# - to F<>
# ,
- to =over 2, =item *, =back
# , &, <, > - to their symbols, appropriately encoded
#
# The rest of HTML tags is removed
#
# If the same section is started more than once, the text from the
# second appearance will be added to the first, etc.
#
#
# Stop copying text to the man page.
#
#
# Continue copying text to the man page, same section as before.
#
#
# Insert this