Provided by: libpappl-dev_1.0.3-2_amd64 bug

NAME

       pappl-printer - pappl printer functions

LIBRARY

       Printer Application Framework (libpappl, "pkg-config --cflags --libs pappl")

SYNOPSIS

       #include <pappl/pappl.h>

       typedef struct _pappl_printer_s pappl_printer_t;

       void
       papplPrinterCancelAllJobs(pappl_printer_t *printer);

       void
       papplPrinterCloseDevice(pappl_printer_t *printer);

       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);

       void
       papplPrinterDelete(pappl_printer_t *printer);

       pappl_job_t    *
       papplPrinterFindJob(pappl_printer_t *printer, int job_id);

       pappl_contact_t     *
       papplPrinterGetContact(pappl_printer_t *printer, pappl_contact_t *contact);

       const char     *
       papplPrinterGetDeviceID(pappl_printer_t *printer);

       const char     *
       papplPrinterGetDeviceURI(pappl_printer_t *printer);

       char      *
       papplPrinterGetDNSSDName(pappl_printer_t *printer, char *buffer, size_t bufsize);

       ipp_t          *
       papplPrinterGetDriverAttributes(pappl_printer_t *printer);

       pappl_driver_data_t *
       papplPrinterGetDriverData(pappl_printer_t *printer, pappl_driver_data_t *data);

       const char     *
       papplPrinterGetDriverName(pappl_printer_t *printer);

       char      *
       papplPrinterGetGeoLocation(pappl_printer_t *printer, char *buffer, size_t bufsize);

       int
       papplPrinterGetID(pappl_printer_t *printer);

       int
       papplPrinterGetImpressionsCompleted(pappl_printer_t *printer);

       char      *
       papplPrinterGetLocation(pappl_printer_t *printer, char *buffer, size_t bufsize);

       int
       papplPrinterGetMaxActiveJobs(pappl_printer_t *printer);

       int
       papplPrinterGetMaxCompletedJobs(pappl_printer_t *printer);

       const char     *
       papplPrinterGetName(pappl_printer_t *printer);

       int
       papplPrinterGetNextJobID(pappl_printer_t *printer);

       int
       papplPrinterGetNumberOfActiveJobs(pappl_printer_t *printer);

       int
       papplPrinterGetNumberOfCompletedJobs(pappl_printer_t *printer);

       int
       papplPrinterGetNumberOfJobs(pappl_printer_t *printer);

       char      *
       papplPrinterGetOrganization(pappl_printer_t *printer, char *buffer, size_t bufsize);

       char      *
       papplPrinterGetOrganizationalUnit(pappl_printer_t *printer, char *buffer, size_t bufsize);

       char      *
       papplPrinterGetPrintGroup(pappl_printer_t *printer, char *buffer, size_t bufsize);

       pappl_preason_t
       papplPrinterGetReasons(pappl_printer_t *printer);

       ipp_pstate_t
       papplPrinterGetState(pappl_printer_t *printer);

       int
       papplPrinterGetSupplies(pappl_printer_t   *printer,   int   max_supplies,   pappl_supply_t
       *supplies);

       pappl_system_t *
       papplPrinterGetSystem(pappl_printer_t *printer);

       void
       papplPrinterIterateActiveJobs(pappl_printer_t *printer, pappl_job_cb_t cb, void *data, int
       first_index, int limit);

       void
       papplPrinterIterateAllJobs(pappl_printer_t *printer, pappl_job_cb_t cb,  void  *data,  int
       first_index, int limit);

       void
       papplPrinterIterateCompletedJobs(pappl_printer_t  *printer, pappl_job_cb_t cb, void *data,
       int first_index, int limit);

       pappl_device_t *
       papplPrinterOpenDevice(pappl_printer_t *printer);

       void
       papplPrinterPause(pappl_printer_t *printer);

       void
       papplPrinterResume(pappl_printer_t *printer);

       void
       papplPrinterSetContact(pappl_printer_t *printer, pappl_contact_t *contact);

       void
       papplPrinterSetDNSSDName(pappl_printer_t *printer, const char *value);

       void
       papplPrinterSetDriverData(pappl_printer_t  *printer,  pappl_driver_data_t   *data,   ipp_t
       *attrs);

       void
       papplPrinterSetDriverDefaults(pappl_printer_t *printer, pappl_driver_data_t *data);

       void
       papplPrinterSetGeoLocation(pappl_printer_t *printer, const char *value);

       void
       papplPrinterSetImpressionsCompleted(pappl_printer_t *printer, int add);

       void
       papplPrinterSetLocation(pappl_printer_t *printer, const char *value);

       void
       papplPrinterSetMaxActiveJobs(pappl_printer_t *printer, int max_active_jobs);

       void
       papplPrinterSetMaxCompletedJobs(pappl_printer_t *printer, int max_completed_jobs);

       void
       papplPrinterSetNextJobID(pappl_printer_t *printer, int next_job_id);

       void
       papplPrinterSetOrganization(pappl_printer_t *printer, const char *value);

       void
       papplPrinterSetOrganizationalUnit(pappl_printer_t *printer, const char *value);

       void
       papplPrinterSetPrintGroup(pappl_printer_t *printer, const char *value);

       void
       papplPrinterSetReadyMedia(pappl_printer_t   *printer,   int  num_ready,  pappl_media_col_t
       *ready);

       void
       papplPrinterSetReasons(pappl_printer_t  *printer,  pappl_preason_t  add,   pappl_preason_t
       remove);

       void
       papplPrinterSetSupplies(pappl_printer_t   *printer,   int   num_supplies,   pappl_supply_t
       *supplies);

       void
       papplPrinterSetUSB(pappl_printer_t  *printer,  unsigned  vendor_id,  unsigned  product_id,
       pappl_uoptions_t options);

