The gspool_open routine is used to commence a session with the
API. The first form is that used on Unix or GNU/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.
host is the name of the host to be connected to. Serv is the
name of the TCP/UDP service to be used to connect to GNUspool. If
this is set to NULL, the default service will be used (but this must
be set up correctly).
user is the Unix user name to be used on Windows hosts and pass
is the password. Note that this is not "const", and the passed field
will be deliberately overwritten as soon as possible within
gspool_login. Also note that the password may not be the Unix password,
it may be an interface password set up by xipasswd(8).
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
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.
If an error occurs, one of the following (negative) error codes will be returned.
GSPOOL_BADWRITE
failure writing to the network
GSPOOL_BADREAD
failure reading from the network
GSPOOL_NOMEM
out of memory accessing network
GSPOOL_UNKNOWN_USER
user name not known
GSPOOL_NO_PASSWD
password must be specified
GSPOOL_PASSWD_INVALID
invalid password
Each connection should also be terminated by a call to gspool_close or
exit from the calling program.
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.
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);
Copyright (c) 2009 Free Software Foundation, Inc.
This is free software. You may redistribute copies of it under the
terms of the GNU General Public License
<http://www.gnu.org/licenses/gpl.html>.
There is NO WARRANTY, to the extent permitted by law.