Provided by: libpappl-dev_1.3.1-2_amd64 bug

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.