DESCRIPTION

       The  PAPPL  printer  functions provide access to the printer object.  Printers are created
       and deleted by the printer application while the life cycle of the pappl_printer_t objects
       are managed automatically by the system object for the printer application.

       The  papplPrinterCreate  function  creates  a  new  printer  while  the papplPrinterDelete
       function deletes a printer.

       The papplPrinterPause function stops  a  printer  while  the  papplPrinterResume  function
       starts a printer.

       The  papplPrinterGet  functions get the current values associated with a printer while the
       papplPrinterSet functions set the current values associated with a printer.

       The  papplPrinterCancelAddJobs,  papplPrinterFindJob,   papplPrinterGetNumberOfActiveJobs,
       papplPrinterGetNumberOfCompletedJobs,                         papplPrinterGetNumberOfJobs,
       papplPrinterIterateActiveJobs,               papplPrinterIterateAllJobs,               and
       papplPrinterIterateCompletedJobs functions provide access to the jobs queued on a printer.

       The  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
       papplPrinterCloseDevice function so that the printer can resume job processing.

ENUMERATIONS

   pappl_color_mode_e
       IPP "print-color-mode" bit values

       PAPPL_COLOR_MODE_AUTO
            ´auto' - Automatic color/monochrome print mode

       PAPPL_COLOR_MODE_AUTO_MONOCHROME
            ´auto-monochrome' - Automatic monochrome/process monochrome print mode

       PAPPL_COLOR_MODE_BI_LEVEL
            ´bi-level' - B&W (threshold) print mode

       PAPPL_COLOR_MODE_COLOR
            ´color' - Full color print mode

       PAPPL_COLOR_MODE_MONOCHROME
            ´monochrome' - Grayscale print mode using 1 color

       PAPPL_COLOR_MODE_PROCESS_MONOCHROME
            ´process-monochrome' - Grayscale print mode using multiple colors

   pappl_content_e
       IPP "print-content-optimize" bit values

       PAPPL_CONTENT_AUTO
            ´auto': Automatically determine content

       PAPPL_CONTENT_GRAPHIC
            ´graphic': Optimize for vector graphics

       PAPPL_CONTENT_PHOTO
            ´photo': Optimize for photos/continuous tone images

       PAPPL_CONTENT_TEXT
            ´text': Optimize for text

       PAPPL_CONTENT_TEXT_AND_GRAPHIC
            ´text-and-graphic': Optimize for text and vector graphics

   pappl_duplex_e
       Duplex printing support

       PAPPL_DUPLEX_FLIPPED
            Duplex with flipped back sides

       PAPPL_DUPLEX_MANUAL_TUMBLE
            Duplex with back side rotated 180 degrees for short-edge duplex

       PAPPL_DUPLEX_NONE
            No duplex printing support

       PAPPL_DUPLEX_NORMAL
            Duplex with normal back sides

       PAPPL_DUPLEX_ROTATED
            Duplex with back side rotated 180 degrees for long-edge duplex

   pappl_finishings_e
       IPP "finishings" bit values

       PAPPL_FINISHINGS_NONE
            ´none'

       PAPPL_FINISHINGS_PUNCH
            ´punch'

       PAPPL_FINISHINGS_STAPLE
            ´staple'

       PAPPL_FINISHINGS_TRIM
            ´trim'

   pappl_identify_actions_e
       IPP "identify-actions" bit values

       PAPPL_IDENTIFY_ACTIONS_DISPLAY
            ´display': Display a message

       PAPPL_IDENTIFY_ACTIONS_FLASH
            ´flash': Flash the display or a light

       PAPPL_IDENTIFY_ACTIONS_NONE
            No actions

       PAPPL_IDENTIFY_ACTIONS_SOUND
            ´sound': Make a sound

       PAPPL_IDENTIFY_ACTIONS_SPEAK
            ´speak': Speak a message

   pappl_kind_e
       IPP "printer-kind" bit values

       PAPPL_KIND_DISC
            ´disc'

       PAPPL_KIND_DOCUMENT
            ´document'

       PAPPL_KIND_ENVELOPE
            ´envelope'

       PAPPL_KIND_LABEL
            ´label'

       PAPPL_KIND_LARGE_FORMAT
            ´large-format'

       PAPPL_KIND_PHOTO
            ´photo'

       PAPPL_KIND_POSTCARD
            ´postcard'

       PAPPL_KIND_RECEIPT
            ´receipt'

       PAPPL_KIND_ROLL
            ´roll'

   pappl_label_mode_e
       IPP "label-mode-xxx" bit values

       PAPPL_LABEL_MODE_APPLICATOR
            ´applicator'

       PAPPL_LABEL_MODE_CUTTER
            ´cutter'

       PAPPL_LABEL_MODE_CUTTER_DELAYED
            ´cutter-delayed'

       PAPPL_LABEL_MODE_KIOSK
            ´kiosk'

       PAPPL_LABEL_MODE_PEEL_OFF
            ´peel-off'

       PAPPL_LABEL_MODE_PEEL_OFF_PREPEEL
            ´peel-off-prepeel'

       PAPPL_LABEL_MODE_REWIND
            ´rewind'

       PAPPL_LABEL_MODE_RFID
            ´rfid'

       PAPPL_LABEL_MODE_TEAR_OFF
            ´tear-off'

   pappl_media_tracking_e
       IPP "media-tracking" bit values

       PAPPL_MEDIA_TRACKING_CONTINUOUS
            ´continuous'

       PAPPL_MEDIA_TRACKING_GAP
            ´gap'

       PAPPL_MEDIA_TRACKING_MARK
            ´mark'

       PAPPL_MEDIA_TRACKING_WEB
            ´web'

   pappl_preason_e
       IPP "printer-state-reasons" bit values

       PAPPL_PREASON_COVER_OPEN
            ´cover-open'

       PAPPL_PREASON_DEVICE_STATUS
            Supported papplDeviceGetStatus bits

       PAPPL_PREASON_INPUT_TRAY_MISSING
            ´input-tray-missing'

       PAPPL_PREASON_MARKER_SUPPLY_EMPTY
            ´marker-supply-empty'

       PAPPL_PREASON_MARKER_SUPPLY_LOW
            ´marker-supply-low'

       PAPPL_PREASON_MARKER_WASTE_ALMOST_FULL
            ´marker-waste-almost-full'

       PAPPL_PREASON_MARKER_WASTE_FULL
            ´marker-waste-full'

       PAPPL_PREASON_MEDIA_EMPTY
            ´media-empty'

       PAPPL_PREASON_MEDIA_JAM
            ´media-jam'

       PAPPL_PREASON_MEDIA_LOW
            ´media-low'

       PAPPL_PREASON_MEDIA_NEEDED
            ´media-needed'

       PAPPL_PREASON_NONE
            ´none'

       PAPPL_PREASON_OFFLINE
            ´offline'

       PAPPL_PREASON_OTHER
            ´other'

       PAPPL_PREASON_SPOOL_AREA_FULL
            ´spool-area-full'

       PAPPL_PREASON_TONER_EMPTY
            ´toner-empty'

       PAPPL_PREASON_TONER_LOW
            ´toner-low'

   pappl_raster_type_e
       IPP "pwg-raster-document-type-supported" bit values

       PAPPL_PWG_RASTER_TYPE_ADOBE_RGB_16
            16-bit per component AdobeRGB

       PAPPL_PWG_RASTER_TYPE_ADOBE_RGB_8
            8-bit per component AdobeRGB

       PAPPL_PWG_RASTER_TYPE_BLACK_1
            1-bit (device) black

       PAPPL_PWG_RASTER_TYPE_BLACK_16
            16-bit (device) black

       PAPPL_PWG_RASTER_TYPE_BLACK_8
            8-bit (device) black

       PAPPL_PWG_RASTER_TYPE_CMYK_16
            16-bit per component (device) CMYK

       PAPPL_PWG_RASTER_TYPE_CMYK_8
            8-bit per component (device) CMYK

       PAPPL_PWG_RASTER_TYPE_NONE
            Do not force a particular raster type

       PAPPL_PWG_RASTER_TYPE_RGB_16
            16-bit per component (device) RGB)

       PAPPL_PWG_RASTER_TYPE_RGB_8
            8-bit per component (device) RGB

       PAPPL_PWG_RASTER_TYPE_SGRAY_16
            16-bit grayscale with 2.2 gamma

       PAPPL_PWG_RASTER_TYPE_SGRAY_8
            8-bit grayscale with 2.2 gamma

       PAPPL_PWG_RASTER_TYPE_SRGB_16
            16-bit per component sRGB

       PAPPL_PWG_RASTER_TYPE_SRGB_8
            8-bit per component sRGB

   pappl_scaling_e
       IPP "print-scaling" bit values

       PAPPL_SCALING_AUTO
            ´auto':  Scale  to  fit  (non-borderless)  or  fill (borderless) if larger, otherwise
            center

       PAPPL_SCALING_AUTO_FIT
            ´auto-fit': Scale to fit if larger, otherwise center

       PAPPL_SCALING_FILL
            ´fill': Scale to fill the media

       PAPPL_SCALING_FIT
            ´fit': Scale to fit within margins

       PAPPL_SCALING_NONE
            ´none': No scaling (center/crop)

   pappl_sides_e
       IPP "sides" bit values

       PAPPL_SIDES_ONE_SIDED
            ´one-sided'

       PAPPL_SIDES_TWO_SIDED_LONG_EDGE
            ´two-sided-long-edge'

       PAPPL_SIDES_TWO_SIDED_SHORT_EDGE
            ´two-sided-short-edge'

   pappl_supply_color_e
       "printer-supply" color values

       PAPPL_SUPPLY_COLOR_BLACK
            Black ink/toner (photo or matte)

       PAPPL_SUPPLY_COLOR_CYAN
            Cyan ink/toner

       PAPPL_SUPPLY_COLOR_GRAY
            Gray ink (sometimes marketed as light gray)

       PAPPL_SUPPLY_COLOR_GREEN
            Green ink

       PAPPL_SUPPLY_COLOR_LIGHT_CYAN
            Light cyan ink

       PAPPL_SUPPLY_COLOR_LIGHT_GRAY
            Light gray ink (sometimes marketed as light light gray)

       PAPPL_SUPPLY_COLOR_LIGHT_MAGENTA
            Light magenta ink

       PAPPL_SUPPLY_COLOR_MAGENTA
            Magenta ink/toner

       PAPPL_SUPPLY_COLOR_NO_COLOR
            No color (waste tank, etc.)

       PAPPL_SUPPLY_COLOR_ORANGE
            Orange ink

       PAPPL_SUPPLY_COLOR_VIOLET
            Violet ink

       PAPPL_SUPPLY_COLOR_YELLOW
            Yellow ink/toner

   pappl_supply_type_e
       IPP "printer-supply" type values

       PAPPL_SUPPLY_TYPE_BANDING_SUPPLY
            Banding finisher supplies

       PAPPL_SUPPLY_TYPE_BINDING_SUPPLY
            Binding finisher supplies

       PAPPL_SUPPLY_TYPE_CLEANER_UNIT
            Cleaning unit

       PAPPL_SUPPLY_TYPE_CORONA_WIRE
            Corona wire (laser printers)

       PAPPL_SUPPLY_TYPE_COVERS
            Cover finisher supplies

       PAPPL_SUPPLY_TYPE_DEVELOPER
            Developer supply

       PAPPL_SUPPLY_TYPE_FUSER
            Fuser (laser printers)

       PAPPL_SUPPLY_TYPE_FUSER_CLEANING_PAD
            Fuser cleaning pad (laser printers)

       PAPPL_SUPPLY_TYPE_FUSER_OIL
            Fuser oil supply (laser printers)

       PAPPL_SUPPLY_TYPE_FUSER_OILER
            Fuser oiler (laser printers)

       PAPPL_SUPPLY_TYPE_FUSER_OIL_WICK
            Fuser oil wick (laser printers)

       PAPPL_SUPPLY_TYPE_INK
            Ink supply

       PAPPL_SUPPLY_TYPE_INK_CARTRIDGE
            Ink cartridge

       PAPPL_SUPPLY_TYPE_INK_RIBBON
            Ink ribbon supply

       PAPPL_SUPPLY_TYPE_INSERTS
            Insert finisher supplies

       PAPPL_SUPPLY_TYPE_OPC
            Optical photoconductor (laser printers)

       PAPPL_SUPPLY_TYPE_PAPER_WRAP
            Wrap finisher supplies

       PAPPL_SUPPLY_TYPE_RIBBON_WAX
            Wax ribbon supply

       PAPPL_SUPPLY_TYPE_SOLID_WAX
            Solid wax supply

       PAPPL_SUPPLY_TYPE_STAPLES
            Staple finisher supplies

       PAPPL_SUPPLY_TYPE_STITCHING_WIRE
            Staple/stitch finisher supplies

       PAPPL_SUPPLY_TYPE_TONER
            Toner supply

       PAPPL_SUPPLY_TYPE_TONER_CARTRIDGE
            Toner cartridge

       PAPPL_SUPPLY_TYPE_TRANSFER_UNIT
            Transfer unit (laser printers)

       PAPPL_SUPPLY_TYPE_WASTE_INK
            Waste ink

       PAPPL_SUPPLY_TYPE_WASTE_TONER
            Waste toner

       PAPPL_SUPPLY_TYPE_WASTE_WATER
            Waste water

       PAPPL_SUPPLY_TYPE_WASTE_WAX
            Waste wax

       PAPPL_SUPPLY_TYPE_WATER
            Water supply

   pappl_uoptions_e
       USB gadget options

       PAPPL_UOPTIONS_ETHERNET
            Include USB ethernet gadget

       PAPPL_UOPTIONS_NONE
            No options (just USB printer)

       PAPPL_UOPTIONS_SERIAL
            Include USB serial gadget

       PAPPL_UOPTIONS_STORAGE
            Include USB mass storage gadget

       PAPPL_UOPTIONS_STORAGE_READONLY
            USB mass storage gadget is read-only

       PAPPL_UOPTIONS_STORAGE_REMOVABLE
            USB mass storage gadget is removable

