=pod

=head1 NAME



B<XPAOpen: allocate a persistent client handle>



=head1 SYNOPSIS





  #include <xpa.h>

  XPA XPAOpen(char *mode);





=head1 DESCRIPTION




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.


B<Example:>

 #include <xpa.h>

  XPA xpa;
  xpa = XPAOpen(NULL);





=head1 SEE ALSO



See xpa(n) for a list of XPA help pages


=cut