.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "xpaaccess 3"
.TH xpaaccess 3 "July 23, 2013" "version 2.1.15" "SAORD Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XPAAccess: return XPA access points matching
template (XPA 2.1 and above)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  #include <xpa.h>
\&
\&  int XPAAccess(XPA xpa,
\&                char *template, char *paramlist, char *mode,
\&                char **names, char **messages, int n);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The XPAAccess routine returns the public access points that match the
specified second argument template and
have the specified access type.
.PP
A
template
of the form \*(L"class1:name1\*(R" is sent to the
\&\s-1XPA\s0 name server, which returns a list of at most n matching \s-1XPA\s0
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 \s-1XPA\s0 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).
.PP
The \fIXPAAccess()\fR routine retrieves names from at most n \s-1XPA\s0 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.
\&\s-1NB:\s0 if specified, the name and messages arrays must be of size n or greater.
.PP
The returned message string will be of the form:
.PP
.Vb 1
\&  XPA$ERROR error\-message (class:name ip:port)
.Ve
.PP
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.
.PP
For example, assume that a server registers a number of access points
but delays entering its event loop. If a call to \fIXPAAccess()\fR 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:
.PP
.Vb 1
\&  XPA$ERROR: timeout waiting for server authentication (XPA:xpa1)
.Ve
.PP
The error means that the \s-1XPA\s0 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 \fIXPAAccess()\fR
will return successfully.
.PP
\&\s-1NB:\s0 This routine only works with \s-1XPA\s0 servers built with \s-1XPA\s0 2.1.x and later.
Servers with older versions of \s-1XPA\s0 will return the error message:
.PP
.Vb 1
\&  XPA$ERROR invalid xpa command in initialization string
.Ve
.PP
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.
.PP
The third argument for \fIXPAAccess()\fR is the type of access and can be
any combination of:
.PP
.Vb 5
\&  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
.Ve
.PP
The mode string argument is of the form: \*(L"key1=value1,key2=value2,...\*(R"
The following keywords are recognized:
.PP
.Vb 3
\&  key           value           default         explanation
\&  \-\-\-\-\-\-        \-\-\-\-\-\-\-\-        \-\-\-\-\-\-\-\-        \-\-\-\-\-\-\-\-\-\-\-
\&  ack           true/false      true            if false, don\*(Aqt wait for ack from server (after callback completes)
.Ve
.PP
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).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See xpa(n) for a list of \s-1XPA\s0 help pages