1pappl-printer(3) pappl printer functions pappl-printer(3)
2
6 pappl-printer - pappl printer functions
7
9 Printer Application Framework (libpappl, "pkg-config --cflags --libs
10 pappl")
11
13 #include <pappl/pappl.h>
14 typedef struct _pappl_printer_s pappl_printer_t;
16 void
18 papplPrinterCancelAllJobs(pappl_printer_t *printer);
19 void
22 papplPrinterCloseDevice(pappl_printer_t *printer);
23 pappl_printer_t *
26 papplPrinterCreate(pappl_system_t *system, int printer_id, const char
27 *printer_name, const char *driver_name, const char *device_id, const
28 char *device_uri);
29 void
31 papplPrinterDelete(pappl_printer_t *printer);
32 pappl_job_t *
34 papplPrinterFindJob(pappl_printer_t *printer, int job_id);
35 pappl_contact_t *
37 papplPrinterGetContact(pappl_printer_t *printer, pappl_contact_t *con‐
38 tact);
39 const char *
41 papplPrinterGetDeviceID(pappl_printer_t *printer);
42 const char *
44 papplPrinterGetDeviceURI(pappl_printer_t *printer);
45 char *
47 papplPrinterGetDNSSDName(pappl_printer_t *printer, char *buffer, size_t
48 bufsize);
49 ipp_t *
51 papplPrinterGetDriverAttributes(pappl_printer_t *printer);
52 pappl_driver_data_t *
54 papplPrinterGetDriverData(pappl_printer_t *printer, pappl_driver_data_t
55 *data);
56 const char *
58 papplPrinterGetDriverName(pappl_printer_t *printer);
59 char *
61 papplPrinterGetGeoLocation(pappl_printer_t *printer, char *buffer,
62 size_t bufsize);
63 int
65 papplPrinterGetID(pappl_printer_t *printer);
66 int
68 papplPrinterGetImpressionsCompleted(pappl_printer_t *printer);
69 char *
71 papplPrinterGetLocation(pappl_printer_t *printer, char *buffer, size_t
72 bufsize);
73 int
75 papplPrinterGetMaxActiveJobs(pappl_printer_t *printer);
76 int
78 papplPrinterGetMaxCompletedJobs(pappl_printer_t *printer);
79 const char *
81 papplPrinterGetName(pappl_printer_t *printer);
82 int
84 papplPrinterGetNextJobID(pappl_printer_t *printer);
85 int
87 papplPrinterGetNumberOfActiveJobs(pappl_printer_t *printer);
88 int
90 papplPrinterGetNumberOfCompletedJobs(pappl_printer_t *printer);
91 int
93 papplPrinterGetNumberOfJobs(pappl_printer_t *printer);
94 char *
96 papplPrinterGetOrganization(pappl_printer_t *printer, char *buffer,
97 size_t bufsize);
98 char *
100 papplPrinterGetOrganizationalUnit(pappl_printer_t *printer, char *buf‐
101 fer, size_t bufsize);
102 char *
104 papplPrinterGetPrintGroup(pappl_printer_t *printer, char *buffer,
105 size_t bufsize);
106 pappl_preason_t
108 papplPrinterGetReasons(pappl_printer_t *printer);
109 ipp_pstate_t
111 papplPrinterGetState(pappl_printer_t *printer);
112 int
114 papplPrinterGetSupplies(pappl_printer_t *printer, int max_supplies,
115 pappl_supply_t *supplies);
116 pappl_system_t *
118 papplPrinterGetSystem(pappl_printer_t *printer);
119 void
122 papplPrinterIterateActiveJobs(pappl_printer_t *printer, pappl_job_cb_t
123 cb, void *data, int first_index, int limit);
124 void
126 papplPrinterIterateAllJobs(pappl_printer_t *printer, pappl_job_cb_t cb,
127 void *data, int first_index, int limit);
128 void
130 papplPrinterIterateCompletedJobs(pappl_printer_t *printer,
131 pappl_job_cb_t cb, void *data, int first_index, int limit);
132 pappl_device_t *
135 papplPrinterOpenDevice(pappl_printer_t *printer);
136 void
139 papplPrinterPause(pappl_printer_t *printer);
140 void
142 papplPrinterResume(pappl_printer_t *printer);
143 void
146 papplPrinterSetContact(pappl_printer_t *printer, pappl_contact_t *con‐
147 tact);
148 void
150 papplPrinterSetDNSSDName(pappl_printer_t *printer, const char *value);
151 void
153 papplPrinterSetDriverData(pappl_printer_t *printer, pappl_driver_data_t
154 *data, ipp_t *attrs);
155 void
157 papplPrinterSetDriverDefaults(pappl_printer_t *printer,
158 pappl_driver_data_t *data);
159 void
161 papplPrinterSetGeoLocation(pappl_printer_t *printer, const char
162 *value);
163 void
165 papplPrinterSetImpressionsCompleted(pappl_printer_t *printer, int add);
166 void
168 papplPrinterSetLocation(pappl_printer_t *printer, const char *value);
169 void
171 papplPrinterSetMaxActiveJobs(pappl_printer_t *printer, int max_ac‐
172 tive_jobs);
173 void
175 papplPrinterSetMaxCompletedJobs(pappl_printer_t *printer, int max_com‐
176 pleted_jobs);
177 void
179 papplPrinterSetNextJobID(pappl_printer_t *printer, int next_job_id);
180 void
182 papplPrinterSetOrganization(pappl_printer_t *printer, const char
183 *value);
184 void
186 papplPrinterSetOrganizationalUnit(pappl_printer_t *printer, const char
187 *value);
188 void
190 papplPrinterSetPrintGroup(pappl_printer_t *printer, const char *value);
191 void
193 papplPrinterSetReadyMedia(pappl_printer_t *printer, int num_ready,
194 pappl_media_col_t *ready);
195 void
197 papplPrinterSetReasons(pappl_printer_t *printer, pappl_preason_t add,
198 pappl_preason_t remove);
199 void
201 papplPrinterSetSupplies(pappl_printer_t *printer, int num_supplies,
202 pappl_supply_t *supplies);
203 void
205 papplPrinterSetUSB(pappl_printer_t *printer, unsigned vendor_id, un‐
206 signed product_id, pappl_uoptions_t options);
207
210 The PAPPL printer functions provide access to the printer object.
211 Printers are created and deleted by the printer application while the
212 life cycle of the pappl_printer_t objects are managed automatically by
213 the system object for the printer application.
214 The papplPrinterCreate function creates a new printer while the pappl‐
216 PrinterDelete function deletes a printer.
217 The papplPrinterPause function stops a printer while the papplPrinter‐
219 Resume function starts a printer.
220 The papplPrinterGet functions get the current values associated with a
222 printer while the papplPrinterSet functions set the current values as‐
223 sociated with a printer.
224 The papplPrinterCancelAddJobs, papplPrinterFindJob, papplPrinterGetNum‐
226 berOfActiveJobs, papplPrinterGetNumberOfCompletedJobs, papplPrinterGet‐
227 NumberOfJobs, papplPrinterIterateActiveJobs, papplPrinterIter‐
228 ateAllJobs, and papplPrinterIterateCompletedJobs functions provide ac‐
229 cess to the jobs queued on a printer.
230 The papplPrinterOpenDevice function provides access to the device asso‐
232 ciated with a printer when it is not processing a job. The device must
233 be later closed using the papplPrinterCloseDevice function so that the
234 printer can resume job processing.
235
237 pappl_color_mode_e
238 IPP "print-color-mode" bit values
239 PAPPL_COLOR_MODE_AUTO
241 ´auto' - Automatic color/monochrome print mode
242 PAPPL_COLOR_MODE_AUTO_MONOCHROME
244 ´auto-monochrome' - Automatic monochrome/process monochrome print
245 mode
246 PAPPL_COLOR_MODE_BI_LEVEL
248 ´bi-level' - B&W (threshold) print mode
249 PAPPL_COLOR_MODE_COLOR
251 ´color' - Full color print mode
252 PAPPL_COLOR_MODE_MONOCHROME
254 ´monochrome' - Grayscale print mode using 1 color
255 PAPPL_COLOR_MODE_PROCESS_MONOCHROME
257 ´process-monochrome' - Grayscale print mode using multiple colors
258 pappl_content_e
260 IPP "print-content-optimize" bit values
261 PAPPL_CONTENT_AUTO
263 ´auto': Automatically determine content
264 PAPPL_CONTENT_GRAPHIC
266 ´graphic': Optimize for vector graphics
267 PAPPL_CONTENT_PHOTO
269 ´photo': Optimize for photos/continuous tone images
270 PAPPL_CONTENT_TEXT
272 ´text': Optimize for text
273 PAPPL_CONTENT_TEXT_AND_GRAPHIC
275 ´text-and-graphic': Optimize for text and vector graphics
276 pappl_duplex_e
278 Duplex printing support
279 PAPPL_DUPLEX_FLIPPED
281 Duplex with flipped back sides
282 PAPPL_DUPLEX_MANUAL_TUMBLE
284 Duplex with back side rotated 180 degrees for short-edge duplex
285 PAPPL_DUPLEX_NONE
287 No duplex printing support
288 PAPPL_DUPLEX_NORMAL
290 Duplex with normal back sides
291 PAPPL_DUPLEX_ROTATED
293 Duplex with back side rotated 180 degrees for long-edge duplex
294 pappl_finishings_e
296 IPP "finishings" bit values
297 PAPPL_FINISHINGS_NONE
299 ´none'
300 PAPPL_FINISHINGS_PUNCH
302 ´punch'
303 PAPPL_FINISHINGS_STAPLE
305 ´staple'
306 PAPPL_FINISHINGS_TRIM
308 ´trim'
309 pappl_identify_actions_e
311 IPP "identify-actions" bit values
312 PAPPL_IDENTIFY_ACTIONS_DISPLAY
314 ´display': Display a message
315 PAPPL_IDENTIFY_ACTIONS_FLASH
317 ´flash': Flash the display or a light
318 PAPPL_IDENTIFY_ACTIONS_NONE
320 No actions
321 PAPPL_IDENTIFY_ACTIONS_SOUND
323 ´sound': Make a sound
324 PAPPL_IDENTIFY_ACTIONS_SPEAK
326 ´speak': Speak a message
327 pappl_kind_e
329 IPP "printer-kind" bit values
330 PAPPL_KIND_DISC
332 ´disc'
333 PAPPL_KIND_DOCUMENT
335 ´document'
336 PAPPL_KIND_ENVELOPE
338 ´envelope'
339 PAPPL_KIND_LABEL
341 ´label'
342 PAPPL_KIND_LARGE_FORMAT
344 ´large-format'
345 PAPPL_KIND_PHOTO
347 ´photo'
348 PAPPL_KIND_POSTCARD
350 ´postcard'
351 PAPPL_KIND_RECEIPT
353 ´receipt'
354 PAPPL_KIND_ROLL
356 ´roll'
357 pappl_label_mode_e
359 IPP "label-mode-xxx" bit values
360 PAPPL_LABEL_MODE_APPLICATOR
362 ´applicator'
363 PAPPL_LABEL_MODE_CUTTER
365 ´cutter'
366 PAPPL_LABEL_MODE_CUTTER_DELAYED
368 ´cutter-delayed'
369 PAPPL_LABEL_MODE_KIOSK
371 ´kiosk'
372 PAPPL_LABEL_MODE_PEEL_OFF
374 ´peel-off'
375 PAPPL_LABEL_MODE_PEEL_OFF_PREPEEL
377 ´peel-off-prepeel'
378 PAPPL_LABEL_MODE_REWIND
380 ´rewind'
381 PAPPL_LABEL_MODE_RFID
383 ´rfid'
384 PAPPL_LABEL_MODE_TEAR_OFF
386 ´tear-off'
387 pappl_media_tracking_e
389 IPP "media-tracking" bit values
390 PAPPL_MEDIA_TRACKING_CONTINUOUS
392 ´continuous'
393 PAPPL_MEDIA_TRACKING_GAP
395 ´gap'
396 PAPPL_MEDIA_TRACKING_MARK
398 ´mark'
399 PAPPL_MEDIA_TRACKING_WEB
401 ´web'
402 pappl_preason_e
404 IPP "printer-state-reasons" bit values
405 PAPPL_PREASON_COVER_OPEN
407 ´cover-open'
408 PAPPL_PREASON_DEVICE_STATUS
410 Supported papplDeviceGetStatus bits
411 PAPPL_PREASON_DOOR_OPEN
413 ´door-open'
414 PAPPL_PREASON_IDENTIFY_PRINTER_REQUESTED
416 ´identify-printer-requested'
417 PAPPL_PREASON_INPUT_TRAY_MISSING
419 ´input-tray-missing'
420 PAPPL_PREASON_MARKER_SUPPLY_EMPTY
422 ´marker-supply-empty'
423 PAPPL_PREASON_MARKER_SUPPLY_LOW
425 ´marker-supply-low'
426 PAPPL_PREASON_MARKER_WASTE_ALMOST_FULL
428 ´marker-waste-almost-full'
429 PAPPL_PREASON_MARKER_WASTE_FULL
431 ´marker-waste-full'
432 PAPPL_PREASON_MEDIA_EMPTY
434 ´media-empty'
435 PAPPL_PREASON_MEDIA_JAM
437 ´media-jam'
438 PAPPL_PREASON_MEDIA_LOW
440 ´media-low'
441 PAPPL_PREASON_MEDIA_NEEDED
443 ´media-needed'
444 PAPPL_PREASON_NONE
446 ´none'
447 PAPPL_PREASON_OFFLINE
449 ´offline'
450 PAPPL_PREASON_OTHER
452 ´other'
453 PAPPL_PREASON_SPOOL_AREA_FULL
455 ´spool-area-full'
456 PAPPL_PREASON_TONER_EMPTY
458 ´toner-empty'
459 PAPPL_PREASON_TONER_LOW
461 ´toner-low'
462 pappl_raster_type_e
464 IPP "pwg-raster-document-type-supported" bit values
465 PAPPL_PWG_RASTER_TYPE_ADOBE_RGB_16
467 16-bit per component AdobeRGB
468 PAPPL_PWG_RASTER_TYPE_ADOBE_RGB_8
470 8-bit per component AdobeRGB
471 PAPPL_PWG_RASTER_TYPE_BLACK_1
473 1-bit (device) black
474 PAPPL_PWG_RASTER_TYPE_BLACK_16
476 16-bit (device) black
477 PAPPL_PWG_RASTER_TYPE_BLACK_8
479 8-bit (device) black
480 PAPPL_PWG_RASTER_TYPE_CMYK_16
482 16-bit per component (device) CMYK
483 PAPPL_PWG_RASTER_TYPE_CMYK_8
485 8-bit per component (device) CMYK
486 PAPPL_PWG_RASTER_TYPE_NONE
488 Do not force a particular raster type
489 PAPPL_PWG_RASTER_TYPE_RGB_16
491 16-bit per component (device) RGB
492 PAPPL_PWG_RASTER_TYPE_RGB_8
494 8-bit per component (device) RGB
495 PAPPL_PWG_RASTER_TYPE_SGRAY_16
497 16-bit grayscale with 2.2 gamma
498 PAPPL_PWG_RASTER_TYPE_SGRAY_8
500 8-bit grayscale with 2.2 gamma
501 PAPPL_PWG_RASTER_TYPE_SRGB_16
503 16-bit per component sRGB
504 PAPPL_PWG_RASTER_TYPE_SRGB_8
506 8-bit per component sRGB
507 pappl_scaling_e
509 IPP "print-scaling" bit values
510 PAPPL_SCALING_AUTO
512 ´auto': Scale to fit (non-borderless) or fill (borderless) if
513 larger, otherwise center
514 PAPPL_SCALING_AUTO_FIT
516 ´auto-fit': Scale to fit if larger, otherwise center
517 PAPPL_SCALING_FILL
519 ´fill': Scale to fill the media
520 PAPPL_SCALING_FIT
522 ´fit': Scale to fit within margins
523 PAPPL_SCALING_NONE
525 ´none': No scaling (center/crop)
526 pappl_sides_e
528 IPP "sides" bit values
529 PAPPL_SIDES_ONE_SIDED
531 ´one-sided'
532 PAPPL_SIDES_TWO_SIDED_LONG_EDGE
534 ´two-sided-long-edge'
535 PAPPL_SIDES_TWO_SIDED_SHORT_EDGE
537 ´two-sided-short-edge'
538 pappl_uoptions_e
540 USB gadget options
541 PAPPL_UOPTIONS_ETHERNET
543 Include USB ethernet gadget
544 PAPPL_UOPTIONS_NONE
546 No options (just USB printer)
547 PAPPL_UOPTIONS_SERIAL
549 Include USB serial gadget
550 PAPPL_UOPTIONS_STORAGE
552 Include USB mass storage gadget
553 PAPPL_UOPTIONS_STORAGE_READONLY
555 USB mass storage gadget is read-only
556 PAPPL_UOPTIONS_STORAGE_REMOVABLE
558 USB mass storage gadget is removable
559
561 papplPrinterCancelAllJobs
562 Cancel all jobs on the printer.
563 void papplPrinterCancelAllJobs (
565 pappl_printer_t *printer
566 );
567 This function cancels all jobs on the printer. If any job is currently
569 being printed, it will be stopped at a convenient time (usually the end
570 of a page) so that the printer will be left in a known state.
571 papplPrinterCloseDevice
573 Close the device associated with the printer.
574 void papplPrinterCloseDevice (
576 pappl_printer_t *printer
577 );
578 This function closes the device for a printer. The device must have
580 been previously opened using the papplPrinterOpenDevice function.
581 papplPrinterCreate
583 Create a new printer.
584 pappl_printer_t * papplPrinterCreate (
586 pappl_system_t *system,
587 int printer_id,
588 const char *printer_name,
589 const char *driver_name,
590 const char *device_id,
591 const char *device_uri
592 );
593 This function creates a new printer (service) on the specified system.
595 The "type" argument specifies the type of service to create and must
596 currently be the value PAPPL_SERVICE_TYPE_PRINT.
597 The "printer_id" argument specifies a positive integer identifier that
599 is unique to the system. If you specify a value of 0 a new identifier
600 will be assigned.
601 The "driver_name" argument specifies a named driver for the printer,
603 from the list of drivers registered with the papplSystemSetPrinter‐
604 Drivers function.
605 The "device_id" and "device_uri" arguments specify the IEEE-1284 device
607 ID and device URI strings for the printer.
608 On error, this function sets the errno variable to one of the following
610 values:
611 • EEXIST: A printer with the specified name already exists.
613 • EINVAL: Bad values for the arguments were specified.
615 • EIO: The driver callback failed.
617 • ENOENT: No driver callback has been set.
619 • ENOMEM: Ran out of memory.</li> </ul>
621 papplPrinterDelete
623 Delete a printer.
624 void papplPrinterDelete (
626 pappl_printer_t *printer
627 );
628 This function deletes a printer from a system, freeing all memory and
630 canceling all jobs as needed.
631 papplPrinterDisable
633 Stop accepting jobs on a printer.
634 void papplPrinterDisable (
636 pappl_printer_t *printer
637 );
638 This function stops accepting jobs on a printer.
640 papplPrinterEnable
642 Start accepting jobs on a printer.
643 void papplPrinterEnable (
645 pappl_printer_t *printer
646 );
647 This function starts accepting jobs on a printer.
649 papplPrinterGetContact
651 Get the "printer-contact" value.
652 pappl_contact_t * papplPrinterGetContact (
654 pappl_printer_t *printer,
655 pappl_contact_t *contact
656 );
657 This function copies the current printer contact information to the
659 buffer pointed to by the "contact" argument.
660 papplPrinterGetDNSSDName
662 Get the current DNS-SD service name.
663 char * papplPrinterGetDNSSDName (
665 pappl_printer_t *printer,
666 char *buffer,
667 size_t bufsize
668 );
669 This function copies the current DNS-SD service name to the buffer
671 pointed to by the "buffer" argument.
672 papplPrinterGetDeviceID
674 Get the IEEE-1284 device ID of the printer.
675 const char * papplPrinterGetDeviceID (
677 pappl_printer_t *printer
678 );
679 This function returns the IEEE-1284 device ID of the printer.
681 papplPrinterGetDeviceURI
683 Get the URI of the device associated with the printer.
684 const char * papplPrinterGetDeviceURI (
686 pappl_printer_t *printer
687 );
688 This function returns the device URI for the printer.
690 papplPrinterGetDriverAttributes
692 Get a copy of the current driver attributes.
693 ipp_t * papplPrinterGetDriverAttributes (
695 pappl_printer_t *printer
696 );
697 This function returns a copy the current driver attributes. Use the ip‐
699 pDelete function to free the memory used for the attributes when you
700 are done.
701 papplPrinterGetDriverData
703 Get the current print driver data.
704 pappl_pr_driver_data_t * papplPrinterGetDriverData (
706 pappl_printer_t *printer,
707 pappl_pr_driver_data_t *data
708 );
709 This function copies the current print driver data, defaults, and ready
711 (loaded) media information into the specified buffer.
712 papplPrinterGetDriverName
714 Get the driver name for a printer.
715 const char * papplPrinterGetDriverName (
717 pappl_printer_t *printer
718 );
719 This function returns the driver name for the printer.
721 papplPrinterGetGeoLocation
723 Get the current geo-location as a "geo:" URI.
724 char * papplPrinterGetGeoLocation (
726 pappl_printer_t *printer,
727 char *buffer,
728 size_t bufsize
729 );
730 This function copies the currently configured geographic location as a
732 "geo:" URI to the buffer pointed to by the "buffer" argument.
733 papplPrinterGetID
735 Get the printer ID.
736 int papplPrinterGetID (
738 pappl_printer_t *printer
739 );
740 This function returns the printer's unique positive integer identifier.
742 papplPrinterGetImpressionsCompleted
744 Get the number of impressions (sides) that have been printed.
745 int papplPrinterGetImpressionsCompleted (
747 pappl_printer_t *printer
748 );
749 This function returns the number of impressions that have been printed.
751 An impression is one side of an output page.
752 papplPrinterGetLocation
754 Get the location string.
755 char * papplPrinterGetLocation (
757 pappl_printer_t *printer,
758 char *buffer,
759 size_t bufsize
760 );
761 This function copies the printer's human-readable location to the buf‐
763 fer pointed to by the "buffer" argument.
764 papplPrinterGetMaxActiveJobs
766 Get the maximum number of active (queued) jobs allowed by the printer.
767 int papplPrinterGetMaxActiveJobs (
769 pappl_printer_t *printer
770 );
771 This function returns the maximum number of active jobs that the
773 printer supports, as configured by the papplPrinterSetMaxActiveJobs
774 function.
775 papplPrinterGetMaxCompletedJobs
777 Get the maximum number of jobs retained for history by the printer.
778 int papplPrinterGetMaxCompletedJobs (
780 pappl_printer_t *printer
781 );
782 This function returns the maximum number of jobs that are retained in
784 the job history as configured by the papplPrinterSetMaxCompletedJobs
785 function.
786 papplPrinterGetMaxPreservedJobs
788 Get the maximum number of jobs preserved by the printer.
789 int papplPrinterGetMaxPreservedJobs (
791 pappl_printer_t *printer
792 );
793 This function returns the maximum number of jobs that are retained (in‐
795 cluding document data) in the job history as configured by the pappl‐
796 PrinterSetMaxPreservedJobs function.
797 papplPrinterGetName
799 Get the printer name.
800 const char * papplPrinterGetName (
802 pappl_printer_t *printer
803 );
804 This function returns the printer's human-readable name.
806 papplPrinterGetNextJobID
808 Get the next job ID.
809 int papplPrinterGetNextJobID (
811 pappl_printer_t *printer
812 );
813 This function returns the positive integer identifier that will be used
815 for the next job that is created.
816 papplPrinterGetNumberOfActiveJobs
818 Get the number of active print jobs.
819 int papplPrinterGetNumberOfActiveJobs (
821 pappl_printer_t *printer
822 );
823 This function returns the number of print jobs that are either printing
825 or waiting to be printed.
826 papplPrinterGetNumberOfCompletedJobs
828 Get the number of completed print jobs.
829 int papplPrinterGetNumberOfCompletedJobs (
831 pappl_printer_t *printer
832 );
833 This function returns the number of print jobs that have been aborted,
835 canceled, or completed.
836 papplPrinterGetNumberOfJobs
838 Get the total number of print jobs.
839 int papplPrinterGetNumberOfJobs (
841 pappl_printer_t *printer
842 );
843 This function returns the number of print jobs that are printing, wait‐
845 ing to be printed, have been aborted, have been canceled, or have com‐
846 pleted.
847 papplPrinterGetOrganization
849 Get the organization name.
850 char * papplPrinterGetOrganization (
852 pappl_printer_t *printer,
853 char *buffer,
854 size_t bufsize
855 );
856 This function copies the printer's organization name to the buffer
858 pointed to by the "buffer" argument.
859 papplPrinterGetOrganizationalUnit
861 Get the organizational unit name.
862 char * papplPrinterGetOrganizationalUnit (
864 pappl_printer_t *printer,
865 char *buffer,
866 size_t bufsize
867 );
868 This function copies the printer's organizational unit name to the buf‐
870 fer pointed to by the "buffer" argument.
871 papplPrinterGetPath
873 Get the URL path for a printer web page.
874 char * papplPrinterGetPath (
876 pappl_printer_t *printer,
877 const char *subpath,
878 char *buffer,
879 size_t bufsize
880 );
881 This function generates and returns the URL path for the printer's web
883 page. The "subpath" argument specifies an optional sub-path for a spe‐
884 cific printer web page.
885 papplPrinterGetPrintGroup
887 Get the print authorization group, if any.
888 char * papplPrinterGetPrintGroup (
890 pappl_printer_t *printer,
891 char *buffer,
892 size_t bufsize
893 );
894 This function copies the printer's authorization group name to the buf‐
896 fer pointed to by the "buffer" argument.
897 papplPrinterGetReasons
899 Get the current "printer-state-reasons" bit values.
900 pappl_preason_t papplPrinterGetReasons (
902 pappl_printer_t *printer
903 );
904 This function returns the current printer state reasons bitfield, which
906 can be updated by the printer driver and/or by the papplPrinterSetRea‐
907 sons function.
908 papplPrinterGetState
910 Get the current "printer-state" value.
911 ipp_pstate_t papplPrinterGetState (
913 pappl_printer_t *printer
914 );
915 This function returns the current printer state as an enumeration:
917 • IPP_PSTATE_IDLE: The printer is idle and has no jobs to process.
919 • IPP_PSTATE_PROCESSING: The printer is processing a job and/or pro‐
921 ducing output.
922 • IPP_PSTATE_STOPPED: The printer is stopped for maintenance.</li>
924 </ul>
925 papplPrinterGetSupplies
927 Get the current "printer-supplies" values.
928 int papplPrinterGetSupplies (
930 pappl_printer_t *printer,
931 int max_supplies,
932 pappl_supply_t *supplies
933 );
934 This function copies the current printer supply values to the specified
936 array. The "max_supplies" and "supplies" arguments can be 0 and NULL
937 to query the number of supplies used.
938 The return value is the actual number of supplies used by the printer,
940 regardless of the size of the array.
941 papplPrinterGetSystem
943 Get the system associated with the printer.
944 pappl_system_t * papplPrinterGetSystem (
946 pappl_printer_t *printer
947 );
948 This function returns a pointer to the system object that contains the
950 printer.
951 papplPrinterIsAcceptingJobs
953 Return whether the printer is accepting jobs.
954 bool papplPrinterIsAcceptingJobs (
956 pappl_printer_t *printer
957 );
958 This function returns a boolean value indicating whether a printer is
960 accepting jobs.
961 papplPrinterIterateActiveJobs
963 Iterate over the active jobs.
964 void papplPrinterIterateActiveJobs (
966 pappl_printer_t *printer,
967 pappl_job_cb_t cb,
968 void *data,
969 int job_index,
970 int limit
971 );
972 This function iterates over jobs that are either printing or waiting to
974 be printed. The specified callback "cb" will be called once per job
975 with the data pointer "data".
976 The "job_index" argument specifies the first job in the list to iter‐
978 ate, where 1 is the first job, etc. The "limit" argument specifies the
979 maximum number of jobs to iterate - use 0 to iterate an unlimited num‐
980 ber of jobs.
981 papplPrinterIterateAllJobs
983 Iterate over all the jobs.
984 void papplPrinterIterateAllJobs (
986 pappl_printer_t *printer,
987 pappl_job_cb_t cb,
988 void *data,
989 int job_index,
990 int limit
991 );
992 This function iterates over all jobs. The specified callback "cb" will
994 be called once per job with the data pointer "data".
995 The "job_index" argument specifies the first job in the list to iter‐
997 ate, where 1 is the first job, etc. The "limit" argument specifies the
998 maximum number of jobs to iterate - use 0 to iterate an unlimited num‐
999 ber of jobs.
1000 papplPrinterIterateCompletedJobs
1002 Iterate over the completed jobs.
1003 void papplPrinterIterateCompletedJobs (
1005 pappl_printer_t *printer,
1006 pappl_job_cb_t cb,
1007 void *data,
1008 int job_index,
1009 int limit
1010 );
1011 This function iterates over jobs that are aborted, canceled, or com‐
1013 pleted. The specified callback "cb" will be called once per job with
1014 the data pointer "data".
1015 The "job_index" argument specifies the first job in the list to iter‐
1017 ate, where 1 is the first job, etc. The "limit" argument specifies the
1018 maximum number of jobs to iterate - use 0 to iterate an unlimited num‐
1019 ber of jobs.
1020 papplPrinterOpenDevice
1022 Open the device associated with a printer.
1023 pappl_device_t * papplPrinterOpenDevice (
1025 pappl_printer_t *printer
1026 );
1027 This function opens the printer's device. NULL is returned if the de‐
1029 vice is already in use, for example while a job is being printed.
1030 The returned device must be closed using the papplPrinterCloseDevice
1032 function.
1033 papplPrinterOpenFile
1035 Create or open a file for a printer.
1036 int papplPrinterOpenFile (
1038 pappl_printer_t *printer,
1039 char *fname,
1040 size_t fnamesize,
1041 const char *directory,
1042 const char *resname,
1043 const char *ext,
1044 const char *mode
1045 );
1046 This function creates or opens a file for a printer. The "fname" and
1048 "fnamesize" arguments specify the location and size of a buffer to
1049 store the printer filename, which incorporates the "directory", printer
1050 ID, resource name, and "ext" values. The job name is "sanitized" to
1051 only contain alphanumeric characters.
1052 The "mode" argument is "r" to read an existing job file or "w" to write
1054 a new job file. New files are created with restricted permissions for
1055 security purposes.
1056 papplPrinterPause
1058 Pause (stop) a printer.
1059 void papplPrinterPause (
1061 pappl_printer_t *printer
1062 );
1063 This function pauses a printer. If the printer is currently processing
1065 (printing) a job, it will be completed before the printer is stopped.
1066 papplPrinterResume
1068 Resume (start) a printer.
1069 void papplPrinterResume (
1071 pappl_printer_t *printer
1072 );
1073 This function resumes a printer and starts processing any pending jobs.
1075 papplPrinterSetContact
1077 Set the "printer-contact" value.
1078 void papplPrinterSetContact (
1080 pappl_printer_t *printer,
1081 pappl_contact_t *contact
1082 );
1083 This function sets the printer's contact information.
1085 papplPrinterSetDNSSDName
1087 Set the DNS-SD service name.
1088 void papplPrinterSetDNSSDName (
1090 pappl_printer_t *printer,
1091 const char *value
1092 );
1093 This function sets the printer's DNS-SD service name. If NULL, the
1095 printer will stop advertising the printer.
1096 papplPrinterSetDriverData
1098 Set the driver data.
1099 bool papplPrinterSetDriverData (
1101 pappl_printer_t *printer,
1102 pappl_pr_driver_data_t *data,
1103 ipp_t *attrs
1104 );
1105 This function validates and sets the driver data, including all de‐
1107 faults and ready (loaded) media.
1108 5 Note: This function regenerates all of the driver-specific capa‐
1110 bility
1111 5 attributes like "media-col-database", "sides-supported", and so
1113 forth.
1114 5 Use the papplPrinterSetDriverDefaults or
1116 5 papplPrinterSetReadyMedia functions to efficiently change the
1118 5 "xxx-default" or "xxx-ready" values, respectively.
1120 papplPrinterSetDriverDefaults
1122 Set the default print option values.
1123 bool papplPrinterSetDriverDefaults (
1125 pappl_printer_t *printer,
1126 pappl_pr_driver_data_t *data,
1127 int num_vendor,
1128 cups_option_t *vendor
1129 );
1130 This function validates and sets the printer's default print options.
1132 5 Note: Unlike papplPrinterSetPrintDriverData, this function only
1134 5 changes the "xxx_default" members of the driver data and is con‐
1136 sidered
1137 5 lightweight.
1139 papplPrinterSetGeoLocation
1141 Set the geo-location value as a "geo:" URI.
1142 void papplPrinterSetGeoLocation (
1144 pappl_printer_t *printer,
1145 const char *value
1146 );
1147 This function sets the printer's geographic location as a "geo:" URI.
1149 If NULL, the location is cleared to the 'unknown' value.
1150 papplPrinterSetImpressionsCompleted
1152 Add impressions (sides) to the total count of printed impressions.
1153 void papplPrinterSetImpressionsCompleted (
1155 pappl_printer_t *printer,
1156 int add
1157 );
1158 This function adds to the printer's impressions counter. An impression
1160 is one side of an output page.
1161 papplPrinterSetLocation
1163 Set the location string.
1164 void papplPrinterSetLocation (
1166 pappl_printer_t *printer,
1167 const char *value
1168 );
1169 This function sets the printer's human-readable location string. If
1171 NULL, the location is cleared.
1172 papplPrinterSetMaxActiveJobs
1174 Set the maximum number of active jobs for the printer.
1175 void papplPrinterSetMaxActiveJobs (
1177 pappl_printer_t *printer,
1178 int max_active_jobs
1179 );
1180 This function sets the maximum number of jobs that can be spooled on
1182 the printer at one time.
1183 5 Note: This limit does not apply to streaming raster formats such
1185 as PWG
1186 5 Raster since they are not spooled.
1188 papplPrinterSetMaxCompletedJobs
1190 Set the maximum number of completed jobs for the printer.
1191 void papplPrinterSetMaxCompletedJobs (
1193 pappl_printer_t *printer,
1194 int max_completed_jobs
1195 );
1196 This function sets the maximum number of aborted, canceled, or com‐
1198 pleted jobs that are retained in the job history.
1199 papplPrinterSetMaxPreservedJobs
1201 Set the maximum number of preserved jobs for the printer.
1202 void papplPrinterSetMaxPreservedJobs (
1204 pappl_printer_t *printer,
1205 int max_preserved_jobs
1206 );
1207 This function sets the maximum number of aborted, canceled, or com‐
1209 pleted jobs that are preserved (with document data) in the job history.
1210 papplPrinterSetNextJobID
1212 Set the next "job-id" value.
1213 void papplPrinterSetNextJobID (
1215 pappl_printer_t *printer,
1216 int next_job_id
1217 );
1218 This function sets the next unique positive integer identifier that
1220 will be used for a job.
1221 5 Note: This function is normally only called once to restore the
1223 previous
1224 5 state of the printer.
1226 papplPrinterSetOrganization
1228 Set the organization name.
1229 void papplPrinterSetOrganization (
1231 pappl_printer_t *printer,
1232 const char *value
1233 );
1234 This function sets the printer's organization name. If NULL the value
1236 is cleared.
1237 papplPrinterSetOrganizationalUnit
1239 Set the organizational unit name.
1240 void papplPrinterSetOrganizationalUnit (
1242 pappl_printer_t *printer,
1243 const char *value
1244 );
1245 This function sets the printer's organizational unit name. If NULL the
1247 value is cleared.
1248 papplPrinterSetPrintGroup
1250 Set the print authorization group, if any.
1251 void papplPrinterSetPrintGroup (
1253 pappl_printer_t *printer,
1254 const char *value
1255 );
1256 This function sets the printer's authorization group. If NULL, the
1258 group is cleared.
1259 5 Note: The authorization group is only used if the system is cre‐
1261 ated with a
1262 5 named authorization service.
1264 papplPrinterSetReadyMedia
1266 Set the ready (loaded) media.
1267 bool papplPrinterSetReadyMedia (
1269 pappl_printer_t *printer,
1270 int num_ready,
1271 pappl_media_col_t *ready
1272 );
1273 This function validates and sets the printer's ready (loaded) media.
1275 papplPrinterSetReasons
1277 Add or remove values from "printer-state-reasons".
1278 void papplPrinterSetReasons (
1280 pappl_printer_t *printer,
1281 pappl_preason_t add,
1282 pappl_preason_t remove
1283 );
1284 This function updates the printer state reasons bitfield by clearing
1286 any bit values in the "remove" argument and setting any bit values in
1287 the "add" argument.
1288 papplPrinterSetSupplies
1290 Set/update the supplies for a printer.
1291 void papplPrinterSetSupplies (
1293 pappl_printer_t *printer,
1294 int num_supplies,
1295 pappl_supply_t *supplies
1296 );
1297 This function updates the supply information for the printer.
1299 papplPrinterSetUSB
1301 Set the USB vendor and product IDs for a printer.
1302 void papplPrinterSetUSB (
1304 pappl_printer_t *printer,
1305 unsigned vendor_id,
1306 unsigned product_id,
1307 pappl_uoptions_t options,
1308 const char *storagefile,
1309 pappl_pr_usb_cb_t usb_cb,
1310 void *usb_cbdata
1311 );
1312 This function sets the USB vendor and product IDs for a printer as well
1314 as specifying USB gadget options when the printer is registered with
1315 the USB device controller.
1316 The usb_cb argument specifies a processing callback that is called for
1318 every byte of data sent from the USB host and which is responsible for
1319 interpreting the data, writing data to the device, and handling back-
1320 channel data.
1321 5 Note: USB gadget functionality is currently only available when
1323 running
1324 5 on Linux with compatible hardware such as the Raspberry Pi Zero
1326 and 4B.
1327
1329 pappl_icon_s
1330 Printer PNG icon structure
1331 struct pappl_icon_s
1333 {
1334 const void *data;
1335 size_t datalen;
1336 char filename[256];
1337 };
1338 pappl_media_col_s
1340 Media details structure
1341 struct pappl_media_col_s
1343 {
1344 int bottom_margin;
1345 int left_margin;
1346 int left_offset;
1347 int right_margin;
1348 int size_length;
1349 char size_name[64];
1350 int size_width;
1351 char source[64];
1352 int top_margin;
1353 int top_offset;
1354 pappl_media_tracking_t tracking;
1355 char type[64];
1356 };
1357 pappl_pr_driver_data_s
1359 Printer driver data
1360 struct pappl_pr_driver_data_s
1362 {
1363 const char *bin[PAPPL_MAX_BIN];
1364 int bin_default;
1365 bool borderless;
1366 int bottom_top;
1367 pappl_color_mode_t color_default;
1368 pappl_color_mode_t color_supported;
1369 pappl_content_t content_default;
1370 int darkness_configured;
1371 int darkness_default;
1372 int darkness_supported;
1373 pappl_pr_delete_cb_t delete_cb;
1374 pappl_duplex_t duplex;
1375 void *extension;
1376 const char *features[PAPPL_MAX_VENDOR];
1377 pappl_finishings_t finishings;
1378 pappl_raster_type_t force_raster_type;
1379 const char *format;
1380 pappl_dither_t gdither;
1381 bool has_supplies;
1382 pappl_icon_t icons[3];
1383 pappl_pr_identify_cb_t identify_cb;
1384 pappl_identify_actions_t identify_default;
1385 pappl_identify_actions_t identify_supported;
1386 bool input_face_up;
1387 pappl_kind_t kind;
1388 int left_offset_supported[2];
1389 int left_right;
1390 char make_and_model[128];
1391 const char *media[PAPPL_MAX_MEDIA];
1392 pappl_media_col_t media_default;
1393 pappl_media_col_t media_ready[PAPPL_MAX_SOURCE];
1394 pappl_label_mode_t mode_configured;
1395 pappl_label_mode_t mode_supported;
1396 int num_bin;
1397 int num_features;
1398 int num_media;
1399 int num_resolution;
1400 int num_source;
1401 int num_type;
1402 int num_vendor;
1403 ipp_orient_t orient_default;
1404 bool output_face_up;
1405 pappl_dither_t pdither;
1406 int ppm;
1407 int ppm_color;
1408 pappl_pr_printfile_cb_t printfile_cb;
1409 ipp_quality_t quality_default;
1410 pappl_raster_type_t raster_types;
1411 pappl_pr_rendjob_cb_t rendjob_cb;
1412 pappl_pr_rendpage_cb_t rendpage_cb;
1413 pappl_pr_rstartjob_cb_t rstartjob_cb;
1414 pappl_pr_rstartpage_cb_t rstartpage_cb;
1415 pappl_pr_rwriteline_cb_t rwriteline_cb;
1416 pappl_scaling_t scaling_default;
1417 pappl_sides_t sides_default;
1418 pappl_sides_t sides_supported;
1419 const char *source[PAPPL_MAX_SOURCE];
1420 int speed_default;
1421 int speed_supported[2];
1422 pappl_pr_status_cb_t status_cb;
1423 int tear_offset_configured;
1424 int tear_offset_supported[2];
1425 pappl_pr_testpage_cb_t testpage_cb;
1426 int top_offset_supported[2];
1427 pappl_media_tracking_t tracking_supported;
1428 const char *type[PAPPL_MAX_TYPE];
1429 const char *vendor[PAPPL_MAX_VENDOR];
1430 int x_default;
1431 int x_resolution[PAPPL_MAX_RESOLUTION];
1432 int y_default;
1433 int y_resolution[PAPPL_MAX_RESOLUTION];
1434 };
1435 pappl_pr_options_s
1437 Combined print job options
1438 struct pappl_pr_options_s
1440 {
1441 int copies;
1442 int darkness_configured;
1443 pappl_dither_t dither;
1444 pappl_finishings_t finishings;
1445 unsigned first_page;
1446 cups_page_header2_t header;
1447 unsigned last_page;
1448 pappl_media_col_t media;
1449 unsigned num_pages;
1450 int num_vendor;
1451 ipp_orient_t orientation_requested;
1452 char output_bin[64];
1453 pappl_color_mode_t print_color_mode;
1454 pappl_content_t print_content_optimize;
1455 int print_darkness;
1456 ipp_quality_t print_quality;
1457 pappl_scaling_t print_scaling;
1458 int print_speed;
1459 int printer_resolution[2];
1460 pappl_sides_t sides;
1461 cups_option_t *vendor;
1462 };
1463
1465 pappl_color_mode_t
1466 Bitfield for IPP "print-color-mode" values
1467 typedef unsigned pappl_color_mode_t;
1469 pappl_content_t
1471 Bitfield for IPP "print-content-optimize" values
1472 typedef unsigned pappl_content_t;
1474 pappl_default_cb_t
1476 papplIterateDefaults callback
1477 typedef void (*pappl_default_cb_t)(ipp_attribute_t *attr, void *data);
1479 pappl_duplex_t
1481 Duplex printing support
1482 typedef enum pappl_duplex_e pappl_duplex_t;
1484 pappl_finishings_t
1486 Bitfield for IPP "finishings" values
1487 typedef unsigned pappl_finishings_t;
1489 pappl_icon_t
1491 Printer PNG icon structure
1492 typedef struct pappl_icon_s pappl_icon_t;
1494 pappl_identify_actions_t
1496 Bitfield for IPP "identify-actions" values
1497 typedef unsigned pappl_identify_actions_t;
1499 pappl_job_cb_t
1501 papplIterateXxxJobs callback function
1502 typedef void (*pappl_job_cb_t)(pappl_job_t *job, void *data);
1504 pappl_kind_t
1506 Bitfield for IPP "printer-kind" values
1507 typedef unsigned pappl_kind_t;
1509 pappl_label_mode_t
1511 Bitfield for IPP "label-mode-xxx" values
1512 typedef unsigned short pappl_label_mode_t;
1514 pappl_media_col_t
1516 Media details structure
1517 typedef struct pappl_media_col_s pappl_media_col_t;
1519 pappl_media_tracking_t
1521 Bitfield for IPP "media-tracking" values
1522 typedef unsigned short pappl_media_tracking_t;
1524 pappl_pr_delete_cb_t
1526 Printer deletion callback
1527 typedef void (*pappl_pr_delete_cb_t)(pappl_printer_t *printer, pappl_pr_driver_data_t *data);
1529 pappl_pr_identify_cb_t
1531 Identify-Printer callback
1532 typedef void (*pappl_pr_identify_cb_t)(pappl_printer_t *printer, pappl_identify_actions_t actions, const char *message);
1534 pappl_pr_printfile_cb_t
1536 Print a "raw" job callback
1537 typedef bool (*pappl_pr_printfile_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device);
1539 pappl_pr_rendjob_cb_t
1541 End a raster job callback
1542 typedef bool (*pappl_pr_rendjob_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device);
1544 pappl_pr_rendpage_cb_t
1546 End a raster page callback
1547 typedef bool (*pappl_pr_rendpage_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device, unsigned page);
1549 pappl_pr_rstartjob_cb_t
1551 Start a raster job callback
1552 typedef bool (*pappl_pr_rstartjob_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device);
1554 pappl_pr_rstartpage_cb_t
1556 Start a raster page callback
1557 typedef bool (*pappl_pr_rstartpage_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device, unsigned page);
1559 pappl_pr_rwriteline_cb_t
1561 Write a line of raster graphics callback
1562 typedef bool (*pappl_pr_rwriteline_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device, unsigned y, const unsigned char *line);
1564 pappl_pr_status_cb_t
1566 Update printer status callback
1567 typedef bool (*pappl_pr_status_cb_t)(pappl_printer_t *printer);
1569 pappl_pr_testpage_cb_t
1571 Print a test page callback
1572 typedef const char * (*pappl_pr_testpage_cb_t)(pappl_printer_t *printer, char *buffer, size_t bufsize);
1574 pappl_pr_usb_cb_t
1576 Raw USB IO callback
1577 typedef ssize_t (*pappl_pr_usb_cb_t)(pappl_printer_t *printer, pappl_device_t *device, void *buffer, size_t bufsize, size_t bytes, void *data);
1579 pappl_raster_type_t
1581 Bitfield for IPP "pwg-raster-document-type-supported" values
1582 typedef unsigned pappl_raster_type_t;
1584 pappl_scaling_t
1586 Bitfield for IPP "print-scaling" values
1587 typedef unsigned pappl_scaling_t;
1589 pappl_sides_t
1591 Bitfield for IPP "sides" values
1592 typedef unsigned pappl_sides_t;
1594 pappl_uoptions_t
1596 USB gadget options bitfield
1597 typedef unsigned pappl_uoptions_t;
1599
1601 pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3),
1602 pappl-mainline(3), pappl-makeresheader(1), pappl-printer(3), pappl-re‐
1603 source(3), pappl-system(3), https://www.msweet.org/pappl
1604
1606 Copyright © 2019-2022 by Michael R Sweet.
1607 PAPPL is licensed under the Apache License Version 2.0 with an (op‐
1609 tional) exception to allow linking against GPL2/LGPL2 software (like
1610 older versions of CUPS), so it can be used freely in any project you'd
1611 like. See the files "LICENSE" and "NOTICE" in the source distribution
1612 for more information.
16132022-05-10 pappl printer functions pappl-printer(3)