FUNCTIONS

   papplPrinterCancelAllJobs
       Cancel all jobs on the printer.

       void papplPrinterCancelAllJobs (
           pappl_printer_t *printer
       );

       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.

   papplPrinterCloseDevice
       Close the device associated with the printer.

       void papplPrinterCloseDevice (
           pappl_printer_t *printer
       );

       This function closes the device for a printer.   The  device  must  have  been  previously
       opened using the papplPrinterOpenDevice function.

   papplPrinterCreate
       Create a new printer.

       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
       );

       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
       PAPPL_SERVICE_TYPE_PRINT.

       The  "printer_id"  argument  specifies a positive integer identifier that is unique to the
       system.  If you specify a value of 0 a new identifier will be assigned.

       The "driver_name" argument specifies a named driver for the  printer,  from  the  list  of
       drivers registered with the papplSystemSetPrinterDrivers function.

       The  "device_id" and "device_uri" arguments specify the IEEE-1284 device ID and device URI
       strings for the printer.

       On error, this function sets the errno variable to one of the following values:

       •    EEXIST: A printer with the specified name already exists.

       •    EINVAL: Bad values for the arguments were specified.

       •    EIO: The driver callback failed.

       •    ENOENT: No driver callback has been set.

       •    ENOMEM: Ran out of memory.</li> </ul>

   papplPrinterDelete
       Delete a printer.

       void papplPrinterDelete (
           pappl_printer_t *printer
       );

       This function deletes a printer from a system, freeing all memory and canceling  all  jobs
       as needed.

   papplPrinterGetContact
       Get the "printer-contact" value.

       pappl_contact_t * papplPrinterGetContact (
           pappl_printer_t *printer,
           pappl_contact_t *contact
       );

       This  function  copies the current printer contact information to the buffer pointed to by
       the "contact" argument.

   papplPrinterGetDNSSDName
       Get the current DNS-SD service name.

       char * papplPrinterGetDNSSDName (
           pappl_printer_t *printer,
           char *buffer,
           size_t bufsize
       );

       This function copies the current DNS-SD service name to  the  buffer  pointed  to  by  the
       "buffer" argument.

   papplPrinterGetDeviceID
       Get the IEEE-1284 device ID of the printer.

       const char * papplPrinterGetDeviceID (
           pappl_printer_t *printer
       );

       This function returns the IEEE-1284 device ID of the printer.

   papplPrinterGetDeviceURI
       Get the URI of the device associated with the printer.

       const char * papplPrinterGetDeviceURI (
           pappl_printer_t *printer
       );

       This function returns the device URI for the printer.

   papplPrinterGetDriverAttributes
       Get a copy of the current driver attributes.

       ipp_t * papplPrinterGetDriverAttributes (
           pappl_printer_t *printer
       );

       This  function returns a copy the current driver attributes. Use the ippDelete function to
       free the memory used for the attributes when you are done.

   papplPrinterGetDriverData
       Get the current print driver data.

       pappl_pr_driver_data_t * papplPrinterGetDriverData (
           pappl_printer_t *printer,
           pappl_pr_driver_data_t *data
       );

       This function copies the current print driver data, defaults,  and  ready  (loaded)  media
       information into the specified buffer.

   papplPrinterGetDriverName
       Get the driver name for a printer.

       const char * papplPrinterGetDriverName (
           pappl_printer_t *printer
       );

       This function returns the driver name for the printer.

   papplPrinterGetGeoLocation
       Get the current geo-location as a "geo:" URI.

       char * papplPrinterGetGeoLocation (
           pappl_printer_t *printer,
           char *buffer,
           size_t bufsize
       );

       This  function  copies the currently configured geographic location as a "geo:" URI to the
       buffer pointed to by the "buffer" argument.

   papplPrinterGetID
       Get the printer ID.

       int  papplPrinterGetID (
           pappl_printer_t *printer
       );

       This function returns the printer's unique positive integer identifier.

   papplPrinterGetImpressionsCompleted
       Get the number of impressions (sides) that have been printed.

       int  papplPrinterGetImpressionsCompleted (
           pappl_printer_t *printer
       );

       This function returns the number of impressions that have been printed.  An impression  is
       one side of an output page.

   papplPrinterGetLocation
       Get the location string.

       char * papplPrinterGetLocation (
           pappl_printer_t *printer,
           char *buffer,
           size_t bufsize
       );

       This function copies the printer's human-readable location to the buffer pointed to by the
       "buffer" argument.

   papplPrinterGetMaxActiveJobs
       Get the maximum number of active (queued) jobs allowed by the printer.

       int  papplPrinterGetMaxActiveJobs (
           pappl_printer_t *printer
       );

       This function returns the maximum number of active jobs  that  the  printer  supports,  as
       configured by the papplPrinterSetMaxActiveJobs function.

   papplPrinterGetMaxCompletedJobs
       Get the maximum number of jobs retained for history by the printer.

       int  papplPrinterGetMaxCompletedJobs (
           pappl_printer_t *printer
       );

       This  function  returns the maximum number of jobs that are retained in the job history as
       configured by the papplPrinterSetMaxCompletedJobs function.

   papplPrinterGetName
       Get the printer name.

       const char * papplPrinterGetName (
           pappl_printer_t *printer
       );

       This function returns the printer's human-readable name.

   papplPrinterGetNextJobID
       Get the next job ID.

       int  papplPrinterGetNextJobID (
           pappl_printer_t *printer
       );

       This function returns the positive integer identifier that will be used for the  next  job
       that is created.

   papplPrinterGetNumberOfActiveJobs
       Get the number of active print jobs.

       int  papplPrinterGetNumberOfActiveJobs (
           pappl_printer_t *printer
       );

       This  function  returns the number of print jobs that are either printing or waiting to be
       printed.

   papplPrinterGetNumberOfCompletedJobs
       Get the number of completed print jobs.

       int  papplPrinterGetNumberOfCompletedJobs (
           pappl_printer_t *printer
       );

       This function returns the number of print  jobs  that  have  been  aborted,  canceled,  or
       completed.

   papplPrinterGetNumberOfJobs
       Get the total number of print jobs.

       int  papplPrinterGetNumberOfJobs (
           pappl_printer_t *printer
       );

       This  function  returns the number of print jobs that are printing, waiting to be printed,
       have been aborted, have been canceled, or have completed.

   papplPrinterGetOrganization
       Get the organization name.

       char * papplPrinterGetOrganization (
           pappl_printer_t *printer,
           char *buffer,
           size_t bufsize
       );

       This function copies the printer's organization name to  the  buffer  pointed  to  by  the
       "buffer" argument.

   papplPrinterGetOrganizationalUnit
       Get the organizational unit name.

       char * papplPrinterGetOrganizationalUnit (
           pappl_printer_t *printer,
           char *buffer,
           size_t bufsize
       );

       This  function  copies  the printer's organizational unit name to the buffer pointed to by
       the "buffer" argument.

   papplPrinterGetPath
       Get the URL path for a printer web page.

       char * papplPrinterGetPath (
           pappl_printer_t *printer,
           const char *subpath,
           char *buffer,
           size_t bufsize
       );

       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.

   papplPrinterGetPrintGroup
       Get the print authorization group, if any.

       char * papplPrinterGetPrintGroup (
           pappl_printer_t *printer,
           char *buffer,
           size_t bufsize
       );

       This  function  copies  the printer's authorization group name to the buffer pointed to by
       the "buffer" argument.

   papplPrinterGetReasons
       Get the current "printer-state-reasons" bit values.

       pappl_preason_t  papplPrinterGetReasons (
           pappl_printer_t *printer
       );

       This function returns the current printer state reasons bitfield, which can be updated  by
       the printer driver and/or by the papplPrinterSetReasons function.

   papplPrinterGetState
       Get the current "printer-state" value.

       ipp_pstate_t  papplPrinterGetState (
           pappl_printer_t *printer
       );

       This function returns the current printer state as an enumeration:

       •    IPP_PSTATE_IDLE: The printer is idle and has no jobs to process.

       •    IPP_PSTATE_PROCESSING: The printer is processing a job and/or producing output.

       •    IPP_PSTATE_STOPPED: The printer is stopped for maintenance.</li> </ul>

   papplPrinterGetSupplies
       Get the current "printer-supplies" values.

       int  papplPrinterGetSupplies (
           pappl_printer_t *printer,
           int max_supplies,
           pappl_supply_t *supplies
       );

       This  function  copies  the  current  printer  supply  values to the specified array.  The
       "max_supplies" and "supplies" arguments can be 0 and NULL to query the number of  supplies
       used.

       The  return  value is the actual number of supplies used by the printer, regardless of the
       size of the array.

   papplPrinterGetSystem
       Get the system associated with the printer.

       pappl_system_t * papplPrinterGetSystem (
           pappl_printer_t *printer
       );

       This function returns a pointer to the system object that contains the printer.

   papplPrinterIterateActiveJobs
       Iterate over the active jobs.

       void papplPrinterIterateActiveJobs (
           pappl_printer_t *printer,
           pappl_job_cb_t cb,
           void *data,
           int job_index,
           int limit
       );

       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".

       The  "job_index"  argument  specifies the first job in the list to iterate, where 1 is the
       first job, etc.  The "limit" argument specifies the maximum number of jobs  to  iterate  -
       use 0 to iterate an unlimited number of jobs.

   papplPrinterIterateAllJobs
       Iterate over all the jobs.

       void papplPrinterIterateAllJobs (
           pappl_printer_t *printer,
           pappl_job_cb_t cb,
           void *data,
           int job_index,
           int limit
       );

       This function iterates over all jobs.  The specified callback "cb" will be called once per
       job with the data pointer "data".

       The "job_index" argument specifies the first job in the list to iterate, where  1  is  the
       first  job,  etc.   The "limit" argument specifies the maximum number of jobs to iterate -
       use 0 to iterate an unlimited number of jobs.

   papplPrinterIterateCompletedJobs
       Iterate over the completed jobs.

       void papplPrinterIterateCompletedJobs (
           pappl_printer_t *printer,
           pappl_job_cb_t cb,
           void *data,
           int job_index,
           int limit
       );

       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".

       The  "job_index"  argument  specifies the first job in the list to iterate, where 1 is the
       first job, etc.  The "limit" argument specifies the maximum number of jobs  to  iterate  -
       use 0 to iterate an unlimited number of jobs.

   papplPrinterOpenDevice
       Open the device associated with a printer.

       pappl_device_t * papplPrinterOpenDevice (
           pappl_printer_t *printer
       );

       This  function  opens  the printer's device.  NULL is returned if the device is already in
       use, for example while a job is being printed.

       The returned device must be closed using the papplPrinterCloseDevice function.

   papplPrinterPause
       Pause (stop) a printer.

       void papplPrinterPause (
           pappl_printer_t *printer
       );

       This function pauses a printer.  If the printer is currently processing (printing) a  job,
       it will be completed before the printer is stopped.

   papplPrinterResume
       Resume (start) a printer.

       void papplPrinterResume (
           pappl_printer_t *printer
       );

       This function resumes a printer and starts processing any pending jobs.

   papplPrinterSetContact
       Set the "printer-contact" value.

       void papplPrinterSetContact (
           pappl_printer_t *printer,
           pappl_contact_t *contact
       );

       This function sets the printer's contact information.

   papplPrinterSetDNSSDName
       Set the DNS-SD service name.

       void papplPrinterSetDNSSDName (
           pappl_printer_t *printer,
           const char *value
       );

       This  function  sets  the  printer's  DNS-SD service name.  If NULL, the printer will stop
       advertising the printer.

   papplPrinterSetDriverData
       Set the driver data.

       bool  papplPrinterSetDriverData (
           pappl_printer_t *printer,
           pappl_pr_driver_data_t *data,
           ipp_t *attrs
       );

       This function validates and sets  the  driver  data,  including  all  defaults  and  ready
       (loaded) media.

       5      Note: This function regenerates all of the driver-specific capability

       5      attributes like "media-col-database", "sides-supported", and so forth.

       5      Use the papplPrinterSetDriverDefaults or

       5      papplPrinterSetReadyMedia functions to efficiently change the

       5      "xxx-default" or "xxx-ready" values, respectively.

   papplPrinterSetDriverDefaults
       Set the default print option values.

       bool  papplPrinterSetDriverDefaults (
           pappl_printer_t *printer,
           pappl_pr_driver_data_t *data,
           int num_vendor,
           cups_option_t *vendor
       );

       This function validates and sets the printer's default print options.

       5      Note: Unlike papplPrinterSetPrintDriverData, this function only

       5      changes the "xxx_default" members of the driver data and is considered

       5      lightweight.

   papplPrinterSetGeoLocation
       Set the geo-location value as a "geo:" URI.

       void papplPrinterSetGeoLocation (
           pappl_printer_t *printer,
           const char *value
       );

       This  function  sets  the  printer's  geographic  location  as a "geo:" URI.  If NULL, the
       location is cleared to the 'unknown' value.

   papplPrinterSetImpressionsCompleted
       Add impressions (sides) to the total count of printed impressions.

       void papplPrinterSetImpressionsCompleted (
           pappl_printer_t *printer,
           int add
       );

       This function adds to the printer's impressions counter.  An impression is one side of  an
       output page.

   papplPrinterSetLocation
       Set the location string.

       void papplPrinterSetLocation (
           pappl_printer_t *printer,
           const char *value
       );

       This function sets the printer's human-readable location string.  If NULL, the location is
       cleared.

   papplPrinterSetMaxActiveJobs
       Set the maximum number of active jobs for the printer.

       void papplPrinterSetMaxActiveJobs (
           pappl_printer_t *printer,
           int max_active_jobs
       );

       This function sets the maximum number of jobs that can be spooled on the  printer  at  one
       time.

       5      Note: This limit does not apply to streaming raster formats such as PWG

       5      Raster since they are not spooled.

   papplPrinterSetMaxCompletedJobs
       Set the maximum number of completed jobs for the printer.

       void papplPrinterSetMaxCompletedJobs (
           pappl_printer_t *printer,
           int max_completed_jobs
       );

       This  function  sets  the  maximum number of aborted, canceled, or completed jobs that are
       retained in the job history.

   papplPrinterSetNextJobID
       Set the next "job-id" value.

       void papplPrinterSetNextJobID (
           pappl_printer_t *printer,
           int next_job_id
       );

       This function sets the next unique positive integer identifier that will  be  used  for  a
       job.

       5      Note: This function is normally only called once to restore the previous

       5      state of the printer.

   papplPrinterSetOrganization
       Set the organization name.

       void papplPrinterSetOrganization (
           pappl_printer_t *printer,
           const char *value
       );

       This function sets the printer's organization name.  If NULL the value is cleared.

   papplPrinterSetOrganizationalUnit
       Set the organizational unit name.

       void papplPrinterSetOrganizationalUnit (
           pappl_printer_t *printer,
           const char *value
       );

       This function sets the printer's organizational unit name.  If NULL the value is cleared.

   papplPrinterSetPrintGroup
       Set the print authorization group, if any.

       void papplPrinterSetPrintGroup (
           pappl_printer_t *printer,
           const char *value
       );

       This function sets the printer's authorization group.  If NULL, the group is cleared.

       5      Note: The authorization group is only used if the system is created with a

       5      named authorization service.

   papplPrinterSetReadyMedia
       Set the ready (loaded) media.

       bool  papplPrinterSetReadyMedia (
           pappl_printer_t *printer,
           int num_ready,
           pappl_media_col_t *ready
       );

       This function validates and sets the printer's ready (loaded) media.

   papplPrinterSetReasons
       Add or remove values from "printer-state-reasons".

       void papplPrinterSetReasons (
           pappl_printer_t *printer,
           pappl_preason_t add,
           pappl_preason_t remove
       );

       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.

   papplPrinterSetSupplies
       Set/update the supplies for a printer.

       void papplPrinterSetSupplies (
           pappl_printer_t *printer,
           int num_supplies,
           pappl_supply_t *supplies
       );

       This function updates the supply information for the printer.

   papplPrinterSetUSB
       Set the USB vendor and product IDs for a printer.

       void papplPrinterSetUSB (
           pappl_printer_t *printer,
           unsigned vendor_id,
           unsigned product_id,
           pappl_uoptions_t options,
           const char *storagefile
       );

       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.

       5      Note: USB gadget functionality is currently only available when running

       5      on Linux with compatible hardware such as the Raspberry Pi.

