.TH pappl-printer 3 "pappl printer functions" "2020-12-08" "pappl printer functions" .SH NAME pappl-printer \- pappl printer functions .SH LIBRARY Printer Application Framework (libpappl, "pkg-config --cflags --libs pappl") .SH SYNOPSIS .B #include .PP .I typedef struct _pappl_printer_s .B pappl_printer_t; .PP .I void .br .BI papplPrinterCancelAllJobs "(pappl_printer_t *printer);" .PP .I void .br .BI papplPrinterCloseDevice "(pappl_printer_t *printer);" .PP .I pappl_printer_t * .br .BI papplPrinterCreate "(pappl_system_t *system, int printer_id, const char *printer_name, const char *driver_name, const char *device_id, const char *device_uri);" .PP .I void .br .BI papplPrinterDelete "(pappl_printer_t *printer);" .PP .I pappl_job_t * .br .BI papplPrinterFindJob "(pappl_printer_t *printer, int job_id);" .PP .I pappl_contact_t * .br .BI papplPrinterGetContact "(pappl_printer_t *printer, pappl_contact_t *contact);" .PP .I const char * .br .BI papplPrinterGetDeviceID "(pappl_printer_t *printer);" .PP .I const char * .br .BI papplPrinterGetDeviceURI "(pappl_printer_t *printer);" .PP .I char * .br .BI papplPrinterGetDNSSDName "(pappl_printer_t *printer, char *buffer, size_t bufsize);" .PP .I ipp_t * .br .BI papplPrinterGetDriverAttributes "(pappl_printer_t *printer);" .PP .I pappl_driver_data_t * .br .BI papplPrinterGetDriverData "(pappl_printer_t *printer, pappl_driver_data_t *data);" .PP .I const char * .br .BI papplPrinterGetDriverName "(pappl_printer_t *printer);" .PP .I char * .br .BI papplPrinterGetGeoLocation "(pappl_printer_t *printer, char *buffer, size_t bufsize);" .PP .I int .br .BI papplPrinterGetID "(pappl_printer_t *printer);" .PP .I int .br .BI papplPrinterGetImpressionsCompleted "(pappl_printer_t *printer);" .PP .I char * .br .BI papplPrinterGetLocation "(pappl_printer_t *printer, char *buffer, size_t bufsize);" .PP .I int .br .BI papplPrinterGetMaxActiveJobs "(pappl_printer_t *printer);" .PP .I int .br .BI papplPrinterGetMaxCompletedJobs "(pappl_printer_t *printer);" .PP .I const char * .br .BI papplPrinterGetName "(pappl_printer_t *printer);" .PP .I int .br .BI papplPrinterGetNextJobID "(pappl_printer_t *printer);" .PP .I int .br .BI papplPrinterGetNumberOfActiveJobs "(pappl_printer_t *printer);" .PP .I int .br .BI papplPrinterGetNumberOfCompletedJobs "(pappl_printer_t *printer);" .PP .I int .br .BI papplPrinterGetNumberOfJobs "(pappl_printer_t *printer);" .PP .I char * .br .BI papplPrinterGetOrganization "(pappl_printer_t *printer, char *buffer, size_t bufsize);" .PP .I char * .br .BI papplPrinterGetOrganizationalUnit "(pappl_printer_t *printer, char *buffer, size_t bufsize);" .PP .I char * .br .BI papplPrinterGetPrintGroup "(pappl_printer_t *printer, char *buffer, size_t bufsize);" .PP .I pappl_preason_t .br .BI papplPrinterGetReasons "(pappl_printer_t *printer);" .PP .I ipp_pstate_t .br .BI papplPrinterGetState "(pappl_printer_t *printer);" .PP .I int .br .BI papplPrinterGetSupplies "(pappl_printer_t *printer, int max_supplies, pappl_supply_t *supplies);" .PP .I pappl_system_t * .br .BI papplPrinterGetSystem "(pappl_printer_t *printer);" .PP .I void .br .BI papplPrinterIterateActiveJobs "(pappl_printer_t *printer, pappl_job_cb_t cb, void *data, int first_index, int limit);" .PP .I void .br .BI papplPrinterIterateAllJobs "(pappl_printer_t *printer, pappl_job_cb_t cb, void *data, int first_index, int limit);" .PP .I void .br .BI papplPrinterIterateCompletedJobs "(pappl_printer_t *printer, pappl_job_cb_t cb, void *data, int first_index, int limit);" .PP .I pappl_device_t * .br .BI papplPrinterOpenDevice "(pappl_printer_t *printer);" .PP .I void .br .BI papplPrinterPause "(pappl_printer_t *printer);" .PP .I void .br .BI papplPrinterResume "(pappl_printer_t *printer);" .PP .I void .br .BI papplPrinterSetContact "(pappl_printer_t *printer, pappl_contact_t *contact);" .PP .I void .br .BI papplPrinterSetDNSSDName "(pappl_printer_t *printer, const char *value);" .PP .I void .br .BI papplPrinterSetDriverData "(pappl_printer_t *printer, pappl_driver_data_t *data, ipp_t *attrs);" .PP .I void .br .BI papplPrinterSetDriverDefaults "(pappl_printer_t *printer, pappl_driver_data_t *data);" .PP .I void .br .BI papplPrinterSetGeoLocation "(pappl_printer_t *printer, const char *value);" .PP .I void .br .BI papplPrinterSetImpressionsCompleted "(pappl_printer_t *printer, int add);" .PP .I void .br .BI papplPrinterSetLocation "(pappl_printer_t *printer, const char *value);" .PP .I void .br .BI papplPrinterSetMaxActiveJobs "(pappl_printer_t *printer, int max_active_jobs);" .PP .I void .br .BI papplPrinterSetMaxCompletedJobs "(pappl_printer_t *printer, int max_completed_jobs);" .PP .I void .br .BI papplPrinterSetNextJobID "(pappl_printer_t *printer, int next_job_id);" .PP .I void .br .BI papplPrinterSetOrganization "(pappl_printer_t *printer, const char *value);" .PP .I void .br .BI papplPrinterSetOrganizationalUnit "(pappl_printer_t *printer, const char *value);" .PP .I void .br .BI papplPrinterSetPrintGroup "(pappl_printer_t *printer, const char *value);" .PP .I void .br .BI papplPrinterSetReadyMedia "(pappl_printer_t *printer, int num_ready, pappl_media_col_t *ready);" .PP .I void .br .BI papplPrinterSetReasons "(pappl_printer_t *printer, pappl_preason_t add, pappl_preason_t remove);" .PP .I void .br .BI papplPrinterSetSupplies "(pappl_printer_t *printer, int num_supplies, pappl_supply_t *supplies);" .PP .I void .br .BI papplPrinterSetUSB "(pappl_printer_t *printer, unsigned vendor_id, unsigned product_id, pappl_uoptions_t options);" .SH DESCRIPTION The .B PAPPL printer functions provide access to the printer object. Printers are created and deleted by the printer application while the life cycle of the .B pappl_printer_t objects are managed automatically by the system object for the printer application. .PP The .B papplPrinterCreate function creates a new printer while the .B papplPrinterDelete function deletes a printer. .PP The .B papplPrinterPause function stops a printer while the .B papplPrinterResume function starts a printer. .PP The .B papplPrinterGet functions get the current values associated with a printer while the .B papplPrinterSet functions set the current values associated with a printer. .PP The .B papplPrinterCancelAddJobs, papplPrinterFindJob, .B papplPrinterGetNumberOfActiveJobs, papplPrinterGetNumberOfCompletedJobs, .B papplPrinterGetNumberOfJobs, papplPrinterIterateActiveJobs, .B papplPrinterIterateAllJobs, and .B papplPrinterIterateCompletedJobs functions provide access to the jobs queued on a printer. .PP The .B papplPrinterOpenDevice function provides access to the device associated with a printer when it is not processing a job. The device must be later closed using the .B papplPrinterCloseDevice function so that the printer can resume job processing. .SH ENUMERATIONS .SS pappl_color_mode_e IPP "print-color-mode" bit values .TP 5 PAPPL_COLOR_MODE_AUTO .br 'auto' - Automatic color/monochrome print mode .TP 5 PAPPL_COLOR_MODE_AUTO_MONOCHROME .br 'auto-monochrome' - Automatic monochrome/process monochrome print mode .TP 5 PAPPL_COLOR_MODE_BI_LEVEL .br 'bi-level' - B&W (threshold) print mode .TP 5 PAPPL_COLOR_MODE_COLOR .br 'color' - Full color print mode .TP 5 PAPPL_COLOR_MODE_MONOCHROME .br 'monochrome' - Grayscale print mode using 1 color .TP 5 PAPPL_COLOR_MODE_PROCESS_MONOCHROME .br 'process-monochrome' - Grayscale print mode using multiple colors .SS pappl_content_e IPP "print-content-optimize" bit values .TP 5 PAPPL_CONTENT_AUTO .br 'auto': Automatically determine content .TP 5 PAPPL_CONTENT_GRAPHIC .br 'graphic': Optimize for vector graphics .TP 5 PAPPL_CONTENT_PHOTO .br 'photo': Optimize for photos/continuous tone images .TP 5 PAPPL_CONTENT_TEXT .br 'text': Optimize for text .TP 5 PAPPL_CONTENT_TEXT_AND_GRAPHIC .br 'text-and-graphic': Optimize for text and vector graphics .SS pappl_duplex_e Duplex printing support .TP 5 PAPPL_DUPLEX_FLIPPED .br Duplex with flipped back sides .TP 5 PAPPL_DUPLEX_MANUAL_TUMBLE .br Duplex with back side rotated 180 degrees for short-edge duplex .TP 5 PAPPL_DUPLEX_NONE .br No duplex printing support .TP 5 PAPPL_DUPLEX_NORMAL .br Duplex with normal back sides .TP 5 PAPPL_DUPLEX_ROTATED .br Duplex with back side rotated 180 degrees for long-edge duplex .SS pappl_finishings_e IPP "finishings" bit values .TP 5 PAPPL_FINISHINGS_NONE .br 'none' .TP 5 PAPPL_FINISHINGS_PUNCH .br 'punch' .TP 5 PAPPL_FINISHINGS_STAPLE .br 'staple' .TP 5 PAPPL_FINISHINGS_TRIM .br 'trim' .SS pappl_identify_actions_e IPP "identify-actions" bit values .TP 5 PAPPL_IDENTIFY_ACTIONS_DISPLAY .br 'display': Display a message .TP 5 PAPPL_IDENTIFY_ACTIONS_FLASH .br 'flash': Flash the display or a light .TP 5 PAPPL_IDENTIFY_ACTIONS_NONE .br No actions .TP 5 PAPPL_IDENTIFY_ACTIONS_SOUND .br 'sound': Make a sound .TP 5 PAPPL_IDENTIFY_ACTIONS_SPEAK .br 'speak': Speak a message .SS pappl_kind_e IPP "printer-kind" bit values .TP 5 PAPPL_KIND_DISC .br 'disc' .TP 5 PAPPL_KIND_DOCUMENT .br 'document' .TP 5 PAPPL_KIND_ENVELOPE .br 'envelope' .TP 5 PAPPL_KIND_LABEL .br 'label' .TP 5 PAPPL_KIND_LARGE_FORMAT .br 'large-format' .TP 5 PAPPL_KIND_PHOTO .br 'photo' .TP 5 PAPPL_KIND_POSTCARD .br 'postcard' .TP 5 PAPPL_KIND_RECEIPT .br 'receipt' .TP 5 PAPPL_KIND_ROLL .br 'roll' .SS pappl_label_mode_e IPP "label-mode-xxx" bit values .TP 5 PAPPL_LABEL_MODE_APPLICATOR .br 'applicator' .TP 5 PAPPL_LABEL_MODE_CUTTER .br 'cutter' .TP 5 PAPPL_LABEL_MODE_CUTTER_DELAYED .br 'cutter-delayed' .TP 5 PAPPL_LABEL_MODE_KIOSK .br 'kiosk' .TP 5 PAPPL_LABEL_MODE_PEEL_OFF .br 'peel-off' .TP 5 PAPPL_LABEL_MODE_PEEL_OFF_PREPEEL .br 'peel-off-prepeel' .TP 5 PAPPL_LABEL_MODE_REWIND .br 'rewind' .TP 5 PAPPL_LABEL_MODE_RFID .br 'rfid' .TP 5 PAPPL_LABEL_MODE_TEAR_OFF .br 'tear-off' .SS pappl_media_tracking_e IPP "media-tracking" bit values .TP 5 PAPPL_MEDIA_TRACKING_CONTINUOUS .br 'continuous' .TP 5 PAPPL_MEDIA_TRACKING_GAP .br 'gap' .TP 5 PAPPL_MEDIA_TRACKING_MARK .br 'mark' .TP 5 PAPPL_MEDIA_TRACKING_WEB .br 'web' .SS pappl_preason_e IPP "printer-state-reasons" bit values .TP 5 PAPPL_PREASON_COVER_OPEN .br 'cover-open' .TP 5 PAPPL_PREASON_DEVICE_STATUS .br Supported \fIpapplDeviceGetStatus\fR bits .TP 5 PAPPL_PREASON_INPUT_TRAY_MISSING .br 'input-tray-missing' .TP 5 PAPPL_PREASON_MARKER_SUPPLY_EMPTY .br 'marker-supply-empty' .TP 5 PAPPL_PREASON_MARKER_SUPPLY_LOW .br 'marker-supply-low' .TP 5 PAPPL_PREASON_MARKER_WASTE_ALMOST_FULL .br 'marker-waste-almost-full' .TP 5 PAPPL_PREASON_MARKER_WASTE_FULL .br 'marker-waste-full' .TP 5 PAPPL_PREASON_MEDIA_EMPTY .br 'media-empty' .TP 5 PAPPL_PREASON_MEDIA_JAM .br 'media-jam' .TP 5 PAPPL_PREASON_MEDIA_LOW .br 'media-low' .TP 5 PAPPL_PREASON_MEDIA_NEEDED .br 'media-needed' .TP 5 PAPPL_PREASON_NONE .br 'none' .TP 5 PAPPL_PREASON_OFFLINE .br 'offline' .TP 5 PAPPL_PREASON_OTHER .br 'other' .TP 5 PAPPL_PREASON_SPOOL_AREA_FULL .br 'spool-area-full' .TP 5 PAPPL_PREASON_TONER_EMPTY .br 'toner-empty' .TP 5 PAPPL_PREASON_TONER_LOW .br 'toner-low' .SS pappl_raster_type_e IPP "pwg-raster-document-type-supported" bit values .TP 5 PAPPL_PWG_RASTER_TYPE_ADOBE_RGB_16 .br 16-bit per component AdobeRGB .TP 5 PAPPL_PWG_RASTER_TYPE_ADOBE_RGB_8 .br 8-bit per component AdobeRGB .TP 5 PAPPL_PWG_RASTER_TYPE_BLACK_1 .br 1-bit (device) black .TP 5 PAPPL_PWG_RASTER_TYPE_BLACK_16 .br 16-bit (device) black .TP 5 PAPPL_PWG_RASTER_TYPE_BLACK_8 .br 8-bit (device) black .TP 5 PAPPL_PWG_RASTER_TYPE_CMYK_16 .br 16-bit per component (device) CMYK .TP 5 PAPPL_PWG_RASTER_TYPE_CMYK_8 .br 8-bit per component (device) CMYK .TP 5 PAPPL_PWG_RASTER_TYPE_NONE .br Do not force a particular raster type .TP 5 PAPPL_PWG_RASTER_TYPE_RGB_16 .br 16-bit per component (device) RGB) .TP 5 PAPPL_PWG_RASTER_TYPE_RGB_8 .br 8-bit per component (device) RGB .TP 5 PAPPL_PWG_RASTER_TYPE_SGRAY_16 .br 16-bit grayscale with 2.2 gamma .TP 5 PAPPL_PWG_RASTER_TYPE_SGRAY_8 .br 8-bit grayscale with 2.2 gamma .TP 5 PAPPL_PWG_RASTER_TYPE_SRGB_16 .br 16-bit per component sRGB .TP 5 PAPPL_PWG_RASTER_TYPE_SRGB_8 .br 8-bit per component sRGB .SS pappl_scaling_e IPP "print-scaling" bit values .TP 5 PAPPL_SCALING_AUTO .br 'auto': Scale to fit (non-borderless) or fill (borderless) if larger, otherwise center .TP 5 PAPPL_SCALING_AUTO_FIT .br 'auto-fit': Scale to fit if larger, otherwise center .TP 5 PAPPL_SCALING_FILL .br 'fill': Scale to fill the media .TP 5 PAPPL_SCALING_FIT .br 'fit': Scale to fit within margins .TP 5 PAPPL_SCALING_NONE .br 'none': No scaling (center/crop) .SS pappl_sides_e IPP "sides" bit values .TP 5 PAPPL_SIDES_ONE_SIDED .br 'one-sided' .TP 5 PAPPL_SIDES_TWO_SIDED_LONG_EDGE .br 'two-sided-long-edge' .TP 5 PAPPL_SIDES_TWO_SIDED_SHORT_EDGE .br 'two-sided-short-edge' .SS pappl_supply_color_e "printer-supply" color values .TP 5 PAPPL_SUPPLY_COLOR_BLACK .br Black ink/toner (photo or matte) .TP 5 PAPPL_SUPPLY_COLOR_CYAN .br Cyan ink/toner .TP 5 PAPPL_SUPPLY_COLOR_GRAY .br Gray ink (sometimes marketed as light gray) .TP 5 PAPPL_SUPPLY_COLOR_GREEN .br Green ink .TP 5 PAPPL_SUPPLY_COLOR_LIGHT_CYAN .br Light cyan ink .TP 5 PAPPL_SUPPLY_COLOR_LIGHT_GRAY .br Light gray ink (sometimes marketed as light light gray) .TP 5 PAPPL_SUPPLY_COLOR_LIGHT_MAGENTA .br Light magenta ink .TP 5 PAPPL_SUPPLY_COLOR_MAGENTA .br Magenta ink/toner .TP 5 PAPPL_SUPPLY_COLOR_NO_COLOR .br No color (waste tank, etc.) .TP 5 PAPPL_SUPPLY_COLOR_ORANGE .br Orange ink .TP 5 PAPPL_SUPPLY_COLOR_VIOLET .br Violet ink .TP 5 PAPPL_SUPPLY_COLOR_YELLOW .br Yellow ink/toner .SS pappl_supply_type_e IPP "printer-supply" type values .TP 5 PAPPL_SUPPLY_TYPE_BANDING_SUPPLY .br Banding finisher supplies .TP 5 PAPPL_SUPPLY_TYPE_BINDING_SUPPLY .br Binding finisher supplies .TP 5 PAPPL_SUPPLY_TYPE_CLEANER_UNIT .br Cleaning unit .TP 5 PAPPL_SUPPLY_TYPE_CORONA_WIRE .br Corona wire (laser printers) .TP 5 PAPPL_SUPPLY_TYPE_COVERS .br Cover finisher supplies .TP 5 PAPPL_SUPPLY_TYPE_DEVELOPER .br Developer supply .TP 5 PAPPL_SUPPLY_TYPE_FUSER .br Fuser (laser printers) .TP 5 PAPPL_SUPPLY_TYPE_FUSER_CLEANING_PAD .br Fuser cleaning pad (laser printers) .TP 5 PAPPL_SUPPLY_TYPE_FUSER_OIL .br Fuser oil supply (laser printers) .TP 5 PAPPL_SUPPLY_TYPE_FUSER_OILER .br Fuser oiler (laser printers) .TP 5 PAPPL_SUPPLY_TYPE_FUSER_OIL_WICK .br Fuser oil wick (laser printers) .TP 5 PAPPL_SUPPLY_TYPE_INK .br Ink supply .TP 5 PAPPL_SUPPLY_TYPE_INK_CARTRIDGE .br Ink cartridge .TP 5 PAPPL_SUPPLY_TYPE_INK_RIBBON .br Ink ribbon supply .TP 5 PAPPL_SUPPLY_TYPE_INSERTS .br Insert finisher supplies .TP 5 PAPPL_SUPPLY_TYPE_OPC .br Optical photoconductor (laser printers) .TP 5 PAPPL_SUPPLY_TYPE_PAPER_WRAP .br Wrap finisher supplies .TP 5 PAPPL_SUPPLY_TYPE_RIBBON_WAX .br Wax ribbon supply .TP 5 PAPPL_SUPPLY_TYPE_SOLID_WAX .br Solid wax supply .TP 5 PAPPL_SUPPLY_TYPE_STAPLES .br Staple finisher supplies .TP 5 PAPPL_SUPPLY_TYPE_STITCHING_WIRE .br Staple/stitch finisher supplies .TP 5 PAPPL_SUPPLY_TYPE_TONER .br Toner supply .TP 5 PAPPL_SUPPLY_TYPE_TONER_CARTRIDGE .br Toner cartridge .TP 5 PAPPL_SUPPLY_TYPE_TRANSFER_UNIT .br Transfer unit (laser printers) .TP 5 PAPPL_SUPPLY_TYPE_WASTE_INK .br Waste ink .TP 5 PAPPL_SUPPLY_TYPE_WASTE_TONER .br Waste toner .TP 5 PAPPL_SUPPLY_TYPE_WASTE_WATER .br Waste water .TP 5 PAPPL_SUPPLY_TYPE_WASTE_WAX .br Waste wax .TP 5 PAPPL_SUPPLY_TYPE_WATER .br Water supply .SS pappl_uoptions_e USB gadget options .TP 5 PAPPL_UOPTIONS_ETHERNET .br Include USB ethernet gadget .TP 5 PAPPL_UOPTIONS_NONE .br No options (just USB printer) .TP 5 PAPPL_UOPTIONS_SERIAL .br Include USB serial gadget .TP 5 PAPPL_UOPTIONS_STORAGE .br Include USB mass storage gadget .TP 5 PAPPL_UOPTIONS_STORAGE_READONLY .br USB mass storage gadget is read-only .TP 5 PAPPL_UOPTIONS_STORAGE_REMOVABLE .br USB mass storage gadget is removable .SH FUNCTIONS .SS papplPrinterCancelAllJobs Cancel all jobs on the printer. .PP .nf void papplPrinterCancelAllJobs ( pappl_printer_t *printer ); .fi .PP This function cancels all jobs on the printer. If any job is currently being printed, it will be stopped at a convenient time (usually the end of a page) so that the printer will be left in a known state. .SS papplPrinterCloseDevice Close the device associated with the printer. .PP .nf void papplPrinterCloseDevice ( pappl_printer_t *printer ); .fi .PP This function closes the device for a printer. The device must have been previously opened using the \fIpapplPrinterOpenDevice\fR function. .SS papplPrinterCreate Create a new printer. .PP .nf pappl_printer_t * papplPrinterCreate ( pappl_system_t *system, int printer_id, const char *printer_name, const char *driver_name, const char *device_id, const char *device_uri ); .fi .PP This function creates a new printer (service) on the specified system. The "type" argument specifies the type of service to create and must currently be the value \fBPAPPL_SERVICE_TYPE_PRINT\fR. .PP The "printer_id" argument specifies a positive integer identifier that is unique to the system. If you specify a value of \fB0\fR a new identifier will be assigned. .PP The "driver_name" argument specifies a named driver for the printer, from the list of drivers registered with the \fIpapplSystemSetPrinterDrivers\fR function. .PP The "device_id" and "device_uri" arguments specify the IEEE-1284 device ID and device URI strings for the printer. .PP On error, this function sets the \fBerrno\fR variable to one of the following values: .PP .IP \(bu 5 \fBEEXIST\fR: A printer with the specified name already exists. .IP \(bu 5 \fBEINVAL\fR: Bad values for the arguments were specified. .IP \(bu 5 \fBEIO\fR: The driver callback failed. .IP \(bu 5 \fBENOENT\fR: No driver callback has been set. .IP \(bu 5 \fBENOMEM\fR: Ran out of memory. .SS papplPrinterDelete Delete a printer. .PP .nf void papplPrinterDelete ( pappl_printer_t *printer ); .fi .PP This function deletes a printer from a system, freeing all memory and canceling all jobs as needed. .SS papplPrinterGetContact Get the "printer-contact" value. .PP .nf pappl_contact_t * papplPrinterGetContact ( pappl_printer_t *printer, pappl_contact_t *contact ); .fi .PP This function copies the current printer contact information to the buffer pointed to by the "contact" argument. .SS papplPrinterGetDNSSDName Get the current DNS-SD service name. .PP .nf char * papplPrinterGetDNSSDName ( pappl_printer_t *printer, char *buffer, size_t bufsize ); .fi .PP This function copies the current DNS-SD service name to the buffer pointed to by the "buffer" argument. .SS papplPrinterGetDeviceID Get the IEEE-1284 device ID of the printer. .PP .nf const char * papplPrinterGetDeviceID ( pappl_printer_t *printer ); .fi .PP This function returns the IEEE-1284 device ID of the printer. .SS papplPrinterGetDeviceURI Get the URI of the device associated with the printer. .PP .nf const char * papplPrinterGetDeviceURI ( pappl_printer_t *printer ); .fi .PP This function returns the device URI for the printer. .SS papplPrinterGetDriverAttributes Get the current driver attributes. .PP .nf ipp_t * papplPrinterGetDriverAttributes ( pappl_printer_t *printer ); .fi .PP This function returns the current driver attributes. .SS papplPrinterGetDriverData Get the current print driver data. .PP .nf pappl_pr_driver_data_t * papplPrinterGetDriverData ( pappl_printer_t *printer, pappl_pr_driver_data_t *data ); .fi .PP This function copies the current print driver data, defaults, and ready (loaded) media information into the specified buffer. .SS papplPrinterGetDriverName Get the driver name for a printer. .PP .nf const char * papplPrinterGetDriverName ( pappl_printer_t *printer ); .fi .PP This function returns the driver name for the printer. .SS papplPrinterGetGeoLocation Get the current geo-location as a "geo:" URI. .PP .nf char * papplPrinterGetGeoLocation ( pappl_printer_t *printer, char *buffer, size_t bufsize ); .fi .PP This function copies the currently configured geographic location as a "geo:" URI to the buffer pointed to by the "buffer" argument. .SS papplPrinterGetID Get the printer ID. .PP .nf int papplPrinterGetID ( pappl_printer_t *printer ); .fi .PP This function returns the printer's unique positive integer identifier. .SS papplPrinterGetImpressionsCompleted Get the number of impressions (sides) that have been printed. .PP .nf int papplPrinterGetImpressionsCompleted ( pappl_printer_t *printer ); .fi .PP This function returns the number of impressions that have been printed. An impression is one side of an output page. .SS papplPrinterGetLocation Get the location string. .PP .nf char * papplPrinterGetLocation ( pappl_printer_t *printer, char *buffer, size_t bufsize ); .fi .PP This function copies the printer's human-readable location to the buffer pointed to by the "buffer" argument. .SS papplPrinterGetMaxActiveJobs Get the maximum number of active (queued) jobs allowed by the printer. .PP .nf int papplPrinterGetMaxActiveJobs ( pappl_printer_t *printer ); .fi .PP This function returns the maximum number of active jobs that the printer supports, as configured by the \fIpapplPrinterSetMaxActiveJobs\fR function. .SS papplPrinterGetMaxCompletedJobs Get the maximum number of jobs retained for history by the printer. .PP .nf int papplPrinterGetMaxCompletedJobs ( pappl_printer_t *printer ); .fi .PP This function returns the maximum number of jobs that are retained in the job history as configured by the \fIpapplPrinterSetMaxCompletedJobs\fR function. .SS papplPrinterGetName Get the printer name. .PP .nf const char * papplPrinterGetName ( pappl_printer_t *printer ); .fi .PP This function returns the printer's human-readable name. .SS papplPrinterGetNextJobID Get the next job ID. .PP .nf int papplPrinterGetNextJobID ( pappl_printer_t *printer ); .fi .PP This function returns the positive integer identifier that will be used for the next job that is created. .SS papplPrinterGetNumberOfActiveJobs Get the number of active print jobs. .PP .nf int papplPrinterGetNumberOfActiveJobs ( pappl_printer_t *printer ); .fi .PP This function returns the number of print jobs that are either printing or waiting to be printed. .SS papplPrinterGetNumberOfCompletedJobs Get the number of completed print jobs. .PP .nf int papplPrinterGetNumberOfCompletedJobs ( pappl_printer_t *printer ); .fi .PP This function returns the number of print jobs that have been aborted, canceled, or completed. .SS papplPrinterGetNumberOfJobs Get the total number of print jobs. .PP .nf int papplPrinterGetNumberOfJobs ( pappl_printer_t *printer ); .fi .PP This function returns the number of print jobs that are printing, waiting to be printed, have been aborted, have been canceled, or have completed. .SS papplPrinterGetOrganization Get the organization name. .PP .nf char * papplPrinterGetOrganization ( pappl_printer_t *printer, char *buffer, size_t bufsize ); .fi .PP This function copies the printer's organization name to the buffer pointed to by the "buffer" argument. .SS papplPrinterGetOrganizationalUnit Get the organizational unit name. .PP .nf char * papplPrinterGetOrganizationalUnit ( pappl_printer_t *printer, char *buffer, size_t bufsize ); .fi .PP This function copies the printer's organizational unit name to the buffer pointed to by the "buffer" argument. .SS papplPrinterGetPath Get the URL path for a printer web page. .PP .nf char * papplPrinterGetPath ( pappl_printer_t *printer, const char *subpath, char *buffer, size_t bufsize ); .fi .PP This function generates and returns the URL path for the printer's web page. The "subpath" argument specifies an optional sub-path for a specific printer web page. .SS papplPrinterGetPrintGroup Get the print authorization group, if any. .PP .nf char * papplPrinterGetPrintGroup ( pappl_printer_t *printer, char *buffer, size_t bufsize ); .fi .PP This function copies the printer's authorization group name to the buffer pointed to by the "buffer" argument. .SS papplPrinterGetReasons Get the current "printer-state-reasons" bit values. .PP .nf pappl_preason_t papplPrinterGetReasons ( pappl_printer_t *printer ); .fi .PP This function returns the current printer state reasons bitfield, which can be updated by the printer driver and/or by the \fIpapplPrinterSetReasons\fR function. .SS papplPrinterGetState Get the current "printer-state" value. .PP .nf ipp_pstate_t papplPrinterGetState ( pappl_printer_t *printer ); .fi .PP This function returns the current printer state as an enumeration: .PP .IP \(bu 5 \fBIPP_PSTATE_IDLE\fR: The printer is idle and has no jobs to process. .IP \(bu 5 \fBIPP_PSTATE_PROCESSING\fR: The printer is processing a job and/or producing output. .IP \(bu 5 \fBIPP_PSTATE_STOPPED\fR: The printer is stopped for maintenance. .SS papplPrinterGetSupplies Get the current "printer-supplies" values. .PP .nf int papplPrinterGetSupplies ( pappl_printer_t *printer, int max_supplies, pappl_supply_t *supplies ); .fi .PP This function copies the current printer supply values to the specified array. The "max_supplies" and "supplies" arguments can be \fB0\fR and \fBNULL\fR to query the number of supplies used. .PP The return value is the actual number of supplies used by the printer, regardless of the size of the array. .SS papplPrinterGetSystem Get the system associated with the printer. .PP .nf pappl_system_t * papplPrinterGetSystem ( pappl_printer_t *printer ); .fi .PP This function returns a pointer to the system object that contains the printer. .SS papplPrinterIterateActiveJobs Iterate over the active jobs. .PP .nf void papplPrinterIterateActiveJobs ( pappl_printer_t *printer, pappl_job_cb_t cb, void *data, int job_index, int limit ); .fi .PP This function iterates over jobs that are either printing or waiting to be printed. The specified callback "cb" will be called once per job with the data pointer "data". .PP The "job_index" argument specifies the first job in the list to iterate, where \fB1\fR is the first job, etc. The "limit" argument specifies the maximum number of jobs to iterate - use \fB0\fR to iterate an unlimited number of jobs. .SS papplPrinterIterateAllJobs Iterate over all the jobs. .PP .nf void papplPrinterIterateAllJobs ( pappl_printer_t *printer, pappl_job_cb_t cb, void *data, int job_index, int limit ); .fi .PP This function iterates over all jobs. The specified callback "cb" will be called once per job with the data pointer "data". .PP The "job_index" argument specifies the first job in the list to iterate, where \fB1\fR is the first job, etc. The "limit" argument specifies the maximum number of jobs to iterate - use \fB0\fR to iterate an unlimited number of jobs. .SS papplPrinterIterateCompletedJobs Iterate over the completed jobs. .PP .nf void papplPrinterIterateCompletedJobs ( pappl_printer_t *printer, pappl_job_cb_t cb, void *data, int job_index, int limit ); .fi .PP This function iterates over jobs that are aborted, canceled, or completed. The specified callback "cb" will be called once per job with the data pointer "data". .PP The "job_index" argument specifies the first job in the list to iterate, where \fB1\fR is the first job, etc. The "limit" argument specifies the maximum number of jobs to iterate - use \fB0\fR to iterate an unlimited number of jobs. .SS papplPrinterOpenDevice Open the device associated with a printer. .PP .nf pappl_device_t * papplPrinterOpenDevice ( pappl_printer_t *printer ); .fi .PP This function opens the printer's device. \fBNULL\fR is returned if the device is already in use, for example while a job is being printed. .PP The returned device must be closed using the \fIpapplPrinterCloseDevice\fR function. .SS papplPrinterPause Pause (stop) a printer. .PP .nf void papplPrinterPause ( pappl_printer_t *printer ); .fi .PP This function pauses a printer. If the printer is currently processing (printing) a job, it will be completed before the printer is stopped. .SS papplPrinterResume Resume (start) a printer. .PP .nf void papplPrinterResume ( pappl_printer_t *printer ); .fi .PP This function resumes a printer and starts processing any pending jobs. .SS papplPrinterSetContact Set the "printer-contact" value. .PP .nf void papplPrinterSetContact ( pappl_printer_t *printer, pappl_contact_t *contact ); .fi .PP This function sets the printer's contact information. .SS papplPrinterSetDNSSDName Set the DNS-SD service name. .PP .nf void papplPrinterSetDNSSDName ( pappl_printer_t *printer, const char *value ); .fi .PP This function sets the printer's DNS-SD service name. If \fBNULL\fR, the printer will stop advertising the printer. .SS papplPrinterSetDriverData Set the driver data. .PP .nf bool papplPrinterSetDriverData ( pappl_printer_t *printer, pappl_pr_driver_data_t *data, ipp_t *attrs ); .fi .PP This function validates and sets the driver data, including all defaults and ready (loaded) media. .PP .IN 5 Note: This function regenerates all of the driver-specific capability .IN 5 attributes like "media-col-database", "sides-supported", and so forth. .IN 5 Use the \fIpapplPrinterSetDriverDefaults\fR or .IN 5 \fIpapplPrinterSetReadyMedia\fR\fB functions to efficiently change the > "xxx-default" or "xxx-ready" values, respectively.\fR .SS papplPrinterSetDriverDefaults Set the default print option values. .PP .nf bool papplPrinterSetDriverDefaults ( pappl_printer_t *printer, pappl_pr_driver_data_t *data, int num_vendor, cups_option_t *vendor ); .fi .PP This function validates and sets the printer's default print options. .PP .IN 5 Note: Unlike \fIpapplPrinterSetPrintDriverData\fR, this function only .IN 5 changes the "xxx_default" members of the driver data and is considered .IN 5 lightweight. .SS papplPrinterSetGeoLocation Set the geo-location value as a "geo:" URI. .PP .nf void papplPrinterSetGeoLocation ( pappl_printer_t *printer, const char *value ); .fi .PP This function sets the printer's geographic location as a "geo:" URI. If \fBNULL\fR, the location is cleared to the 'unknown' value. .SS papplPrinterSetImpressionsCompleted Add impressions (sides) to the total count of printed impressions. .PP .nf void papplPrinterSetImpressionsCompleted ( pappl_printer_t *printer, int add ); .fi .PP This function adds to the printer's impressions counter. An impression is one side of an output page. .SS papplPrinterSetLocation Set the location string. .PP .nf void papplPrinterSetLocation ( pappl_printer_t *printer, const char *value ); .fi .PP This function sets the printer's human-readable location string. If \fBNULL\fR, the location is cleared. .SS papplPrinterSetMaxActiveJobs Set the maximum number of active jobs for the printer. .PP .nf void papplPrinterSetMaxActiveJobs ( pappl_printer_t *printer, int max_active_jobs ); .fi .PP This function sets the maximum number of jobs that can be spooled on the printer at one time. .PP .IN 5 Note: This limit does not apply to streaming raster formats such as PWG .IN 5 Raster since they are not spooled. .SS papplPrinterSetMaxCompletedJobs Set the maximum number of completed jobs for the printer. .PP .nf void papplPrinterSetMaxCompletedJobs ( pappl_printer_t *printer, int max_completed_jobs ); .fi .PP This function sets the maximum number of aborted, canceled, or completed jobs that are retained in the job history. .SS papplPrinterSetNextJobID Set the next "job-id" value. .PP .nf void papplPrinterSetNextJobID ( pappl_printer_t *printer, int next_job_id ); .fi .PP This function sets the next unique positive integer identifier that will be used for a job. .PP .IN 5 Note: This function is normally only called once to restore the previous .IN 5 state of the printer. .SS papplPrinterSetOrganization Set the organization name. .PP .nf void papplPrinterSetOrganization ( pappl_printer_t *printer, const char *value ); .fi .PP This function sets the printer's organization name. If \fBNULL\fR the value is cleared. .SS papplPrinterSetOrganizationalUnit Set the organizational unit name. .PP .nf void papplPrinterSetOrganizationalUnit ( pappl_printer_t *printer, const char *value ); .fi .PP This function sets the printer's organizational unit name. If \fBNULL\fR the value is cleared. .SS papplPrinterSetPrintGroup Set the print authorization group, if any. .PP .nf void papplPrinterSetPrintGroup ( pappl_printer_t *printer, const char *value ); .fi .PP This function sets the printer's authorization group. If \fBNULL\fR, the group is cleared. .PP .IN 5 Note: The authorization group is only used if the system is created with a .IN 5 named authorization service. .SS papplPrinterSetReadyMedia Set the ready (loaded) media. .PP .nf bool papplPrinterSetReadyMedia ( pappl_printer_t *printer, int num_ready, pappl_media_col_t *ready ); .fi .PP This function validates and sets the printer's ready (loaded) media. .SS papplPrinterSetReasons Add or remove values from "printer-state-reasons". .PP .nf void papplPrinterSetReasons ( pappl_printer_t *printer, pappl_preason_t add, pappl_preason_t remove ); .fi .PP This function updates the printer state reasons bitfield by clearing any bit values in the "remove" argument and setting any bit values in the "add" argument. .SS papplPrinterSetSupplies Set/update the supplies for a printer. .PP .nf void papplPrinterSetSupplies ( pappl_printer_t *printer, int num_supplies, pappl_supply_t *supplies ); .fi .PP This function updates the supply information for the printer. .SS papplPrinterSetUSB Set the USB vendor and product IDs for a printer. .PP .nf void papplPrinterSetUSB ( pappl_printer_t *printer, unsigned vendor_id, unsigned product_id, pappl_uoptions_t options, const char *storagefile ); .fi .PP This function sets the USB vendor and product IDs for a printer as well as specifying USB gadget options when the printer is registered with the USB device controller. .PP .IN 5 Note: USB gadget functionality is currently only available when running .IN 5 on Linux with compatible hardware such as the Raspberry Pi. .SH STRUCTURES .SS pappl_icon_s Printer PNG icon structure .PP .nf struct pappl_icon_s { const void *data; size_t datalen; char filename[256]; }; .fi .SS pappl_media_col_s Media details structure .PP .nf struct pappl_media_col_s { int bottom_margin; int left_margin; int left_offset; int right_margin; int size_length; char size_name[64]; int size_width; char source[64]; int top_margin; int top_offset; pappl_media_tracking_t tracking; char type[64]; }; .fi .SS pappl_pr_driver_data_s Printer driver data .PP .nf struct pappl_pr_driver_data_s { const char *bin[PAPPL_MAX_BIN]; int bin_default; bool borderless; int bottom_top; pappl_color_mode_t color_default; pappl_color_mode_t color_supported; pappl_content_t content_default; int darkness_configured; int darkness_default; int darkness_supported; pappl_pr_delete_cb_t delete_cb; pappl_duplex_t duplex; void *extension; const char *features[PAPPL_MAX_VENDOR]; pappl_finishings_t finishings; pappl_raster_type_t force_raster_type; const char *format; pappl_dither_t gdither; bool has_supplies; pappl_icon_t icons[3]; pappl_pr_identify_cb_t identify_cb; pappl_identify_actions_t identify_default; pappl_identify_actions_t identify_supported; bool input_face_up; pappl_kind_t kind; int left_offset_supported[2]; int left_right; char make_and_model[128]; const char *media[PAPPL_MAX_MEDIA]; pappl_media_col_t media_default; pappl_media_col_t media_ready[PAPPL_MAX_SOURCE]; pappl_label_mode_t mode_configured; pappl_label_mode_t mode_supported; int num_bin; int num_features; int num_media; int num_resolution; int num_source; int num_type; int num_vendor; ipp_orient_t orient_default; bool output_face_up; pappl_dither_t pdither; int ppm; int ppm_color; pappl_pr_printfile_cb_t printfile_cb; ipp_quality_t quality_default; pappl_raster_type_t raster_types; pappl_pr_rendjob_cb_t rendjob_cb; pappl_pr_rendpage_cb_t rendpage_cb; pappl_pr_rstartjob_cb_t rstartjob_cb; pappl_pr_rstartpage_cb_t rstartpage_cb; pappl_pr_rwriteline_cb_t rwriteline_cb; pappl_scaling_t scaling_default; pappl_sides_t sides_default; pappl_sides_t sides_supported; const char *source[PAPPL_MAX_SOURCE]; int speed_default; int speed_supported[2]; pappl_pr_status_cb_t status_cb; int tear_offset_configured; int tear_offset_supported[2]; pappl_pr_testpage_cb_t testpage_cb; int top_offset_supported[2]; pappl_media_tracking_t tracking_supported; const char *type[PAPPL_MAX_TYPE]; const char *vendor[PAPPL_MAX_VENDOR]; int x_default; int x_resolution[PAPPL_MAX_RESOLUTION]; int y_default; int y_resolution[PAPPL_MAX_RESOLUTION]; }; .fi .SS pappl_pr_options_s Combined print job options .PP .nf struct pappl_pr_options_s { int copies; int darkness_configured; pappl_dither_t dither; pappl_finishings_t finishings; unsigned first_page; cups_page_header2_t header; unsigned last_page; pappl_media_col_t media; unsigned num_pages; int num_vendor; ipp_orient_t orientation_requested; char output_bin[64]; pappl_color_mode_t print_color_mode; pappl_content_t print_content_optimize; int print_darkness; ipp_quality_t print_quality; pappl_scaling_t print_scaling; int print_speed; int printer_resolution[2]; pappl_sides_t sides; cups_option_t *vendor; }; .fi .SS pappl_supply_s Supply data .PP .nf struct pappl_supply_s { pappl_supply_color_t color; char description[256]; bool is_consumed; int level; pappl_supply_type_t type; }; .fi .SH TYPES .SS pappl_color_mode_t Bitfield for IPP "print-color-mode" values .PP .nf typedef unsigned pappl_color_mode_t; .fi .SS pappl_content_t Bitfield for IPP "print-content-optimize" values .PP .nf typedef unsigned pappl_content_t; .fi .SS pappl_default_cb_t papplIterateDefaults callback .PP .nf typedef void (*pappl_default_cb_t)(ipp_attribute_t *attr, void *data); .fi .SS pappl_duplex_t Duplex printing support .PP .nf typedef enum pappl_duplex_e pappl_duplex_t; .fi .SS pappl_finishings_t Bitfield for IPP "finishings" values .PP .nf typedef unsigned pappl_finishings_t; .fi .SS pappl_icon_t Printer PNG icon structure .PP .nf typedef struct pappl_icon_s pappl_icon_t; .fi .SS pappl_identify_actions_t Bitfield for IPP "identify-actions" values .PP .nf typedef unsigned pappl_identify_actions_t; .fi .SS pappl_job_cb_t papplIterateXxxJobs callback function .PP .nf typedef void (*pappl_job_cb_t)(pappl_job_t *job, void *data); .fi .SS pappl_kind_t Bitfield for IPP "printer-kind" values .PP .nf typedef unsigned pappl_kind_t; .fi .SS pappl_label_mode_t Bitfield for IPP "label-mode-xxx" values .PP .nf typedef unsigned short pappl_label_mode_t; .fi .SS pappl_media_col_t Media details structure .PP .nf typedef struct pappl_media_col_s pappl_media_col_t; .fi .SS pappl_media_tracking_t Bitfield for IPP "media-tracking" values .PP .nf typedef unsigned short pappl_media_tracking_t; .fi .SS pappl_pr_delete_cb_t Printer deletion callback .PP .nf typedef void (*pappl_pr_delete_cb_t)(pappl_printer_t *printer, pappl_pr_driver_data_t *data); .fi .SS pappl_pr_identify_cb_t Identify-Printer callback .PP .nf typedef void (*pappl_pr_identify_cb_t)(pappl_printer_t *printer, pappl_identify_actions_t actions, const char *message); .fi .SS pappl_pr_printfile_cb_t Print a "raw" job callback .PP .nf typedef bool (*pappl_pr_printfile_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device); .fi .SS pappl_pr_rendjob_cb_t End a raster job callback .PP .nf typedef bool (*pappl_pr_rendjob_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device); .fi .SS pappl_pr_rendpage_cb_t End a raster page callback .PP .nf typedef bool (*pappl_pr_rendpage_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device, unsigned page); .fi .SS pappl_pr_rstartjob_cb_t Start a raster job callback .PP .nf typedef bool (*pappl_pr_rstartjob_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device); .fi .SS pappl_pr_rstartpage_cb_t Start a raster page callback .PP .nf typedef bool (*pappl_pr_rstartpage_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device, unsigned page); .fi .SS pappl_pr_rwriteline_cb_t Write a line of raster graphics callback .PP .nf 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); .fi .SS pappl_pr_status_cb_t Update printer status callback .PP .nf typedef bool (*pappl_pr_status_cb_t)(pappl_printer_t *printer); .fi .SS pappl_pr_testpage_cb_t Print a test page callback .PP .nf typedef const char * (*pappl_pr_testpage_cb_t)(pappl_printer_t *printer, char *buffer, size_t bufsize); .fi .SS pappl_raster_type_t Bitfield for IPP "pwg-raster-document-type-supported" values .PP .nf typedef unsigned pappl_raster_type_t; .fi .SS pappl_scaling_t Bitfield for IPP "print-scaling" values .PP .nf typedef unsigned pappl_scaling_t; .fi .SS pappl_sides_t Bitfield for IPP "sides" values .PP .nf typedef unsigned pappl_sides_t; .fi .SS pappl_supply_color_t "printer-supply" color values .PP .nf typedef enum pappl_supply_color_e pappl_supply_color_t; .fi .SS pappl_supply_t Supply data .PP .nf typedef struct pappl_supply_s pappl_supply_t; .fi .SS pappl_supply_type_t IPP "printer-supply" type values .PP .nf typedef enum pappl_supply_type_e pappl_supply_type_t; .fi .SS pappl_uoptions_t USB gadget options bitfield .PP .nf typedef unsigned pappl_uoptions_t; .fi .SH SEE ALSO .BR pappl (1), .BR pappl-client (3), .BR pappl-device (3), .BR pappl-job (3), .BR pappl-log (3), .BR pappl-mainline (3), .BR pappl-makeresheader (1), .BR pappl-printer (3), .BR pappl-resource (3), .BR pappl-system (3), https://www.msweet.org/pappl .SH COPYRIGHT Copyright \[co] 2019-2020 by Michael R Sweet. .PP .B PAPPL is licensed under the Apache License Version 2.0 with an (optional) exception to allow linking against GPL2/LGPL2 software (like older versions of CUPS), so it can be used .I freely in any project you'd like. See the files "LICENSE" and "NOTICE" in the source distribution for more information.