gspool_jobread(3)

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: Job number Host address (network byte order) Originating host address Slot number on owning machine Time job was submitted Time job was started (if applicable) Time job held to, 0 if not held Time after to delete job if not printed (hours) Time after to delete job if printed (hours) External job type index Job size limit applies Size of job in bytes Offset reached if currently being printed Currently-reached page if being printed User name of job owner User name of posting user Copies Priority Class code bits 1=A 2=B 4=C etc Job flags Despooler flags Printer slot assigned to if printing Start page 0=first page End page Number of pages "Halted at" page Job title Job form type Printer pattern assigned to job Post-processing flags

The following bits are set in the "apispq_jflags" field to indicate job parameters: Suppress header Write result Mail result Retain on queue after printing Suppress odd pages Suppress even pages Invert APISPQ_ODDP and API_EVENP after printing Mail attention Write attention Handle job on local machine only Job originated with windows client Job originated with DHCP windows client

The "apispq_dflags" field contains the following bits: Job being printed Job has been printed Job has been started Job has a page file Error if size limit exceeded 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: job not found Invalid File descriptor failure writing to the network failure reading from the network The user does not have permission Printer sequence error, slot may be out of date 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.