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