Provided by: libpappl-dev_1.3.1-2_amd64 
NAME
pappl-job - pappl job functions
LIBRARY
Printer Application Framework (libpappl, "pkg-config --cflags --libs pappl")
SYNOPSIS
#include <pappl/pappl.h>
typedef struct _pappl_job_s pappl_job_t;
void
papplJobCancel(pappl_job_t *job);
bool
papplJobFilterImage(pappl_job_t *job, pappl_device_t *device, pappl_joptions_t *options,
const unsigned char *pixels, unsigned width, unsigned height, unsigned depth, bool
smoothing);
ipp_attribute_t *
papplJobGetAttribute(pappl_job_t *job, const char *name);
void *
papplJobGetData(pappl_job_t *job);
const char *
papplJobGetFilename(pappl_job_t *job);
const char *
papplJobGetFormat(pappl_job_t *job);
int
papplJobGetID(pappl_job_t *job);
int
papplJobGetImpressions(pappl_job_t *job);
int
papplJobGetImpressionsCompleted(pappl_job_t *job);
const char *
papplJobGetMessage(pappl_job_t *job);
const char *
papplJobGetName(pappl_job_t *job);
pappl_joptions_t *
papplJobGetOptions(pappl_job_t *job, pappl_joptions_t *options, unsigned num_pages, bool
color);
pappl_printer_t *
papplJobGetPrinter(pappl_job_t *job);
pappl_jreason_t
papplJobGetReasons(pappl_job_t *job);
ipp_jstate_t
papplJobGetState(pappl_job_t *job);
time_t
papplJobGetTimeCompleted(pappl_job_t *job);
time_t
papplJobGetTimeCreated(pappl_job_t *job);
time_t
papplJobGetTimeProcessed(pappl_job_t *job);
const char *
papplJobGetUsername(pappl_job_t *job);
bool
papplJobIsCanceled(pappl_job_t *job);
int
papplJobOpenFile(pappl_job_t *job, char *fname, size_t fnamesize, const char *directory,
const char *ext, const char *mode);
void
papplJobSetData(pappl_job_t *job, void *data);
void
papplJobSetImpressions(pappl_job_t *job, int impressions);
void
papplJobSetImpressionsCompleted(pappl_job_t *job, int add);
void
papplJobSetMessage(pappl_job_t *job, const char *message, ...);
void
papplJobSetReasons(pappl_job_t *job, pappl_jreason_t add, pappl_jreason_t remove);
DESCRIPTION
The PAPPL job functions provide access to the job object. Jobs and the life cycle of the
pappl_job_t objects are managed automatically by the system object for the printer
application.
The papplJobGet functions get the current values associated with a job while the
papplJobSet functions set the current values associated with a job.
The papplJobCancel function cancels processing of a job, while the papplJobIsCanceled
function returns whether a job is in the canceled state (IPP_JSTATE_CANCELED) or is in the
process of being canceled (IPP_JSTATE_PROCESSING and
PAPPL_JREASON_PROCESSING_TO_STOP_POINT).
The papplJobOpenFile function opens a file associated with the job. The file descriptor
must be closed by the caller using the close(2) system call.
The papplJobFilterImage function converts raw image data to raster data suitable for the
printer.
ENUMERATIONS
pappl_jreason_e
IPP "job-state-reasons" bit values
PAPPL_JREASON_ABORTED_BY_SYSTEM
´aborted-by-system'
PAPPL_JREASON_COMPRESSION_ERROR
´compression-error'
PAPPL_JREASON_DOCUMENT_FORMAT_ERROR
´document-format-error'
PAPPL_JREASON_DOCUMENT_PASSWORD_ERROR
´document-password-error'
PAPPL_JREASON_DOCUMENT_PERMISSION_ERROR
´document-permission-error'
PAPPL_JREASON_DOCUMENT_UNPRINTABLE_ERROR
´document-unprintable-error'
PAPPL_JREASON_ERRORS_DETECTED
´errors-detected'
PAPPL_JREASON_JOB_CANCELED_AT_DEVICE
´job-canceled-at-device'
PAPPL_JREASON_JOB_CANCELED_BY_USER
´job-canceled-by-user'
PAPPL_JREASON_JOB_COMPLETED_SUCCESSFULLY
´job-completed-successfully'
PAPPL_JREASON_JOB_COMPLETED_WITH_ERRORS
´job-completed-with-errors'
PAPPL_JREASON_JOB_COMPLETED_WITH_WARNINGS
´job-completed-with-warnings'
PAPPL_JREASON_JOB_DATA_INSUFFICIENT
´job-data-insufficient'
PAPPL_JREASON_JOB_HOLD_UNTIL_SPECIFIED
´job-hold-until-specified'
PAPPL_JREASON_JOB_INCOMING
´job-incoming'
PAPPL_JREASON_JOB_PRINTING
´job-printing'
PAPPL_JREASON_JOB_QUEUED
´job-queued'
PAPPL_JREASON_JOB_SPOOLING
´job-spooling'
PAPPL_JREASON_NONE
´none'
PAPPL_JREASON_PRINTER_STOPPED
´printer-stopped'
PAPPL_JREASON_PRINTER_STOPPED_PARTLY
´printer-stopped-partly'
PAPPL_JREASON_PROCESSING_TO_STOP_POINT
´processing-to-stop-point'
PAPPL_JREASON_QUEUED_IN_DEVICE
´queued-in-device'
PAPPL_JREASON_WARNINGS_DETECTED
´warnings-detected'
FUNCTIONS
papplJobCancel
Cancel a job.
void papplJobCancel (
pappl_job_t *job
);
This function cancels the specified job. If the job is currently being printed, it will
be stopped at a convenient time (usually the end of a page) so that the printer will be
left in a known state.
papplJobCreatePrintOptions
Create the printer options for a job.
pappl_pr_options_t * papplJobCreatePrintOptions (
pappl_job_t *job,
unsigned num_pages,
bool color
);
This function allocates a printer options structure and computes the print options for a
job based upon the Job Template attributes submitted in the print request and the default
values set in the printer driver data.
The "num_pages" and "color" arguments specify the number of pages and whether the document
contains non-grayscale colors - this information typically comes from parsing the job
file.
papplJobCreateWithFile
Create a job with a local file.
pappl_job_t * papplJobCreateWithFile (
pappl_printer_t *printer,
const char *username,
const char *format,
const char *job_name,
int num_options,
cups_option_t *options,
const char *filename
);
This function creates a new print job with a local file. The "num_options" and "options"
parameters specify additional print options, as needed. The file specified by "filename"
is removed automatically if it resides in the spool directory.
papplJobDeletePrintOptions
Delete a job options structure.
void papplJobDeletePrintOptions (
pappl_pr_options_t *options
);
This function frees the memory used for a job options structure.
papplJobFilterImage
Filter an image in memory.
bool papplJobFilterImage (
pappl_job_t *job,
pappl_device_t *device,
pappl_pr_options_t *options,
const unsigned char *pixels,
int width,
int height,
int depth,
int ppi,
bool smoothing
);
This function will print a grayscale or sRGB image using the printer's raster driver
interface, scaling and positioning the image as necessary based on the job options, and
printing as many copies as requested.
The image data is an array of grayscale ("depth" = 1) or sRGB ("depth" = 3) pixels
starting at the top-left corner of the image.
The image resolution ("ppi") is expressed in pixels per inch and is used for some "print-
scaling" modes. Pass 0 if the image has no explicit resolution information.
papplJobGetAttribute
Get an attribute from a job.
ipp_attribute_t * papplJobGetAttribute (
pappl_job_t *job,
const char *name
);
This function gets the named IPP attribute from a job. The returned attribute can be
examined using the ippGetXxx functions.
papplJobGetData
Get per-job driver data.
void * papplJobGetData (
pappl_job_t *job
);
This function returns the driver data associated with the job. It is normally only called
from drivers to maintain state for the processing of the job, for example to store bitmap
compression information.
papplJobGetFilename
Get the job's filename.
const char * papplJobGetFilename (
pappl_job_t *job
);
This function returns the filename for the job's document data.
papplJobGetFormat
Get the MIME media type for the job's file.
const char * papplJobGetFormat (
pappl_job_t *job
);
This function returns the MIME media type for the job's document data.
papplJobGetID
Get the job ID value.
int papplJobGetID (
pappl_job_t *job
);
This function returns the job's unique integer identifier.
papplJobGetImpressions
Get the number of impressions (sides) in the job.
int papplJobGetImpressions (
pappl_job_t *job
);
This function returns the number of impressions in the job's document data. An impression
is one side of an output page.
papplJobGetImpressionsCompleted
Get the number of completed impressions
(sides) in the job.
int papplJobGetImpressionsCompleted (
pappl_job_t *job
);
This function returns the number of impressions that have been printed. An impression is
one side of an output page.
papplJobGetMessage
Get the current job message string, if any.
const char * papplJobGetMessage (
pappl_job_t *job
);
This function returns the current job message string, if any.
papplJobGetName
Get the job name/title.
const char * papplJobGetName (
pappl_job_t *job
);
This function returns the name or title of the job.
papplJobGetPrinter
Get the printer for the job.
pappl_printer_t * papplJobGetPrinter (
pappl_job_t *job
);
This function returns the printer containing the job.
papplJobGetReasons
Get the current job state reasons.
pappl_jreason_t papplJobGetReasons (
pappl_job_t *job
);
This function returns the current job state reasons bitfield.
papplJobGetState
Get the current job state.
ipp_jstate_t papplJobGetState (
pappl_job_t *job
);
This function returns the current job processing state, which is represented as an
enumeration:
• IPP_JSTATE_ABORTED: Job has been aborted by the system due to an error.
• IPP_JSTATE_CANCELED: Job has been canceled by a user.
• IPP_JSTATE_COMPLETED: Job has finished printing.
• IPP_JSTATE_HELD: Job is being held for some reason, typically because
the document data is being received.
• IPP_JSTATE_PENDING: Job is queued and waiting to be printed.
• IPP_JSTATE_PROCESSING: Job is being printed.
• IPP_JSTATE_STOPPED: Job is paused, typically when the printer is not
ready.</li> </ul>
papplJobGetTimeCompleted
Get the job completion time, if any.
time_t papplJobGetTimeCompleted (
pappl_job_t *job
);
This function returns the date and time when the job reached the completed, canceled, or
aborted states. 0 is returned if the job is not yet in one of those states.
papplJobGetTimeCreated
Get the job creation time.
time_t papplJobGetTimeCreated (
pappl_job_t *job
);
This function returns the date and time when the job was created.
papplJobGetTimeProcessed
Get the job processing time.
time_t papplJobGetTimeProcessed (
pappl_job_t *job
);
This function returns the date and time when the job started processing (printing).
papplJobGetUsername
Get the name of the user that submitted the job.
const char * papplJobGetUsername (
pappl_job_t *job
);
This function returns the name of the user that submitted the job.
papplJobHold
Hold a job for printing.
bool papplJobHold (
pappl_job_t *job,
const char *username,
const char *until,
time_t until_time
);
This function holds a pending job for printing at a later time.
papplJobIsCanceled
Return whether the job is canceled.
bool papplJobIsCanceled (
pappl_job_t *job
);
This function returns true if the job has been canceled or aborted.
papplJobOpenFile
Create or open a file for the document in a job.
int papplJobOpenFile (
pappl_job_t *job,
char *fname,
size_t fnamesize,
const char *directory,
const char *ext,
const char *mode
);
This function creates or opens a file for a job. The "fname" and "fnamesize" arguments
specify the location and size of a buffer to store the job filename, which incorporates
the "directory", printer ID, job ID, job name (title), and "ext" values. The job name is
"sanitized" to only contain alphanumeric characters.
The "mode" argument is "r" to read an existing job file or "w" to write a new job file.
New files are created with restricted permissions for security purposes.
papplJobRelease
Release a job for printing.
bool papplJobRelease (
pappl_job_t *job,
const char *username
);
This function releases a held job for printing.
papplJobSetData
Set the per-job driver data pointer.
void papplJobSetData (
pappl_job_t *job,
void *data
);
This function sets the driver data for the specified job. It is normally only called from
drivers to maintain state for the processing of the job, for example to store bitmap
compression information.
papplJobSetImpressions
Set the number of impressions (sides) in a job.
void papplJobSetImpressions (
pappl_job_t *job,
int impressions
);
This function sets the number of impressions in a job. An impression is one side of an
output page.
papplJobSetImpressionsCompleted
Add completed impressions (sides) to
the job.
void papplJobSetImpressionsCompleted (
pappl_job_t *job,
int add
);
This function updates the number of completed impressions in a job. An impression is one
side of an output page.
papplJobSetMessage
Set the job message string.
void papplJobSetMessage (
pappl_job_t *job,
const char *message,
...
);
This function sets the job message string using a printf-style format string.
5 Note: The maximum length of the job message string is 1023 bytes.
papplJobSetReasons
Set the job state reasons bit values.
void papplJobSetReasons (
pappl_job_t *job,
pappl_jreason_t add,
pappl_jreason_t remove
);
This function updates the job state reasons bitfield. The "remove" bits are cleared
first, then the "add" bits are set.
papplPrinterFindJob
Find a job.
pappl_job_t * papplPrinterFindJob (
pappl_printer_t *printer,
int job_id
);
This function finds a job submitted to a printer using its integer ID value.
papplSystemCleanJobs
Clean out old (completed) jobs.
void papplSystemCleanJobs (
pappl_system_t *system
);
This function deletes all old (completed) jobs above the limit set by the
papplPrinterSetMaxCompletedJobs function. The level may temporarily exceed this limit if
the jobs were completed within the last 60 seconds.
5 Note: This function is normally called automatically from the
5 papplSystemRun function.
TYPES
pappl_jreason_t
Bitfield for IPP "job-state-reasons" values
typedef unsigned int pappl_jreason_t;
SEE ALSO
pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3), pappl-mainline(3),
pappl-makeresheader(1), pappl-printer(3), pappl-resource(3), pappl-system(3),
https://www.msweet.org/pappl
COPYRIGHT
Copyright © 2019-2022 by Michael R Sweet.
PAPPL is licensed under the Apache License Version 2.0 with an (optional) exception to
allow linking against GPL2/LGPL2 software (like older versions of CUPS), so it can be used
freely in any project you'd like. See the files "LICENSE" and "NOTICE" in the source
distribution for more information.