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_AT_DEVICE
152 ´job-canceled-at-device'
153 PAPPL_JREASON_JOB_CANCELED_BY_USER
155 ´job-canceled-by-user'
156 PAPPL_JREASON_JOB_COMPLETED_SUCCESSFULLY
158 ´job-completed-successfully'
159 PAPPL_JREASON_JOB_COMPLETED_WITH_ERRORS
161 ´job-completed-with-errors'
162 PAPPL_JREASON_JOB_COMPLETED_WITH_WARNINGS
164 ´job-completed-with-warnings'
165 PAPPL_JREASON_JOB_DATA_INSUFFICIENT
167 ´job-data-insufficient'
168 PAPPL_JREASON_JOB_HOLD_UNTIL_SPECIFIED
170 ´job-hold-until-specified'
171 PAPPL_JREASON_JOB_INCOMING
173 ´job-incoming'
174 PAPPL_JREASON_JOB_PRINTING
176 ´job-printing'
177 PAPPL_JREASON_JOB_QUEUED
179 ´job-queued'
180 PAPPL_JREASON_JOB_SPOOLING
182 ´job-spooling'
183 PAPPL_JREASON_NONE
185 ´none'
186 PAPPL_JREASON_PRINTER_STOPPED
188 ´printer-stopped'
189 PAPPL_JREASON_PRINTER_STOPPED_PARTLY
191 ´printer-stopped-partly'
192 PAPPL_JREASON_PROCESSING_TO_STOP_POINT
194 ´processing-to-stop-point'
195 PAPPL_JREASON_QUEUED_IN_DEVICE
197 ´queued-in-device'
198 PAPPL_JREASON_WARNINGS_DETECTED
200 ´warnings-detected'
201
203 papplJobCancel
204 Cancel a job.
205 void papplJobCancel (
207 pappl_job_t *job
208 );
209 This function cancels the specified job. If the job is currently being
211 printed, it will be stopped at a convenient time (usually the end of a
212 page) so that the printer will be left in a known state.
213 papplJobCreatePrintOptions
215 Create the printer options for a job.
216 pappl_pr_options_t * papplJobCreatePrintOptions (
218 pappl_job_t *job,
219 unsigned num_pages,
220 bool color
221 );
222 This function allocates a printer options structure and computes the
224 print options for a job based upon the Job Template attributes submit‐
225 ted in the print request and the default values set in the printer
226 driver data.
227 The "num_pages" and "color" arguments specify the number of pages and
229 whether the document contains non-grayscale colors - this information
230 typically comes from parsing the job file.
231 papplJobCreateWithFile
233 Create a job with a local file.
234 pappl_job_t * papplJobCreateWithFile (
236 pappl_printer_t *printer,
237 const char *username,
238 const char *format,
239 const char *job_name,
240 int num_options,
241 cups_option_t *options,
242 const char *filename
243 );
244 This function creates a new print job with a local file. The "num_op‐
246 tions" and "options" parameters specify additional print options, as
247 needed. The file specified by "filename" is removed automatically if
248 it resides in the spool directory.
249 papplJobDeletePrintOptions
251 Delete a job options structure.
252 void papplJobDeletePrintOptions (
254 pappl_pr_options_t *options
255 );
256 This function frees the memory used for a job options structure.
258 papplJobFilterImage
260 Filter an image in memory.
261 bool papplJobFilterImage (
263 pappl_job_t *job,
264 pappl_device_t *device,
265 pappl_pr_options_t *options,
266 const unsigned char *pixels,
267 int width,
268 int height,
269 int depth,
270 int ppi,
271 bool smoothing
272 );
273 This function will print a grayscale or sRGB image using the printer's
275 raster driver interface, scaling and positioning the image as necessary
276 based on the job options, and printing as many copies as requested.
277 The image data is an array of grayscale ("depth" = 1) or sRGB ("depth"
279 = 3) pixels starting at the top-left corner of the image.
280 The image resolution ("ppi") is expressed in pixels per inch and is
282 used for some "print-scaling" modes. Pass 0 if the image has no ex‐
283 plicit resolution information.
284 papplJobGetAttribute
286 Get an attribute from a job.
287 ipp_attribute_t * papplJobGetAttribute (
289 pappl_job_t *job,
290 const char *name
291 );
292 This function gets the named IPP attribute from a job. The returned
294 attribute can be examined using the ippGetXxx functions.
295 papplJobGetData
297 Get per-job driver data.
298 void * papplJobGetData (
300 pappl_job_t *job
301 );
302 This function returns the driver data associated with the job. It is
304 normally only called from drivers to maintain state for the processing
305 of the job, for example to store bitmap compression information.
306 papplJobGetFilename
308 Get the job's filename.
309 const char * papplJobGetFilename (
311 pappl_job_t *job
312 );
313 This function returns the filename for the job's document data.
315 papplJobGetFormat
317 Get the MIME media type for the job's file.
318 const char * papplJobGetFormat (
320 pappl_job_t *job
321 );
322 This function returns the MIME media type for the job's document data.
324 papplJobGetID
326 Get the job ID value.
327 int papplJobGetID (
329 pappl_job_t *job
330 );
331 This function returns the job's unique integer identifier.
333 papplJobGetImpressions
335 Get the number of impressions (sides) in the job.
336 int papplJobGetImpressions (
338 pappl_job_t *job
339 );
340 This function returns the number of impressions in the job's document
342 data. An impression is one side of an output page.
343 papplJobGetImpressionsCompleted
345 Get the number of completed impressions
346 (sides) in the job.
347 int papplJobGetImpressionsCompleted (
349 pappl_job_t *job
350 );
351 This function returns the number of impressions that have been printed.
353 An impression is one side of an output page.
354 papplJobGetMessage
356 Get the current job message string, if any.
357 const char * papplJobGetMessage (
359 pappl_job_t *job
360 );
361 This function returns the current job message string, if any.
363 papplJobGetName
365 Get the job name/title.
366 const char * papplJobGetName (
368 pappl_job_t *job
369 );
370 This function returns the name or title of the job.
372 papplJobGetPrinter
374 Get the printer for the job.
375 pappl_printer_t * papplJobGetPrinter (
377 pappl_job_t *job
378 );
379 This function returns the printer containing the job.
381 papplJobGetReasons
383 Get the current job state reasons.
384 pappl_jreason_t papplJobGetReasons (
386 pappl_job_t *job
387 );
388 This function returns the current job state reasons bitfield.
390 papplJobGetState
392 Get the current job state.
393 ipp_jstate_t papplJobGetState (
395 pappl_job_t *job
396 );
397 This function returns the current job processing state, which is repre‐
399 sented as an enumeration:
400 • IPP_JSTATE_ABORTED: Job has been aborted by the system due to an
402 error.
403 • IPP_JSTATE_CANCELED: Job has been canceled by a user.
405 • IPP_JSTATE_COMPLETED: Job has finished printing.
407 • IPP_JSTATE_HELD: Job is being held for some reason, typically be‐
409 cause
410 the document data is being received.
411 • IPP_JSTATE_PENDING: Job is queued and waiting to be printed.
413 • IPP_JSTATE_PROCESSING: Job is being printed.
415 • IPP_JSTATE_STOPPED: Job is paused, typically when the printer is
417 not
418 ready.</li> </ul>
419 papplJobGetTimeCompleted
421 Get the job completion time, if any.
422 time_t papplJobGetTimeCompleted (
424 pappl_job_t *job
425 );
426 This function returns the date and time when the job reached the com‐
428 pleted, canceled, or aborted states. 0 is returned if the job is not
429 yet in one of those states.
430 papplJobGetTimeCreated
432 Get the job creation time.
433 time_t papplJobGetTimeCreated (
435 pappl_job_t *job
436 );
437 This function returns the date and time when the job was created.
439 papplJobGetTimeProcessed
441 Get the job processing time.
442 time_t papplJobGetTimeProcessed (
444 pappl_job_t *job
445 );
446 This function returns the date and time when the job started processing
448 (printing).
449 papplJobGetUsername
451 Get the name of the user that submitted the job.
452 const char * papplJobGetUsername (
454 pappl_job_t *job
455 );
456 This function returns the name of the user that submitted the job.
458 papplJobHold
460 Hold a job for printing.
461 bool papplJobHold (
463 pappl_job_t *job,
464 const char *username,
465 const char *until,
466 time_t until_time
467 );
468 This function holds a pending job for printing at a later time.
470 papplJobIsCanceled
472 Return whether the job is canceled.
473 bool papplJobIsCanceled (
475 pappl_job_t *job
476 );
477 This function returns true if the job has been canceled or aborted.
479 papplJobOpenFile
481 Create or open a file for the document in a job.
482 int papplJobOpenFile (
484 pappl_job_t *job,
485 char *fname,
486 size_t fnamesize,
487 const char *directory,
488 const char *ext,
489 const char *mode
490 );
491 This function creates or opens a file for a job. The "fname" and
493 "fnamesize" arguments specify the location and size of a buffer to
494 store the job filename, which incorporates the "directory", printer ID,
495 job ID, job name (title), and "ext" values. The job name is "sani‐
496 tized" to only contain alphanumeric characters.
497 The "mode" argument is "r" to read an existing job file or "w" to write
499 a new job file. New files are created with restricted permissions for
500 security purposes.
501 papplJobRelease
503 Release a job for printing.
504 bool papplJobRelease (
506 pappl_job_t *job,
507 const char *username
508 );
509 This function releases a held job for printing.
511 papplJobSetData
513 Set the per-job driver data pointer.
514 void papplJobSetData (
516 pappl_job_t *job,
517 void *data
518 );
519 This function sets the driver data for the specified job. It is nor‐
521 mally only called from drivers to maintain state for the processing of
522 the job, for example to store bitmap compression information.
523 papplJobSetImpressions
525 Set the number of impressions (sides) in a job.
526 void papplJobSetImpressions (
528 pappl_job_t *job,
529 int impressions
530 );
531 This function sets the number of impressions in a job. An impression
533 is one side of an output page.
534 papplJobSetImpressionsCompleted
536 Add completed impressions (sides) to
537 the job.
538 void papplJobSetImpressionsCompleted (
540 pappl_job_t *job,
541 int add
542 );
543 This function updates the number of completed impressions in a job. An
545 impression is one side of an output page.
546 papplJobSetMessage
548 Set the job message string.
549 void papplJobSetMessage (
551 pappl_job_t *job,
552 const char *message,
553 ...
554 );
555 This function sets the job message string using a printf-style format
557 string.
558 5 Note: The maximum length of the job message string is 1023
560 bytes.
561 papplJobSetReasons
563 Set the job state reasons bit values.
564 void papplJobSetReasons (
566 pappl_job_t *job,
567 pappl_jreason_t add,
568 pappl_jreason_t remove
569 );
570 This function updates the job state reasons bitfield. The "remove"
572 bits are cleared first, then the "add" bits are set.
573 papplPrinterFindJob
575 Find a job.
576 pappl_job_t * papplPrinterFindJob (
578 pappl_printer_t *printer,
579 int job_id
580 );
581 This function finds a job submitted to a printer using its integer ID
583 value.
584 papplSystemCleanJobs
586 Clean out old (completed) jobs.
587 void papplSystemCleanJobs (
589 pappl_system_t *system
590 );
591 This function deletes all old (completed) jobs above the limit set by
593 the papplPrinterSetMaxCompletedJobs function. The level may temporar‐
594 ily exceed this limit if the jobs were completed within the last 60
595 seconds.
596 5 Note: This function is normally called automatically from the
598 5 papplSystemRun function.
600
602 pappl_jreason_t
603 Bitfield for IPP "job-state-reasons" values
604 typedef unsigned int pappl_jreason_t;
606
608 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
609 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
610 source(3), pappl-system(3), https://www.msweet.org/pappl
611
613 Copyright © 2019-2022 by Michael R Sweet.
614 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
616 tional) exception to allow linking against GPL2/LGPL2 software (like
617 older versions of CUPS), so it can be used freely in any project you'd
618 like. See the files "LICENSE" and "NOTICE" in the source distribution
619 for more information.
6202022-11-07 pappl job functions pappl-job(3)