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 papplJobDeletePrintOptions
230 Delete a job options structure.
231 void papplJobDeletePrintOptions (
233 pappl_pr_options_t *options
234 );
235 This function frees the memory used for a job options structure.
237 papplJobFilterImage
239 Filter an image in memory.
240 bool papplJobFilterImage (
242 pappl_job_t *job,
243 pappl_device_t *device,
244 pappl_pr_options_t *options,
245 const unsigned char *pixels,
246 int width,
247 int height,
248 int depth,
249 int ppi,
250 bool smoothing
251 );
252 This function will print a grayscale or sRGB image using the printer's
254 raster driver interface, scaling and positioning the image as necessary
255 based on the job options, and printing as many copies as requested.
256 The image data is an array of grayscale ("depth" = 1) or sRGB ("depth"
258 = 3) pixels starting at the top-left corner of the image.
259 The image resolution ("ppi") is expressed in pixels per inch and is
261 used for some "print-scaling" modes. Pass 0 if the image has no ex‐
262 plicit resolution information.
263 papplJobGetAttribute
265 Get an attribute from a job.
266 ipp_attribute_t * papplJobGetAttribute (
268 pappl_job_t *job,
269 const char *name
270 );
271 This function gets the named IPP attribute from a job. The returned
273 attribute can be examined using the ippGetXxx functions.
274 papplJobGetData
276 Get per-job driver data.
277 void * papplJobGetData (
279 pappl_job_t *job
280 );
281 This function returns the driver data associated with the job. It is
283 normally only called from drivers to maintain state for the processing
284 of the job, for example to store bitmap compression information.
285 papplJobGetFilename
287 Get the job's filename.
288 const char * papplJobGetFilename (
290 pappl_job_t *job
291 );
292 This function returns the filename for the job's document data.
294 papplJobGetFormat
296 Get the MIME media type for the job's file.
297 const char * papplJobGetFormat (
299 pappl_job_t *job
300 );
301 This function returns the MIME media type for the job's document data.
303 papplJobGetID
305 Get the job ID value.
306 int papplJobGetID (
308 pappl_job_t *job
309 );
310 This function returns the job's unique integer identifier.
312 papplJobGetImpressions
314 Get the number of impressions (sides) in the job.
315 int papplJobGetImpressions (
317 pappl_job_t *job
318 );
319 This function returns the number of impressions in the job's document
321 data. An impression is one side of an output page.
322 papplJobGetImpressionsCompleted
324 Get the number of completed impressions (sides) in the job.
325 int papplJobGetImpressionsCompleted (
327 pappl_job_t *job
328 );
329 This function returns the number of impressions that have been printed.
331 An impression is one side of an output page.
332 papplJobGetMessage
334 Get the current job message string, if any.
335 const char * papplJobGetMessage (
337 pappl_job_t *job
338 );
339 This function returns the current job message string, if any.
341 papplJobGetName
343 Get the job name/title.
344 const char * papplJobGetName (
346 pappl_job_t *job
347 );
348 This function returns the name or title of the job.
350 papplJobGetPrinter
352 Get the printer for the job.
353 pappl_printer_t * papplJobGetPrinter (
355 pappl_job_t *job
356 );
357 This function returns the printer containing the job.
359 papplJobGetReasons
361 Get the current job state reasons.
362 pappl_jreason_t papplJobGetReasons (
364 pappl_job_t *job
365 );
366 This function returns the current job state reasons bitfield.
368 papplJobGetState
370 Get the current job state.
371 ipp_jstate_t papplJobGetState (
373 pappl_job_t *job
374 );
375 This function returns the current job processing state, which is repre‐
377 sented as an enumeration:
378 • IPP_JSTATE_ABORTED: Job has been aborted by the system due to an
380 error.
381 • IPP_JSTATE_CANCELED: Job has been canceled by a user.
383 • IPP_JSTATE_COMPLETED: Job has finished printing.
385 • IPP_JSTATE_HELD: Job is being held for some reason, typically be‐
387 cause the document data is being received.
388 • IPP_JSTATE_PENDING: Job is queued and waiting to be printed.
390 • IPP_JSTATE_PROCESSING: Job is being printed.
392 • IPP_JSTATE_STOPPED: Job is paused, typically when the printer is
394 not ready.</li> </ul>
395 papplJobGetTimeCompleted
397 Get the job completion time, if any.
398 time_t papplJobGetTimeCompleted (
400 pappl_job_t *job
401 );
402 This function returns the date and time when the job reached the com‐
404 pleted, canceled, or aborted states. 0 is returned if the job is not
405 yet in one of those states.
406 papplJobGetTimeCreated
408 Get the job creation time.
409 time_t papplJobGetTimeCreated (
411 pappl_job_t *job
412 );
413 This function returns the date and time when the job was created.
415 papplJobGetTimeProcessed
417 Get the job processing time.
418 time_t papplJobGetTimeProcessed (
420 pappl_job_t *job
421 );
422 This function returns the date and time when the job started processing
424 (printing).
425 papplJobGetUsername
427 Get the name of the user that submitted the job.
428 const char * papplJobGetUsername (
430 pappl_job_t *job
431 );
432 This function returns the name of the user that submitted the job.
434 papplJobIsCanceled
436 Return whether the job is canceled.
437 bool papplJobIsCanceled (
439 pappl_job_t *job
440 );
441 This function returns true if the job has been canceled or aborted.
443 papplJobOpenFile
445 Create or open a file for the document in a job.
446 int papplJobOpenFile (
448 pappl_job_t *job,
449 char *fname,
450 size_t fnamesize,
451 const char *directory,
452 const char *ext,
453 const char *mode
454 );
455 This function creates or opens a file for a job. The "fname" and
457 "fnamesize" arguments specify the location and size of a buffer to
458 store the job filename, which incorporates the "directory", printer ID,
459 job ID, job name (title), and "ext" values. The job name is "sani‐
460 tized" to only contain alphanumeric characters.
461 The "mode" argument is "r" to read an existing job file or "w" to write
463 a new job file. New files are created with restricted permissions for
464 security purposes.
465 papplJobSetData
467 Set the per-job driver data pointer.
468 void papplJobSetData (
470 pappl_job_t *job,
471 void *data
472 );
473 This function sets the driver data for the specified job. It is nor‐
475 mally only called from drivers to maintain state for the processing of
476 the job, for example to store bitmap compression information.
477 papplJobSetImpressions
479 Set the number of impressions (sides) in a job.
480 void papplJobSetImpressions (
482 pappl_job_t *job,
483 int impressions
484 );
485 This function sets the number of impressions in a job. An impression
487 is one side of an output page.
488 papplJobSetImpressionsCompleted
490 Add completed impressions (sides) to the job.
491 void papplJobSetImpressionsCompleted (
493 pappl_job_t *job,
494 int add
495 );
496 This function updates the number of completed impressions in a job. An
498 impression is one side of an output page.
499 papplJobSetMessage
501 Set the job message string.
502 void papplJobSetMessage (
504 pappl_job_t *job,
505 const char *message,
506 ...
507 );
508 This function sets the job message string using a printf-style format
510 string.
511 5 Note: The maximum length of the job message string is 1023
513 bytes.
514 papplJobSetReasons
516 Set the job state reasons bit values.
517 void papplJobSetReasons (
519 pappl_job_t *job,
520 pappl_jreason_t add,
521 pappl_jreason_t remove
522 );
523 This function updates the job state reasons bitfield. The "remove"
525 bits are cleared first, then the "add" bits are set.
526 papplPrinterFindJob
528 Find a job.
529 pappl_job_t * papplPrinterFindJob (
531 pappl_printer_t *printer,
532 int job_id
533 );
534 This function finds a job submitted to a printer using its integer ID
536 value.
537 papplSystemCleanJobs
539 Clean out old (completed) jobs.
540 void papplSystemCleanJobs (
542 pappl_system_t *system
543 );
544 This function deletes all old (completed) jobs above the limit set by
546 the papplPrinterSetMaxCompletedJobs function. The level may temporar‐
547 ily exceed this limit if the jobs were completed within the last 60
548 seconds.
549 5 Note: This function is normally called automatically from the
551 5 papplSystemRun function.
553
555 pappl_jreason_t
556 Bitfield for IPP "job-state-reasons" values
557 typedef unsigned int pappl_jreason_t;
559
561 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
562 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
563 source(3), pappl-system(3), https://www.msweet.org/pappl
564
566 Copyright © 2019-2020 by Michael R Sweet.
567 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
569 tional) exception to allow linking against GPL2/LGPL2 software (like
570 older versions of CUPS), so it can be used freely in any project you'd
571 like. See the files "LICENSE" and "NOTICE" in the source distribution
572 for more information.
5732021-02-15 pappl job functions pappl-job(3)