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:

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.