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_AFTER_TIMEOUT

´job-canceled-after-timeout'

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_FETCHABLE

´job-fetchable'

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_JOB_SUSPENDED_FOR_APPROVAL

´job-suspended-for-approval'

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'

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.

papplJobGetCopies

Get the number of copies in the job.

int  papplJobGetCopies (
    pappl_job_t *job
);

This function returns the number of copies to produce of the job's document data.

papplJobGetCopiesCompleted

Get the number of completed copies.

int  papplJobGetCopiesCompleted (
    pappl_job_t *job
);

This function returns the number of copies that have been completed.

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.

papplJobResume

Resume processing of a job.

void papplJobResume (
    pappl_job_t *job,
    pappl_jreason_t remove
);

papplJobRetain

Retain a completed job until the specified time.

bool  papplJobRetain (
    pappl_job_t *job,
    const char *username,
    const char *until,
    int until_interval,
    time_t until_time
);

papplJobSetCopiesCompleted

Add completed copies to the job.

void papplJobSetCopiesCompleted (
    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.

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.

papplJobSuspend

Temporarily stop processing of a job.

void papplJobSuspend (
    pappl_job_t *job,
    pappl_jreason_t add
);

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.

pappl_jreason_t

Bitfield for IPP "job-state-reasons" values

typedef unsigned int pappl_jreason_t;