trusty (3) gspool_open.3.gz

NAME

       gspool_open - open a connection to a GNUspool Host

       gspool_login - log in to GNUspool Host from Windows

SYNOPSIS

       #include <gspool.h>

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

DESCRIPTION

       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);

SEE ALSO

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

COPYRIGHT

       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.

AUTHOR

       John M Collins, Xi Software Ltd.