STRUCTURES

   pappl_icon_s
       Printer PNG icon structure

       struct pappl_icon_s
       {
         const void *data;
         size_t datalen;
         char filename[256];
       };

   pappl_media_col_s
       Media details structure

       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];
       };

   pappl_pr_driver_data_s
       Printer driver data

       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];
       };

   pappl_pr_options_s
       Combined print job options

       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;
       };

   pappl_supply_s
       Supply data

       struct pappl_supply_s
       {
         pappl_supply_color_t color;
         char description[256];
         bool is_consumed;
         int level;
         pappl_supply_type_t type;
       };

TYPES

   pappl_color_mode_t
       Bitfield for IPP "print-color-mode" values

       typedef unsigned pappl_color_mode_t;

   pappl_content_t
       Bitfield for IPP "print-content-optimize" values

       typedef unsigned pappl_content_t;

   pappl_default_cb_t
       papplIterateDefaults callback

       typedef void (*pappl_default_cb_t)(ipp_attribute_t *attr, void *data);

   pappl_duplex_t
       Duplex printing support

       typedef enum pappl_duplex_e pappl_duplex_t;

   pappl_finishings_t
       Bitfield for IPP "finishings" values

       typedef unsigned pappl_finishings_t;

   pappl_icon_t
       Printer PNG icon structure

       typedef struct pappl_icon_s pappl_icon_t;

   pappl_identify_actions_t
       Bitfield for IPP "identify-actions" values

       typedef unsigned pappl_identify_actions_t;

   pappl_job_cb_t
       papplIterateXxxJobs callback function

       typedef void (*pappl_job_cb_t)(pappl_job_t *job, void *data);

   pappl_kind_t
       Bitfield for IPP "printer-kind" values

       typedef unsigned pappl_kind_t;

   pappl_label_mode_t
       Bitfield for IPP "label-mode-xxx" values

       typedef unsigned short pappl_label_mode_t;

   pappl_media_col_t
       Media details structure

       typedef struct pappl_media_col_s pappl_media_col_t;

   pappl_media_tracking_t
       Bitfield for IPP "media-tracking" values

       typedef unsigned short pappl_media_tracking_t;

   pappl_pr_delete_cb_t
       Printer deletion callback

       typedef void (*pappl_pr_delete_cb_t)(pappl_printer_t *printer, pappl_pr_driver_data_t *data);

   pappl_pr_identify_cb_t
       Identify-Printer callback

       typedef void (*pappl_pr_identify_cb_t)(pappl_printer_t *printer, pappl_identify_actions_t actions, const char *message);

   pappl_pr_printfile_cb_t
       Print a "raw" job callback

       typedef bool (*pappl_pr_printfile_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device);

   pappl_pr_rendjob_cb_t
       End a raster job callback

       typedef bool (*pappl_pr_rendjob_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device);

   pappl_pr_rendpage_cb_t
       End a raster page callback

       typedef bool (*pappl_pr_rendpage_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device, unsigned page);

   pappl_pr_rstartjob_cb_t
       Start a raster job callback

       typedef bool (*pappl_pr_rstartjob_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device);

   pappl_pr_rstartpage_cb_t
       Start a raster page callback

       typedef bool (*pappl_pr_rstartpage_cb_t)(pappl_job_t *job, pappl_pr_options_t *options, pappl_device_t *device, unsigned page);

   pappl_pr_rwriteline_cb_t
       Write a line of raster graphics callback

       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);

   pappl_pr_status_cb_t
       Update printer status callback

       typedef bool (*pappl_pr_status_cb_t)(pappl_printer_t *printer);

   pappl_pr_testpage_cb_t
       Print a test page callback

       typedef const char * (*pappl_pr_testpage_cb_t)(pappl_printer_t *printer, char *buffer, size_t bufsize);

   pappl_raster_type_t
       Bitfield for IPP "pwg-raster-document-type-supported" values

       typedef unsigned pappl_raster_type_t;

   pappl_scaling_t
       Bitfield for IPP "print-scaling" values

       typedef unsigned pappl_scaling_t;

   pappl_sides_t
       Bitfield for IPP "sides" values

       typedef unsigned pappl_sides_t;

   pappl_supply_color_t
       "printer-supply" color values

       typedef enum pappl_supply_color_e pappl_supply_color_t;

   pappl_supply_t
       Supply data

       typedef struct pappl_supply_s pappl_supply_t;

   pappl_supply_type_t
       IPP "printer-supply" type values

       typedef enum pappl_supply_type_e pappl_supply_type_t;

   pappl_uoptions_t
       USB gadget options bitfield

       typedef unsigned pappl_uoptions_t;

SEE ALSO

       pappl(1), pappl-client(3), pappl-device(3), pappl-job(3), pappl-log(3), pappl-mainline(3),
       pappl-makeresheader(1),     pappl-printer(3),     pappl-resource(3),      pappl-system(3),
       https://www.msweet.org/pappl

COPYRIGHT

       Copyright © 2019-2020 by Michael R Sweet.

       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
       freely  in  any  project  you'd  like.  See the files "LICENSE" and "NOTICE" in the source
       distribution for more information.