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_INCOMING
170 ´job-incoming'
171 PAPPL_JREASON_JOB_PRINTING
173 ´job-printing'
174 PAPPL_JREASON_JOB_QUEUED
176 ´job-queued'
177 PAPPL_JREASON_JOB_SPOOLING
179 ´job-spooling'
180 PAPPL_JREASON_NONE
182 ´none'
183 PAPPL_JREASON_PRINTER_STOPPED
185 ´printer-stopped'
186 PAPPL_JREASON_PRINTER_STOPPED_PARTLY
188 ´printer-stopped-partly'
189 PAPPL_JREASON_PROCESSING_TO_STOP_POINT
191 ´processing-to-stop-point'
192 PAPPL_JREASON_QUEUED_IN_DEVICE
194 ´queued-in-device'
195 PAPPL_JREASON_WARNINGS_DETECTED
197 ´warnings-detected'
198
200 papplJobCancel
201 Cancel a job.
202 void papplJobCancel (
204 pappl_job_t *job
205 );
206 This function cancels the specified job. If the job is currently being
208 printed, it will be stopped at a convenient time (usually the end of a
209 page) so that the printer will be left in a known state.
210 papplJobCreatePrintOptions
212 Create the printer options for a job.
213 pappl_pr_options_t * papplJobCreatePrintOptions (
215 pappl_job_t *job,
216 unsigned num_pages,
217 bool color
218 );
219 This function allocates a printer options structure and computes the
221 print options for a job based upon the Job Template attributes submit‐
222 ted in the print request and the default values set in the printer
223 driver data.
224 The "num_pages" and "color" arguments specify the number of pages and
226 whether the document contains non-grayscale colors - this information
227 typically comes from parsing the job file.
228 papplJobCreateWithFile
230 Create a job with a local file.
231 pappl_job_t * papplJobCreateWithFile (
233 pappl_printer_t *printer,
234 const char *username,
235 const char *format,
236 const char *job_name,
237 int num_options,
238 cups_option_t *options,
239 const char *filename
240 );
241 This function creates a new print job with a local file. The "num_op‐
243 tions" and "options" parameters specify additional print options, as
244 needed. The file specified by "filename" is removed automatically if
245 it resides in the spool directory.
246 papplJobDeletePrintOptions
248 Delete a job options structure.
249 void papplJobDeletePrintOptions (
251 pappl_pr_options_t *options
252 );
253 This function frees the memory used for a job options structure.
255 papplJobFilterImage
257 Filter an image in memory.
258 bool papplJobFilterImage (
260 pappl_job_t *job,
261 pappl_device_t *device,
262 pappl_pr_options_t *options,
263 const unsigned char *pixels,
264 int width,
265 int height,
266 int depth,
267 int ppi,
268 bool smoothing
269 );
270 This function will print a grayscale or sRGB image using the printer's
272 raster driver interface, scaling and positioning the image as necessary
273 based on the job options, and printing as many copies as requested.
274 The image data is an array of grayscale ("depth" = 1) or sRGB ("depth"
276 = 3) pixels starting at the top-left corner of the image.
277 The image resolution ("ppi") is expressed in pixels per inch and is
279 used for some "print-scaling" modes. Pass 0 if the image has no ex‐
280 plicit resolution information.
281 papplJobGetAttribute
283 Get an attribute from a job.
284 ipp_attribute_t * papplJobGetAttribute (
286 pappl_job_t *job,
287 const char *name
288 );
289 This function gets the named IPP attribute from a job. The returned
291 attribute can be examined using the ippGetXxx functions.
292 papplJobGetData
294 Get per-job driver data.
295 void * papplJobGetData (
297 pappl_job_t *job
298 );
299 This function returns the driver data associated with the job. It is
301 normally only called from drivers to maintain state for the processing
302 of the job, for example to store bitmap compression information.
303 papplJobGetFilename
305 Get the job's filename.
306 const char * papplJobGetFilename (
308 pappl_job_t *job
309 );
310 This function returns the filename for the job's document data.
312 papplJobGetFormat
314 Get the MIME media type for the job's file.
315 const char * papplJobGetFormat (
317 pappl_job_t *job
318 );
319 This function returns the MIME media type for the job's document data.
321 papplJobGetID
323 Get the job ID value.
324 int papplJobGetID (
326 pappl_job_t *job
327 );
328 This function returns the job's unique integer identifier.
330 papplJobGetImpressions
332 Get the number of impressions (sides) in the job.
333 int papplJobGetImpressions (
335 pappl_job_t *job
336 );
337 This function returns the number of impressions in the job's document
339 data. An impression is one side of an output page.
340 papplJobGetImpressionsCompleted
342 Get the number of completed impressions (sides) in the job.
343 int papplJobGetImpressionsCompleted (
345 pappl_job_t *job
346 );
347 This function returns the number of impressions that have been printed.
349 An impression is one side of an output page.
350 papplJobGetMessage
352 Get the current job message string, if any.
353 const char * papplJobGetMessage (
355 pappl_job_t *job
356 );
357 This function returns the current job message string, if any.
359 papplJobGetName
361 Get the job name/title.
362 const char * papplJobGetName (
364 pappl_job_t *job
365 );
366 This function returns the name or title of the job.
368 papplJobGetPrinter
370 Get the printer for the job.
371 pappl_printer_t * papplJobGetPrinter (
373 pappl_job_t *job
374 );
375 This function returns the printer containing the job.
377 papplJobGetReasons
379 Get the current job state reasons.
380 pappl_jreason_t papplJobGetReasons (
382 pappl_job_t *job
383 );
384 This function returns the current job state reasons bitfield.
386 papplJobGetState
388 Get the current job state.
389 ipp_jstate_t papplJobGetState (
391 pappl_job_t *job
392 );
393 This function returns the current job processing state, which is repre‐
395 sented as an enumeration:
396 • IPP_JSTATE_ABORTED: Job has been aborted by the system due to an
398 error.
399 • IPP_JSTATE_CANCELED: Job has been canceled by a user.
401 • IPP_JSTATE_COMPLETED: Job has finished printing.
403 • IPP_JSTATE_HELD: Job is being held for some reason, typically be‐
405 cause the document data is being received.
406 • IPP_JSTATE_PENDING: Job is queued and waiting to be printed.
408 • IPP_JSTATE_PROCESSING: Job is being printed.
410 • IPP_JSTATE_STOPPED: Job is paused, typically when the printer is
412 not ready.</li> </ul>
413 papplJobGetTimeCompleted
415 Get the job completion time, if any.
416 time_t papplJobGetTimeCompleted (
418 pappl_job_t *job
419 );
420 This function returns the date and time when the job reached the com‐
422 pleted, canceled, or aborted states. 0 is returned if the job is not
423 yet in one of those states.
424 papplJobGetTimeCreated
426 Get the job creation time.
427 time_t papplJobGetTimeCreated (
429 pappl_job_t *job
430 );
431 This function returns the date and time when the job was created.
433 papplJobGetTimeProcessed
435 Get the job processing time.
436 time_t papplJobGetTimeProcessed (
438 pappl_job_t *job
439 );
440 This function returns the date and time when the job started processing
442 (printing).
443 papplJobGetUsername
445 Get the name of the user that submitted the job.
446 const char * papplJobGetUsername (
448 pappl_job_t *job
449 );
450 This function returns the name of the user that submitted the job.
452 papplJobIsCanceled
454 Return whether the job is canceled.
455 bool papplJobIsCanceled (
457 pappl_job_t *job
458 );
459 This function returns true if the job has been canceled or aborted.
461 papplJobOpenFile
463 Create or open a file for the document in a job.
464 int papplJobOpenFile (
466 pappl_job_t *job,
467 char *fname,
468 size_t fnamesize,
469 const char *directory,
470 const char *ext,
471 const char *mode
472 );
473 This function creates or opens a file for a job. The "fname" and
475 "fnamesize" arguments specify the location and size of a buffer to
476 store the job filename, which incorporates the "directory", printer ID,
477 job ID, job name (title), and "ext" values. The job name is "sani‐
478 tized" to only contain alphanumeric characters.
479 The "mode" argument is "r" to read an existing job file or "w" to write
481 a new job file. New files are created with restricted permissions for
482 security purposes.
483 papplJobSetData
485 Set the per-job driver data pointer.
486 void papplJobSetData (
488 pappl_job_t *job,
489 void *data
490 );
491 This function sets the driver data for the specified job. It is nor‐
493 mally only called from drivers to maintain state for the processing of
494 the job, for example to store bitmap compression information.
495 papplJobSetImpressions
497 Set the number of impressions (sides) in a job.
498 void papplJobSetImpressions (
500 pappl_job_t *job,
501 int impressions
502 );
503 This function sets the number of impressions in a job. An impression
505 is one side of an output page.
506 papplJobSetImpressionsCompleted
508 Add completed impressions (sides) to the job.
509 void papplJobSetImpressionsCompleted (
511 pappl_job_t *job,
512 int add
513 );
514 This function updates the number of completed impressions in a job. An
516 impression is one side of an output page.
517 papplJobSetMessage
519 Set the job message string.
520 void papplJobSetMessage (
522 pappl_job_t *job,
523 const char *message,
524 ...
525 );
526 This function sets the job message string using a printf-style format
528 string.
529 5 Note: The maximum length of the job message string is 1023
531 bytes.
532 papplJobSetReasons
534 Set the job state reasons bit values.
535 void papplJobSetReasons (
537 pappl_job_t *job,
538 pappl_jreason_t add,
539 pappl_jreason_t remove
540 );
541 This function updates the job state reasons bitfield. The "remove"
543 bits are cleared first, then the "add" bits are set.
544 papplPrinterFindJob
546 Find a job.
547 pappl_job_t * papplPrinterFindJob (
549 pappl_printer_t *printer,
550 int job_id
551 );
552 This function finds a job submitted to a printer using its integer ID
554 value.
555 papplSystemCleanJobs
557 Clean out old (completed) jobs.
558 void papplSystemCleanJobs (
560 pappl_system_t *system
561 );
562 This function deletes all old (completed) jobs above the limit set by
564 the papplPrinterSetMaxCompletedJobs function. The level may temporar‐
565 ily exceed this limit if the jobs were completed within the last 60
566 seconds.
567 5 Note: This function is normally called automatically from the
569 5 papplSystemRun function.
571
573 pappl_jreason_t
574 Bitfield for IPP "job-state-reasons" values
575 typedef unsigned int pappl_jreason_t;
577
579 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
580 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
581 source(3), pappl-system(3), https://www.msweet.org/pappl
582
584 Copyright © 2019-2022 by Michael R Sweet.
585 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
587 tional) exception to allow linking against GPL2/LGPL2 software (like
588 older versions of CUPS), so it can be used freely in any project you'd
589 like. See the files "LICENSE" and "NOTICE" in the source distribution
590 for more information.
5912022-05-10 pappl job functions pappl-job(3)