NAME

       gspool_jobread - get the details of a job

SYNOPSIS

       #include <gspool.h>

       int gspool_jobread(const int fd, const unsigned flags, const slotno_t slot, struct apispq
       *jobd)

DESCRIPTION

       The gspool_jobread() function is used to retrieve the details of a job from a given slot
       number.

       fd is a file descriptor previously returned by gspool_open

       flags is zero, or a logical OR of one or more of the following values

       GSPOOL_FLAG_LOCALONLY
           Ignore remote printers/hosts, i.e. not local to the server, not the client.

       GSPOOL_FLAG_USERONLY
           Ignore other users jobs

       GSPOOL_FLAG_IGNORESEQ
           Ignore changes since the list was last read

       slot is the slot number corresponding to the job as returned by gspool_joblist or
       gspool_jobfindslot.

       jobd is a descriptor, which on return will contain the details of the job in a "struct
       apispq" as defined in gspool.h and containing the following elements:

       jobno_t apispq_job
               Job number

       netid_t apispq_netid
               Host address (network byte order)

       netid_t apispq_orighost
               Originating host address

       slotno_t apispq_rslot
               Slot number on owning machine

       time_t apispq_time
               Time job was submitted

       time_t apispq_starttime
               Time job was started (if applicable)

       time_t apispq_hold
               Time job held to, 0 if not held

       unsigned short apispq_nptimeout
               Time after to delete job if not printed (hours)

       unsigned short apispq_ptimeout
               Time after to delete job if printed (hours)

       unsigned short apispq_extrn
               External job type index

       unsigned short apispq_pglim
               Job size limit applies

       long apispq_size
               Size of job in bytes

       long apispq_posn
               Offset reached if currently being printed

       long apispq_pagec
               Currently-reached page if being printed

       char apispq_uname[]
               User name of job owner

       char apispq_puname[]
               User name of posting user

       unsigned char apispq_cps
               Copies

       unsigned char apispq_pri
               Priority

       classcode_t apispq_class
               Class code bits 1=A 2=B 4=C etc

       unsigned short apispq_jflags
               Job flags

       unsigned char apispq_dflags
               Despooler flags

       slotno_t apispq_pslot
               Printer slot assigned to if printing

       unsigned long apispq_start
               Start page 0=first page

       unsigned long apispq_end
               End page

       unsigned long apispq_npages
               Number of pages

       unsigned long apispq_haltat
               "Halted at" page

       char apispq_file[]
               Job title

       char apispq_form[]
               Job form type

       char apispq_ptr[]
               Printer pattern assigned to job

       char apispq_flags[]
               Post-processing flags

       The following bits are set in the "apispq_jflags" field to indicate job parameters:

       APISPQ_NOH
               Suppress header

       APISPQ_WRT
               Write result

       APISPQ_MAIL
               Mail result

       APISPQ_RETN
               Retain on queue after printing

       APISPQ_ODDP
               Suppress odd pages

       APISPQ_EVENP
               Suppress even pages

       APISPQ_REVOE
               Invert APISPQ_ODDP and API_EVENP after printing

       APISPQ_MATTN
               Mail attention

       APISPQ_WATTN
               Write attention

       APISPQ_LOCALONLY
               Handle job on local machine only

       APISPQ_CLIENTJOB
               Job originated with windows client

       APISPQ_ROAMUSER
               Job originated with DHCP windows client

       The "apispq_dflags" field contains the following bits:

       APISPQ_PQ
               Job being printed

       APISPQ_PRINTED
               Job has been printed

       APISPQ_STARTED
               Job has been started

       APISPQ_PAGEFILE
               Job has a page file

       APISPQ_ERRLIMIT
               Error if size limit exceeded

       APISPQ_PGLIMIT
               Size limit in pages not KB

       Note that the field "apispq_pglim" and the field bits "APISPQ_ERRLIMIT" and
       "APISPQ_PGLIMIT" will always be zero when read with gspool_joblist, but the description is
       included for completeness. The fields are only used when creating jobs.

RETURN VALUES

       The function gspool_jobread() returns 0 if successful, otherwise one of the following
       codes:

       GSPOOL_UNKNOWN_JOB
               job not found

       GSPOOL_INVALID_FD
               Invalid File descriptor

       GSPOOL_BADWRITE
               failure writing to the network

       GSPOOL_BADREAD
               failure reading from the network

       GSPOOL_NOPERM
               The user does not have permission

       GSPOOL_SEQUENCE
               Printer sequence error, slot may be out of date

       GSPOOL_INVALIDSLOT
               Invalid slot number

EXAMPLE

       An example to read the names of all jobs

        int fd, ret, nj, i;
        struct apispq job;
        slotno_t *slots;

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

        ret = gspool_joblist(fd, 0, &nj, &slots);
        if (ret < 0) { /* error handling */
            ...
        }

        for (i = 0; i < nj, i++) {
            ret = gspool_jobread(fd, 0, slots[i], &job);
            if (ret < 0) { /* error handling */
                ...
            }
            printf("%s\n", job.apispq_file);
        }
        gspool_close(fd);

SEE ALSO

       gspool_jobfind(3), gspool_jobfindslot(3), gspool_joblist(3), gspool_jobdata(3),
       gspool_jobadd(3), gspool_jobdel(3), gspool_jobupd(3), gspool_jobmon(3), gspool_jobpbrk(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.