=head1 NAME

gspool_open - open a connection to a GNUspool Host

gspool_login - log in to GNUspool Host from Windows

=head1 SYNOPSIS

=for man
\&\fB#include <gspool.h>\fR
.PP

=for html
<STRONG>#include &lt;gspool.h&gt;</STRONG>
<br>

B<int gspool_open(const char *>I<host>B<, const char *>I<serv>B<, const classcode_t> I<cl>B<)>
<br>
B<int gspool_open(const char *>I<host>B<, const char *>I<serv>B<, const char *>I<user>B<, const classcode_t> I<cl>B<)>
<br>
B<int gspool_login(const char *>I<host>B<, const char *>I<serv>B<, const char *>I<user>B<, char *>I<pass>B<, const classcode_t> I<cl>B<)>

=head1 DESCRIPTION

The B<gspool_open> routine is used to commence a session with the API. The
first form is that used on Unix or Linux hosts, the user name being
obtained from the effective user id invoking the routine.

The second form is that used on Windows hosts, where the Windows
machine has a static IP address and no password is required.

The third form is that used on Windows hosts with IP addresses
allocated via DHCP and/or a password is required.

I<host> is the name of the host to be connected to. I<Serv> is the
name of the TCP/UDP service to be used to connect to B<GNUspool>.  If
this is set to NULL, the default service will be used (but this must
be set up correctly).

I<user> is the Unix user name to be used on Windows hosts and I<pass>
is the password. Note that this is not C<const>, and the passed field
will be deliberately overwritten as soon as possible within
B<gspool_login>. Also note that the password may not be the Unix password,
it may be an I<interface password> set up by xipasswd(8).

I<cl> is the classcode to be used for access to all printer and job
operations. If 0 is used the user's default class code will be
used. Note that the class code bits are assigned starting at the least
significant bit, thus:

 1 = A
 2 = B
 4 = C
 ....
 0x8000 = P
 0x10000 = a
 0x20000 = b
 0x40000 = c
 ....
 0x80000000 = p

=head1 RETURN VALUES

The functions return an integer descriptor on success, which will be
greater than or equal to 0. This descriptor should be used in all
subsequent operations with the API.

=for html
<P>If an error occurs, one of the (negative) error codes will be returned
as <A HREF="TxtAPI-3.html#Error_codes">listed in Chapter 3</A>.</P>

=for man
If an error occurs, one of the following (negative) error codes will be returned.
.Ip "GSPOOL_BADWRITE" 8
failure writing to the network
.Ip "GSPOOL_BADREAD" 8
failure reading from the network
.Ip "GSPOOL_NOMEM" 8
out of memory accessing network
.Ip "GSPOOL_UNKNOWN_USER" 8
user name not known
.Ip "GSPOOL_NO_PASSWD" 8
password must be specified
.Ip "GSPOOL_PASSWD_INVALID" 8
invalid password

Each connection should also be terminated by a call to B<gspool_close> or
exit from the calling program.

=head1 NOTES

Any number of API sesssions, to the same host or to various hosts, may
be in progress simultaneously, subject to the restrictions on the
number of simultaneous open files per process which the operating
system allows.

=head1 EXAMPLE

An example to open a connection to host "xisl":

 int fd, ret;
 fd = gspool_open("xisl", (char *) 0, 0);
 if (fd < 0) { /* error handling */
     ...
 }

 /* process connection */

 gspool_close(fd);

=head1 SEE ALSO

gspool_close(3),
gspool_jobmon(3),
gspool_ptrmon(3).

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

## Local Variables:
## mode: nroff
## End:
