1pappl-job(3) pappl job functions pappl-job(3)
2
6 pappl-job - pappl job functions
7
9 Printer Application Framework (libpappl, "pkg-config --cflags --libs
10 pappl")
11
13 #include <pappl/pappl.h>
14 typedef struct _pappl_job_s pappl_job_t;
16 void
18 papplJobCancel(pappl_job_t *job);
19 bool
22 papplJobFilterImage(pappl_job_t *job, pappl_device_t *device,
23 pappl_joptions_t *options, const unsigned char *pixels, unsigned width,
24 unsigned height, unsigned depth, bool smoothing);
25 ipp_attribute_t *
28 papplJobGetAttribute(pappl_job_t *job, const char *name);
29 void *
31 papplJobGetData(pappl_job_t *job);
32 const char *
34 papplJobGetFilename(pappl_job_t *job);
35 const char *
37 papplJobGetFormat(pappl_job_t *job);
38 int
40 papplJobGetID(pappl_job_t *job);
41 int
43 papplJobGetImpressions(pappl_job_t *job);
44 int
46 papplJobGetImpressionsCompleted(pappl_job_t *job);
47 const char *
49 papplJobGetMessage(pappl_job_t *job);
50 const char *
52 papplJobGetName(pappl_job_t *job);
53 pappl_joptions_t *
55 papplJobGetOptions(pappl_job_t *job, pappl_joptions_t *options, un‐
56 signed num_pages, bool color);
57 pappl_printer_t *
59 papplJobGetPrinter(pappl_job_t *job);
60 pappl_jreason_t
62 papplJobGetReasons(pappl_job_t *job);
63 ipp_jstate_t
65 papplJobGetState(pappl_job_t *job);
66 time_t
68 papplJobGetTimeCompleted(pappl_job_t *job);
69 time_t
71 papplJobGetTimeCreated(pappl_job_t *job);
72 time_t
74 papplJobGetTimeProcessed(pappl_job_t *job);
75 const char *
77 papplJobGetUsername(pappl_job_t *job);
78 bool
80 papplJobIsCanceled(pappl_job_t *job);
81 int
84 papplJobOpenFile(pappl_job_t *job, char *fname, size_t fnamesize, const
85 char *directory, const char *ext, const char *mode);
86 void
89 papplJobSetData(pappl_job_t *job, void *data);
90 void
92 papplJobSetImpressions(pappl_job_t *job, int impressions);
93 void
95 papplJobSetImpressionsCompleted(pappl_job_t *job, int add);
96 void
98 papplJobSetMessage(pappl_job_t *job, const char *message, ...);
99 void
101 papplJobSetReasons(pappl_job_t *job, pappl_jreason_t add, pappl_jrea‐
102 son_t remove);
103
106 The PAPPL job functions provide access to the job object. Jobs and the
107 life cycle of the pappl_job_t objects are managed automatically by the
108 system object for the printer application.
109 The papplJobGet functions get the current values associated with a job
111 while the papplJobSet functions set the current values associated with
112 a job.
113 The papplJobCancel function cancels processing of a job, while the pap‐
115 plJobIsCanceled function returns whether a job is in the canceled state
116 (IPP_JSTATE_CANCELED) or is in the process of being canceled (IPP_JS‐
117 TATE_PROCESSING and PAPPL_JREASON_PROCESSING_TO_STOP_POINT).
118 The papplJobOpenFile function opens a file associated with the job.
120 The file descriptor must be closed by the caller using the close(2)
121 system call.
122 The papplJobFilterImage function converts raw image data to raster data
124 suitable for the printer.
125
127 pappl_jreason_e
128 IPP "job-state-reasons" bit values
129 PAPPL_JREASON_ABORTED_BY_SYSTEM
131 ´aborted-by-system'
132 PAPPL_JREASON_COMPRESSION_ERROR
134 ´compression-error'
135 PAPPL_JREASON_DOCUMENT_FORMAT_ERROR
137 ´document-format-error'
138 PAPPL_JREASON_DOCUMENT_PASSWORD_ERROR
140 ´document-password-error'
141 PAPPL_JREASON_DOCUMENT_PERMISSION_ERROR
143 ´document-permission-error'
144 PAPPL_JREASON_DOCUMENT_UNPRINTABLE_ERROR
146 ´document-unprintable-error'
147 PAPPL_JREASON_ERRORS_DETECTED
149 ´errors-detected'
150 PAPPL_JREASON_JOB_CANCELED_AFTER_TIMEOUT
152 ´job-canceled-after-timeout'
153 PAPPL_JREASON_JOB_CANCELED_AT_DEVICE
155 ´job-canceled-at-device'
156 PAPPL_JREASON_JOB_CANCELED_BY_USER
158 ´job-canceled-by-user'
159 PAPPL_JREASON_JOB_COMPLETED_SUCCESSFULLY
161 ´job-completed-successfully'
162 PAPPL_JREASON_JOB_COMPLETED_WITH_ERRORS
164 ´job-completed-with-errors'
165 PAPPL_JREASON_JOB_COMPLETED_WITH_WARNINGS
167 ´job-completed-with-warnings'
168 PAPPL_JREASON_JOB_DATA_INSUFFICIENT
170 ´job-data-insufficient'
171 PAPPL_JREASON_JOB_FETCHABLE
173 ´job-fetchable'
174 PAPPL_JREASON_JOB_HOLD_UNTIL_SPECIFIED
176 ´job-hold-until-specified'
177 PAPPL_JREASON_JOB_INCOMING
179 ´job-incoming'
180 PAPPL_JREASON_JOB_PRINTING
182 ´job-printing'
183 PAPPL_JREASON_JOB_QUEUED
185 ´job-queued'
186 PAPPL_JREASON_JOB_SPOOLING
188 ´job-spooling'
189 PAPPL_JREASON_JOB_SUSPENDED_FOR_APPROVAL
191 ´job-suspended-for-approval'
192 PAPPL_JREASON_NONE
194 ´none'
195 PAPPL_JREASON_PRINTER_STOPPED
197 ´printer-stopped'
198 PAPPL_JREASON_PRINTER_STOPPED_PARTLY
200 ´printer-stopped-partly'
201 PAPPL_JREASON_PROCESSING_TO_STOP_POINT
203 ´processing-to-stop-point'
204 PAPPL_JREASON_QUEUED_IN_DEVICE
206 ´queued-in-device'
207 PAPPL_JREASON_WARNINGS_DETECTED
209 ´warnings-detected'
210
212 papplJobCancel
213 Cancel a job.
214 void papplJobCancel (
216 pappl_job_t *job
217 );
218 This function cancels the specified job. If the job is currently being
220 printed, it will be stopped at a convenient time (usually the end of a
221 page) so that the printer will be left in a known state.
222 papplJobCreatePrintOptions
224 Create the printer options for a job.
225 pappl_pr_options_t * papplJobCreatePrintOptions (
227 pappl_job_t *job,
228 unsigned num_pages,
229 bool color
230 );
231 This function allocates a printer options structure and computes the
233 print options for a job based upon the Job Template attributes submit‐
234 ted in the print request and the default values set in the printer
235 driver data.
236 The "num_pages" and "color" arguments specify the number of pages and
238 whether the document contains non-grayscale colors - this information
239 typically comes from parsing the job file.
240 papplJobCreateWithFile
242 Create a job with a local file.
243 pappl_job_t * papplJobCreateWithFile (
245 pappl_printer_t *printer,
246 const char *username,
247 const char *format,
248 const char *job_name,
249 int num_options,
250 cups_option_t *options,
251 const char *filename
252 );
253 This function creates a new print job with a local file. The "num_op‐
255 tions" and "options" parameters specify additional print options, as
256 needed. The file specified by "filename" is removed automatically if
257 it resides in the spool directory.
258 papplJobDeletePrintOptions
260 Delete a job options structure.
261 void papplJobDeletePrintOptions (
263 pappl_pr_options_t *options
264 );
265 This function frees the memory used for a job options structure.
267 papplJobFilterImage
269 Filter an image in memory.
270 bool papplJobFilterImage (
272 pappl_job_t *job,
273 pappl_device_t *device,
274 pappl_pr_options_t *options,
275 const unsigned char *pixels,
276 int width,
277 int height,
278 int depth,
279 int ppi,
280 bool smoothing
281 );
282 This function will print a grayscale or sRGB image using the printer's
284 raster driver interface, scaling and positioning the image as necessary
285 based on the job options, and printing as many copies as requested.
286 The image data is an array of grayscale ("depth" = 1) or sRGB ("depth"
288 = 3) pixels starting at the top-left corner of the image.
289 The image resolution ("ppi") is expressed in pixels per inch and is
291 used for some "print-scaling" modes. Pass 0 if the image has no ex‐
292 plicit resolution information.
293 papplJobGetAttribute
295 Get an attribute from a job.
296 ipp_attribute_t * papplJobGetAttribute (
298 pappl_job_t *job,
299 const char *name
300 );
301 This function gets the named IPP attribute from a job. The returned
303 attribute can be examined using the ippGetXxx functions.
304 papplJobGetCopies
306 Get the number of copies in the job.
307 int papplJobGetCopies (
309 pappl_job_t *job
310 );
311 This function returns the number of copies to produce of the job's doc‐
313 ument data.
314 papplJobGetCopiesCompleted
316 Get the number of completed copies.
317 int papplJobGetCopiesCompleted (
319 pappl_job_t *job
320 );
321 This function returns the number of copies that have been completed.
323 papplJobGetData
325 Get per-job driver data.
326 void * papplJobGetData (
328 pappl_job_t *job
329 );
330 This function returns the driver data associated with the job. It is
332 normally only called from drivers to maintain state for the processing
333 of the job, for example to store bitmap compression information.
334 papplJobGetFilename
336 Get the job's filename.
337 const char * papplJobGetFilename (
339 pappl_job_t *job
340 );
341 This function returns the filename for the job's document data.
343 papplJobGetFormat
345 Get the MIME media type for the job's file.
346 const char * papplJobGetFormat (
348 pappl_job_t *job
349 );
350 This function returns the MIME media type for the job's document data.
352 papplJobGetID
354 Get the job ID value.
355 int papplJobGetID (
357 pappl_job_t *job
358 );
359 This function returns the job's unique integer identifier.
361 papplJobGetImpressions
363 Get the number of impressions (sides) in the job.
364 int papplJobGetImpressions (
366 pappl_job_t *job
367 );
368 This function returns the number of impressions in the job's document
370 data. An impression is one side of an output page.
371 papplJobGetImpressionsCompleted
373 Get the number of completed impressions
374 (sides) in the job.
375 int papplJobGetImpressionsCompleted (
377 pappl_job_t *job
378 );
379 This function returns the number of impressions that have been printed.
381 An impression is one side of an output page.
382 papplJobGetMessage
384 Get the current job message string, if any.
385 const char * papplJobGetMessage (
387 pappl_job_t *job
388 );
389 This function returns the current job message string, if any.
391 papplJobGetName
393 Get the job name/title.
394 const char * papplJobGetName (
396 pappl_job_t *job
397 );
398 This function returns the name or title of the job.
400 papplJobGetPrinter
402 Get the printer for the job.
403 pappl_printer_t * papplJobGetPrinter (
405 pappl_job_t *job
406 );
407 This function returns the printer containing the job.
409 papplJobGetReasons
411 Get the current job state reasons.
412 pappl_jreason_t papplJobGetReasons (
414 pappl_job_t *job
415 );
416 This function returns the current job state reasons bitfield.
418 papplJobGetState
420 Get the current job state.
421 ipp_jstate_t papplJobGetState (
423 pappl_job_t *job
424 );
425 This function returns the current job processing state, which is repre‐
427 sented as an enumeration:
428 • IPP_JSTATE_ABORTED: Job has been aborted by the system due to an
430 error.
431 • IPP_JSTATE_CANCELED: Job has been canceled by a user.
433 • IPP_JSTATE_COMPLETED: Job has finished printing.
435 • IPP_JSTATE_HELD: Job is being held for some reason, typically be‐
437 cause
438 the document data is being received.
439 • IPP_JSTATE_PENDING: Job is queued and waiting to be printed.
441 • IPP_JSTATE_PROCESSING: Job is being printed.
443 • IPP_JSTATE_STOPPED: Job is paused, typically when the printer is
445 not
446 ready.</li> </ul>
447 papplJobGetTimeCompleted
449 Get the job completion time, if any.
450 time_t papplJobGetTimeCompleted (
452 pappl_job_t *job
453 );
454 This function returns the date and time when the job reached the com‐
456 pleted, canceled, or aborted states. 0 is returned if the job is not
457 yet in one of those states.
458 papplJobGetTimeCreated
460 Get the job creation time.
461 time_t papplJobGetTimeCreated (
463 pappl_job_t *job
464 );
465 This function returns the date and time when the job was created.
467 papplJobGetTimeProcessed
469 Get the job processing time.
470 time_t papplJobGetTimeProcessed (
472 pappl_job_t *job
473 );
474 This function returns the date and time when the job started processing
476 (printing).
477 papplJobGetUsername
479 Get the name of the user that submitted the job.
480 const char * papplJobGetUsername (
482 pappl_job_t *job
483 );
484 This function returns the name of the user that submitted the job.
486 papplJobHold
488 Hold a job for printing.
489 bool papplJobHold (
491 pappl_job_t *job,
492 const char *username,
493 const char *until,
494 time_t until_time
495 );
496 This function holds a pending job for printing at a later time.
498 papplJobIsCanceled
500 Return whether the job is canceled.
501 bool papplJobIsCanceled (
503 pappl_job_t *job
504 );
505 This function returns true if the job has been canceled or aborted.
507 papplJobOpenFile
509 Create or open a file for the document in a job.
510 int papplJobOpenFile (
512 pappl_job_t *job,
513 char *fname,
514 size_t fnamesize,
515 const char *directory,
516 const char *ext,
517 const char *mode
518 );
519 This function creates or opens a file for a job. The "fname" and
521 "fnamesize" arguments specify the location and size of a buffer to
522 store the job filename, which incorporates the "directory", printer ID,
523 job ID, job name (title), and "ext" values. The job name is "sani‐
524 tized" to only contain alphanumeric characters.
525 The "mode" argument is "r" to read an existing job file or "w" to write
527 a new job file. New files are created with restricted permissions for
528 security purposes.
529 papplJobRelease
531 Release a job for printing.
532 bool papplJobRelease (
534 pappl_job_t *job,
535 const char *username
536 );
537 This function releases a held job for printing.
539 papplJobResume
541 Resume processing of a job.
542 void papplJobResume (
544 pappl_job_t *job,
545 pappl_jreason_t remove
546 );
547 papplJobRetain
549 Retain a completed job until the specified time.
550 bool papplJobRetain (
552 pappl_job_t *job,
553 const char *username,
554 const char *until,
555 int until_interval,
556 time_t until_time
557 );
558 papplJobSetCopiesCompleted
560 Add completed copies to the job.
561 void papplJobSetCopiesCompleted (
563 pappl_job_t *job,
564 int add
565 );
566 This function updates the number of completed impressions in a job. An
568 impression is one side of an output page.
569 papplJobSetData
571 Set the per-job driver data pointer.
572 void papplJobSetData (
574 pappl_job_t *job,
575 void *data
576 );
577 This function sets the driver data for the specified job. It is nor‐
579 mally only called from drivers to maintain state for the processing of
580 the job, for example to store bitmap compression information.
581 papplJobSetImpressions
583 Set the number of impressions (sides) in a job.
584 void papplJobSetImpressions (
586 pappl_job_t *job,
587 int impressions
588 );
589 This function sets the number of impressions in a job. An impression
591 is one side of an output page.
592 papplJobSetImpressionsCompleted
594 Add completed impressions (sides) to
595 the job.
596 void papplJobSetImpressionsCompleted (
598 pappl_job_t *job,
599 int add
600 );
601 This function updates the number of completed impressions in a job. An
603 impression is one side of an output page.
604 papplJobSetMessage
606 Set the job message string.
607 void papplJobSetMessage (
609 pappl_job_t *job,
610 const char *message,
611 ...
612 );
613 This function sets the job message string using a printf-style format
615 string.
616 5 Note: The maximum length of the job message string is 1023
618 bytes.
619 papplJobSetReasons
621 Set the job state reasons bit values.
622 void papplJobSetReasons (
624 pappl_job_t *job,
625 pappl_jreason_t add,
626 pappl_jreason_t remove
627 );
628 This function updates the job state reasons bitfield. The "remove"
630 bits are cleared first, then the "add" bits are set.
631 papplJobSuspend
633 Temporarily stop processing of a job.
634 void papplJobSuspend (
636 pappl_job_t *job,
637 pappl_jreason_t add
638 );
639 papplPrinterFindJob
641 Find a job.
642 pappl_job_t * papplPrinterFindJob (
644 pappl_printer_t *printer,
645 int job_id
646 );
647 This function finds a job submitted to a printer using its integer ID
649 value.
650 papplSystemCleanJobs
652 Clean out old (completed) jobs.
653 void papplSystemCleanJobs (
655 pappl_system_t *system
656 );
657 This function deletes all old (completed) jobs above the limit set by
659 the papplPrinterSetMaxCompletedJobs function. The level may temporar‐
660 ily exceed this limit if the jobs were completed within the last 60
661 seconds.
662 5 Note: This function is normally called automatically from the
664 5 papplSystemRun function.
666
668 pappl_jreason_t
669 Bitfield for IPP "job-state-reasons" values
670 typedef unsigned int pappl_jreason_t;
672
674 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
675 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
676 source(3), pappl-system(3), https://www.msweet.org/pappl
677
679 Copyright © 2019-2022 by Michael R Sweet.
680 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
682 tional) exception to allow linking against GPL2/LGPL2 software (like
683 older versions of CUPS), so it can be used freely in any project you'd
684 like. See the files "LICENSE" and "NOTICE" in the source distribution
685 for more information.
6862023-10-06 pappl job functions pappl-job(3)