PAPPL v1.1 Programmers Manual

Michael R Sweet

Copyright © 2020 by Michael R Sweet

Contents

Introduction

PAPPL is a simple C-based framework/library for developing CUPS Printer Applications, which are the recommended replacement for printer drivers. It is sufficiently general purpose to support any kind of printer or driver that can be used on desktops, servers, and in embedded environments.

PAPPL embeds a multi-threaded HTTP / IPP Everywhere™ server and provides callbacks for a variety of events that allows a GUI or command-line application to interact with both the local user that is running the Printer Application and any network clients that are submitting print jobs, querying printer status and capabilities, and so forth.

PAPPL provides a simple driver interface for raster graphics printing, and developers of CUPS Raster drivers will readily adapt to it. PAPPL can also be used with printers that support vector graphics printing although you'll have to develop more code to support them. Drivers provide configuration and capability information to PAPPL, and PAPPL then calls the driver to print things as needed. PAPPL automatically supports printing of JPEG, PNG, PWG Raster, Apple Raster, and "raw" files to printers connected via USB and network (AppSocket/JetDirect) connections. Other formats can be supported through "filter" callbacks you register.

PAPPL is Copyright © 2019-2020 by Michael R Sweet and 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.

Requirements

PAPPL requires a POSIX-compliant host operating system such as Linux®, macOS®, QNX®, or VxWorks®, a C99 compiler like Clang or GCC, a make program that supports the include directive, and the following support libraries:

Run the following commands to install the prerequisites on CentOS 7, Fedora 22, and Red Hat Enterprise Linux 7:

sudo yum groupinstall 'Development Tools'
sudo yum install avahi-devel cups-devel gnutls-devel libjpeg-turbo-devel \
    libpam-devel libpng-devel libusbx-devel pam-devel zlib-devel

Run the following commands to install the prerequisites on CentOS 8, Fedora 23 or later, and Red Hat Enterprise Linux 8:

sudo dnf groupinstall 'Development Tools'
sudo dnf install avahi-devel cups-devel gnutls-devel libjpeg-turbo-devel \
    libpam-devel libpng-devel libusbx-devel pam-devel zlib-devel

Run the following commands to install the prerequisites on Debian GNU/Linux, Raspbian, and Ubuntu:

sudo apt-get install build-essential libavahi-client-dev libcups2-dev \
    libcupsimage2-dev libgnutls28-dev libjpeg-dev libpam-dev libpng-dev \
    libusb-1.0-0-dev zlib1g-dev

Finally, after installing Xcode from the AppStore run the following commands to install the prerequisites on macOS:

(install brew if necessary)
brew install libjpeg
brew install libpng
brew install libusb

or download, build, and install libjpeg, libpng, and libusb from source.

Building PAPPL

PAPPL uses the usual configure script to generate a make file:

./configure [options]
make

Use ./configure --help to see a full list of options.

There is also an Xcode project under the xcode directory that can be used on macOS:

open xcode/pappl.xcodeproj

You can test the build by running the PAPPL test program:

testsuite/testpappl

Installing PAPPL

Once you have successfully built PAPPL, install it using:

sudo make install

By default everything will be installed under /usr/local. Use the --prefix configure option to override the base installation directory. Set the DESTDIR, DSTROOT, or RPM_BUILD_ROOT environment variables to redirect the installation to a staging area, as is typically done for most software packaging systems (using one of those environment variables...)

Detecting PAPPL

PAPPL can be detected using the pkg-config command, for example:

if pkg-config --exists pappl; then
    ... 
fi

In a makefile you can add the necessary compiler and linker options with:

CFLAGS  +=      `pkg-config --cflags pappl`
LIBS    +=      `pkg-config --libs pappl`

Header Files

PAPPL provides a top-level header file that should be used:

#include <pappl/pappl.h>

This header includes all of the base object headers in PAPPL as well as the CUPS header files that provide the HTTP and IPP support functions.

API Overview

PAPPL provides five main objects:

PAPPL Block Diagram::100%

The System

The system is an object of type pappl_system_t that manages client and device connections, listeners, the log, printers, and resources. It implements a subset of the IPP System Service (PWG 5100.22) with each printer implementing IPP Everywhere™ (PWG 5100.14) and some extensions to provide compatibility with the full range of mobile and desktop client devices. In addition, it provides an optional embedded web interface, raw socket printing, and USB printer gadget (Linux only).

A system object is created using the papplSystemCreate function and deleted using the papplSystemDelete function. Each system manages zero or more printers which can be accessed using either of the following functions:

The papplSystemLoadState function is often used to load system values and printers from a prior run which used the papplSystemSaveState function.

IP and domain socket listeners are added using the papplSystemAddListeners function.

The papplSystemGet functions get various system values:

Similarly, the papplSystemSet functions set various system values:

Logging

The PAPPL logging functions record messages to the configured log file. The papplLog records messages applying to the system as a whole while papplLogClient, papplLogJob, and papplLogPrinter record messages specific to a client connection, print job, or printer respectively.

The "level" argument specifies a log level from debugging (PAPPL_LOGLEVEL_DEBUG) to fatal (PAPPL_LOGLEVEL_FATAL) and is used to determine whether the message is recorded to the log.

The "message" argument specifies the message using a printf format string.

Navigation links can be added to the web interface using the papplSystemAddLink function and removed using the papplSystemRemoveLink function.

Run Loops

PAPPL provides two functions to manage its run loops:

You can learn more about the second function in the chapter on the HP Printer Application Example.

The system will run until it receives a Shutdown-System request, a termination signal, or you call the papplSystemShutdown function. You can test whether is system is running with the papplSystmeIsRunning function and whether it has been shut down with the papplSystemIsShutdown function.

Resources

PAPPL provides several functions for adding static and dynamic resources to the embedded HTTP server:

Resources may be removed using the papplSystemRemoveResource function.

Clients

The PAPPL client functions provide access to client connections. Client connections and the life cycle of the pappl_client_t objects are managed automatically by the system object for the printer application.

The papplClientGet functions get the current values for various client- supplied request data:

Responding to Client Requests

The papplClientRespond function starts a HTTP response to a client request. The papplClientHTMLHeader and papplClientHTMLFooter functions send standard HTML headers and footers for the printer application's configured web interface while the papplClientHTMLEscape, papplClientHTMLPrintf, papplClientHTMLPuts, and papplClientHTMLStartForm functions send HTML messages or strings. Use the papplClientGetHTTP and (CUPS) httpWrite2 functions to send arbitrary data in a client response. Cookies can be included in web browser requests using the papplClientSetCookie function.

The papplClientRespondIPP function starts an IPP response. Use the various CUPS ippAdd functions to add attributes to the response message.

The papplClientRespondRedirect function sends a redirection response to the client.

HTML Forms

PAPPL provides the papplClientGetCSRFToken, papplClientGetForm, papplClientHTMLStartForm, and papplClientValidateForm functions to securely manage HTML forms.

The papplClientHTMLStartForm function starts a HTML form and inserts a hidden variable containing a CSRF token that was generated by PAPPL from a secure session key that is periodically updated. Upon receipt of a follow-up form submission request, the papplClientGetForm and papplClientValidateForm functions can be used to securely read the form data (including any file attachments) and validate the hidden CSRF token.

Authentication and Authorization

PAPPL supports both user-based authentication using PAM modules and a simple cookie-based password authentication mechanism that is used to limit administrative access through the web interface.

The papplHTMLAuthorize function authorizes access to the web interface and handles displaying an authentication form on the client's web browser. The return value indicates whether the client is authorized to access the web page.

The papplIsAuthorized function can be used to determine whether the current client is authorized to perform administrative operations and is normally only used for IPP clients. Local users are always authorized while remote users must provide credentials (typically a username and password) for access. This function will return an HTTP status code that can be provided to the httpClientSendResponse function. The value HTTP_STATUS_CONTINUE indicates that authorization is granted and the request should continue. The papplGetUsername function can be used to obtain the authenticated user identity.

Devices

The PAPPL device functions provide access to output device connections and to list available output devices. Output devices are accessed using Uniform Resource Identifier (URI) strings such as "file:///path/to/file-or-directory", "socket://11.22.33.44", and "usb://make/model?serial=number". The follow URI schemes are supported by PAPPL:

Custom device URI schemes can be registered using the papplDeviceAddScheme function.

The papplDeviceList function lists available output devices, providing each available output device to the supplied callback function. The list only contains devices whose URI scheme supports discovery, at present USB printers and network printers that advertise themselves using DNS-SD/mDNS and/or SNMPv1.

The papplDeviceOpen function opens a connection to an output device using its URI. The papplDeviceClose function closes the connection.

The papplDevicePrintf, papplDevicePuts, and papplDeviceWrite functions send data to the device, while the papplDeviceRead function reads data from the device.

The papplDeviceGet functions get various device values:

Printers

Printers are managed by the system and are represented by the pappl_printer_t type. Each printer is connected to a device and uses a driver to process document data and produce output. PAPPL supports raster printers out-of-the-box and provides filter callbacks to support other kinds of printers.

Printers are created using the papplPrinterCreate function and deleted using the papplPrinterDelete function. Each printer has zero or more jobs that are pending, processing (printing), or completed which can be access using any of the following functions:

The papplPrinterGet functions get various printer values:

Similarly, the papplPrinterSet functions set those values:

Accessing the Printer Device

When necessary, the device associated with a printer can be opened with the papplPrinterOpenDevice function and subsequently closed using the papplPrinterCloseDevice function.

Controlling Printers

Printers are stopped using the papplPrinterPause function and started using the papplPrinterResume function.

Navigation links can be added to the web interface using the papplPrinterAddLink function and removed using the papplPrinterRemoveLink function.

Jobs

Jobs are managed by the system and are represented by the pappl_job_t type. Jobs are created and deleted automatically by the system object for the printer application.

The papplJobGet functions get the current values associated with a job:

Similarly, the papplJobSet functions set the current values associated with a job:

Controlling Jobs

The papplJobCancel function cancels processing of a job while the papplJobIsCanceled function returns whether a job is in the canceled state (IPP_JSTATE_CANCELED) or is in the process of being canceled (IPP_JSTATE_PROCESSING and PAPPL_JREASON_PROCESSING_TO_STOP_POINT).

Processing Jobs

PAPPL stores print options in pappl_pr_options_t objects. The papplJobCreatePrintOptions function creates a new print option object and initializes it using the job's attributes and printer defaults. The creator of a print options object must free it using the papplJobDeletePrintOptions function.

The papplJobOpenFile function opens a file associated with the job. The file descriptor must be closed by the caller using the close function. The primary document file for a job can be retrieved using the papplJobGetFilename function, and its format using the papplJobGetFormat function.

Filters allow a printer application to support different file formats. PAPPL includes raster filters for PWG and Apple raster documents (streamed) as well as JPEG and PNG image files. Filters for other formats or non-raster printers can be added using the papplSystemAddMIMEFilter function.

The papplJobFilterImage function converts raw image data to raster data suitable for the printer, and prints using the printer driver's raster callbacks. Raster filters that output a single page can use this function to handle the details of scaling, cropping, color space conversion, and dithering for raster printers. A raster filter that needs to print more than one image must use the raster callback functions in the pappl_pr_driver_data_t structure directly.

Filters that produce non-raster data can call the papplDevice functions to directly communicate with the printer in its native language.

The HP Printer Application Example

This chapter will guide you through creating a simple PCL printer application based on the old CUPS "rastertohp" filter. The complete code can be found in the hp-printer-app project and serves as an overgrown "Hello, World!" program for PAPPL.

The Main Loop

All printer applications require some sort of a main loop for processing IPP requests, printing files, and so forth. PAPPL provides the papplMainloop convenience function that provides a standard command-line interface, and in the "hp-printer-app" project the main function just calls papplMainloop to do all of the work:

int
main(int  argc, char *argv[])
{
  return (papplMainloop(argc, argv,
                        /*version*/"1.0",
                        /*footer_html*/NULL,
                        (int)(sizeof(pcl_drivers) / sizeof(pcl_drivers[0])),
                        pcl_drivers, pcl_callback, pcl_autoadd,
                        /*subcmd_name*/NULL, /*subcmd_cb*/NULL,
                        /*system_cb*/NULL,
                        /*usage_cb*/NULL,
                        /*data*/NULL));
}

As you can see, we pass in the command-line arguments, a version number ("1.0") for our printer application, a list of drivers supported by the printer application, a callback for the driver that will configure a printer for a named driver, and a callback for automatically adding printers.

The "footer_html" argument can be provided to override the default footer text that appears at the bottom of the web interface. In this case we are passing NULL to use the default.

The drivers list is a collection of names, descriptions, IEEE-1284 device IDs, and extension pointers. Ours looks like this for HP DeskJet, HP LaserJet, and a generic PCL driver:

static pappl_pr_driver_t pcl_drivers[] =// Driver information
{   /* name */          /* description */       /* device ID */ /* extension */
  { "hp_deskjet",       "HP Deskjet",           NULL,           NULL },
  { "hp_generic",       "Generic PCL",          "CMD:PCL;",     NULL },
  { "hp_laserjet",      "HP LaserJet",          NULL,           NULL }
};

The driver callback is responsible for providing the data associated with each driver, while the auto-add callback tells PAPPL which driver to use for the printers it finds.

The "subcmd_name" and "subcmd_cb" arguments specify a custom sub-command for the printer application along with a function to call. Since this printer application does not have a custom sub-command, we pass NULL for both.

The "system_cb" argument specifies a callback for creating the system object. We pass NULL because we want the default system object for this printer application, which supports multiple printers and a web interface.

The "usage_cb" argument specifies a callback from displaying the program usage message. Passing NULL yields the default usage message.

The "data" argument specifies a pointer that will be passed to any of the callback functions. We pass NULL since we do not have any extra contextual information to provide to the callbacks.

The papplMainloop function runs until all processing for the current sub-command is complete, returning the exit status for the program.

The Driver Callback

The PAPPL driver callback is called when the system is creating a new printer object. It receives pointers to the system, driver name, device URI, a driver data structure, an IPP attributes pointer, and the callback data, and it returns a boolean indicating whether the driver callback was successful:

typedef bool (*pappl_pr_driver_cb_t)(pappl_system_t *system,
    const char *driver_name, const char *device_uri,
    pappl_pr_driver_data_t *driver_data, ipp_t **driver_attrs, void *data);

A driver callback can communicate with the printer via its device URI as needed to configure the driver, however our printer application doesn't need to do that.

The first thing our pcl_callback function does is to set the printer callbacks in the driver data structure:

driver_data->printfile_cb    = pcl_print;
driver_data->rendjob_cb      = pcl_rendjob;
driver_data->rendpage_cb     = pcl_rendpage;
driver_data->rstartjob_cb    = pcl_rstartjob;
driver_data->rstartpage_cb   = pcl_rstartpage;
driver_data->rwriteline_cb   = pcl_rwriteline;
driver_data->status_cb       = pcl_status;

The pcl_print function prints a raw PCL file while the pcl_r functions print raster graphics. The pcl_status updates the printer status.

Next is the printer's native print format as a MIME media type, in this case HP PCL:

driver_data->format          = "application/vnd.hp-pcl";

The default orientation and print quality follow:

driver_data->orient_default  = IPP_ORIENT_NONE;
driver_data->quality_default = IPP_QUALITY_NORMAL;

Then the values for the various drivers. Here are the HP DeskJet driver settings:

if (!strcmp(driver_name, "hp_deskjet"))
{
  /* Make and model name */
  strncpy(driver_data->make_and_model, "HP DeskJet", sizeof(driver_data->make_and_model) - 1);

  /* Pages-per-minute for monochrome and color */
  driver_data->ppm       = 8;
  driver_data->ppm_color = 2;

  /* Three resolutions - 150dpi, 300dpi (default), and 600dpi */
  driver_data->num_resolution  = 3;
  driver_data->x_resolution[0] = 150;
  driver_data->y_resolution[0] = 150;
  driver_data->x_resolution[1] = 300;
  driver_data->y_resolution[1] = 300;
  driver_data->x_resolution[2] = 600;
  driver_data->y_resolution[2] = 600;
  driver_data->x_default = driver_data->y_default = 300;

  /* Four color spaces - black (1-bit and 8-bit), grayscale, and sRGB */
  driver_data->raster_types = PAPPL_PWG_RASTER_TYPE_BLACK_1 | PAPPL_PWG_RASTER_TYPE_BLACK_8 | PAPPL_PWG_RASTER_TYPE_SGRAY_8 | PAPPL_PWG_RASTER_TYPE_SRGB_8;

  /* Color modes: auto (default), monochrome, and color */
  driver_data->color_supported = PAPPL_COLOR_MODE_AUTO | PAPPL_COLOR_MODE_AUTO_MONOCHROME | PAPPL_COLOR_MODE_COLOR | PAPPL_COLOR_MODE_MONOCHROME;
  driver_data->color_default   = PAPPL_COLOR_MODE_AUTO;

  /* Media sizes with 1/4" left/right and 1/2" top/bottom margins*/
  driver_data->num_media = (int)(sizeof(pcl_hp_deskjet_media) / sizeof(pcl_hp_deskjet_media[0]));
  memcpy(driver_data->media, pcl_hp_deskjet_media, sizeof(pcl_hp_deskjet_media));

  driver_data->left_right = 635;       // 1/4" left and right
  driver_data->bottom_top = 1270;      // 1/2" top and bottom

  /* 1-sided printing only */
  driver_data->sides_supported = PAPPL_SIDES_ONE_SIDED;
  driver_data->sides_default   = PAPPL_SIDES_ONE_SIDED;

  /* Three paper trays (MSN names) */
  driver_data->num_source = 3;
  driver_data->source[0]  = "tray-1";
  driver_data->source[1]  = "manual";
  driver_data->source[2]  = "envelope";

  /* Five media types (MSN names) */
  driver_data->num_type = 5;
  driver_data->type[0] = "stationery";
  driver_data->type[1] = "bond";
  driver_data->type[2] = "special";
  driver_data->type[3] = "transparency";
  driver_data->type[4] = "photographic-glossy";
}

Finally, we fill out the ready and default media for each media source (tray), putting US Letter paper in the regular trays and #10 envelopes in any envelope tray:

// Fill out ready and default media (default == ready media from the first source)
for (i = 0; i < driver_data->num_source; i ++)
{
  pwg_media_t *pwg;                   /* Media size information */

  /* Use US Letter for regular trays, #10 envelope for the envelope tray */
  if (!strcmp(driver_data->source[i], "envelope"))
    strncpy(driver_data->media_ready[i].size_name, "env_10_4.125x9.5in", sizeof(driver_data->media_ready[i].size_name) - 1);
  else
    strncpy(driver_data->media_ready[i].size_name, "na_letter_8.5x11in", sizeof(driver_data->media_ready[i].size_name) - 1);

  /* Set margin and size information */
  if ((pwg = pwgMediaForPWG(driver_data->media_ready[i].size_name)) != NULL)
  {
    driver_data->media_ready[i].bottom_margin = driver_data->bottom_top;
    driver_data->media_ready[i].left_margin   = driver_data->left_right;
    driver_data->media_ready[i].right_margin  = driver_data->left_right;
    driver_data->media_ready[i].size_width    = pwg->width;
    driver_data->media_ready[i].size_length   = pwg->length;
    driver_data->media_ready[i].top_margin    = driver_data->bottom_top;
    strncpy(driver_data->media_ready[i].source, driver_data->source[i], sizeof(driver_data->media_ready[i].source) - 1);
    strncpy(driver_data->media_ready[i].type, driver_data->type[0],  sizeof(driver_data->media_ready[i].type) - 1);
  }
}

driver_data->media_default = driver_data->media_ready[0];

return (true);

The Auto-Add Callback

The PAPPL auto-add callback is called when processing the "autoadd" sub-command. It is called for each new device and is responsible for returning the name of the driver to be used for the device or NULL if no driver is available:

typedef const char *(*pappl_ml_autoadd_cb_t)(const char *device_info,
    const char *device_uri, const char *device_id, void *data);

Our pcl_autoadd function uses the IEEE-1284 device ID string to determine whether one of the drivers will work. The papplDeviceParseID function splits the string into key/value pairs that can be looked up using the cupsGetOption function:

const char      *ret = NULL;            // Return value
int             num_did;                // Number of device ID key/value pairs
cups_option_t   *did;                   // Device ID key/value pairs
const char      *cmd,                   // Command set value
                *pcl;                   // PCL command set pointer


// Parse the IEEE-1284 device ID to see if this is a printer we support...
num_did = papplDeviceParseID(device_id, &did);

The two keys we care about are the "COMMAND SET" (also abbreviated as "CMD") for the list of document formats the printer supports and "MODEL"/"MDL" for the model name. We are looking for the "PCL" format and one of the common model names for HP printers:

// Look at the COMMAND SET (CMD) key for the list of printer languages,,,
if ((cmd = cupsGetOption("COMMAND SET", num_did, did)) == NULL)
  cmd = cupsGetOption("CMD", num_did, did);

if (cmd && (pcl = strstr(cmd, "PCL")) != NULL && (pcl[3] == ',' || !pcl[3]))
{
  // Printer supports HP PCL, now look at the MODEL (MDL) string to see if
  // it is one of the HP models or a generic PCL printer...
  const char *mdl;                      // Model name string

  if ((mdl = cupsGetOption("MODEL", num_did, did)) == NULL)
    mdl = cupsGetOption("MDL", num_did, did);

  if (mdl && (strstr(mdl, "DeskJet") || strstr(mdl, "Photosmart")))
    ret = "hp_deskjet";                 // HP DeskJet/Photosmart printer
  else if (mdl && strstr(mdl, "LaserJet"))
    ret = "hp_laserjet";                // HP LaserJet printer
  else
    ret = "hp_generic";                 // Some other PCL laser printer
}

cupsFreeOptions(num_did, did);

return (ret);

The File Printing Callback

The file printing callback is used when printing a "raw" (printer-ready) file from a client:

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

This callback will sometimes send some printer initialization commands followed by the job file and then any cleanup commands. It may also be able to count the number of pages (impressions) in the file, although that is not a requirement. For the HP Printer Application our pcl_print function just copies the file from the job to the device and assumes that the file contains only one page:

int     fd;                     // Job file
ssize_t bytes;                  // Bytes read/written
char    buffer[65536];          // Read/write buffer


papplJobSetImpressions(job, 1);

fd = open(papplJobGetFilename(job), O_RDONLY);

while ((bytes = read(fd, buffer, sizeof(buffer))) > 0)
{
  if (papplDeviceWrite(device, buffer, (size_t)bytes) < 0)
  {
    papplLogJob(job, PAPPL_LOGLEVEL_ERROR,
                "Unable to send %d bytes to printer.", (int)bytes);
    close(fd);
    return (false);
  }
}

close(fd);

papplJobSetImpressionsCompleted(job, 1);

return (true);

The Raster Printing Callbacks

The PAPPL raster printing callbacks are used for printing PWG and Apple raster documents, JPEG and PNG images, and other formats that end up as raster data:

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

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

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

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

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

Each of the raster printing callbacks is expected to send data to the printer using the provided "device" pointer. The "job" argument provides the current job object and the "options" pointer provides the current print job options. The "page" argument specifies the current page number staring at 0.

The pappl_pr_rstartjob_cb_t function is called at the beginning of a job to allow the driver to initialize the printer for the current job.

The pappl_pr_rstartpage_cb_t function is called at the beginning of each page to allow the driver to do any per-page initialization and/or memory allocations and send any printer commands that are necessary to start a new page.

The pappl_pr_rwriteline_cb_t function is called for each raster line on the page and is typically responsible for dithering and compressing the raster data for the printer.

The pappl_pr_rendpage_cb_t function is called at the end of each page where the driver will typically eject the current page.

The pappl_pr_rendjob_cb_t function is called at the end of a job to allow the driver to send any cleanup commands to the printer.

The Identification Callback

The PAPPL identification callback is used to audibly or visibly identify the printer being used:

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

The most common identification method is PAPPL_IDENTIFY_ACTIONS_SOUND which should have the printer make a sound. The PAPPL_IDENTIFY_ACTIONS_DISPLAY and PAPPL_IDENTIFY_ACTIONS_SPEAK methods use the "message" argument to display or speak a message. Finally, the PAPPL_IDENTIFY_ACTIONS_FLASH method flashes a light on the printer.

The HP Printer Application does not have an identification callback since most PCL printers lack a buzzer or light that can be remotely activated.

Note: IPP Everywhere™ requires all printers to support identification. A warning message is logged by PAPPL whenever a driver does not set the identify_cb member of the printer driver data structure.

The Status Callback

The PAPPL status callback is used to update the printer state, supply levels, and/or ready media for the printer:

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

The callback can open a connection to the printer using the papplPrinterOpenDevice function.

The Self-Test Page Callback

The PAPPL self-test page callback is used to generate a self-test page for the printer:

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

When the callback returns a filename (copied to the specified buffer), that file will be queued as a job for the printer. The callback can also try opening the device using the papplPrinterOpenDevice function to send a printer self-test command instead - in this case the callback must return NULL to indicate there is no file to be printed.

Functions

papplClientGetCSRFToken

Get a unique Cross-Site Request Forgery token string.

char *papplClientGetCSRFToken(pappl_client_t *client, char *buffer, size_t bufsize);

Parameters

client Client
buffer String buffer
bufsize Size of string buffer

Return Value

Token string

Discussion

This function generates and returns a unique Cross-Site Request Forgery token string to be used as the value of a hidden variable in all HTML forms sent in the response and then compared when validating the form data in the subsequent request.

The value is based on the current system session key and client address in order to make replay attacks infeasible.

Note: The papplClientHTMLStartForm function automatically adds the hidden CSRF variable, and the papplClientIsValidForm function validates the value.

papplClientGetCookie

Get a cookie from the client.

char *papplClientGetCookie(pappl_client_t *client, const char *name, char *buffer, size_t bufsize);

Parameters

client Client
name Name of cookie
buffer Value buffer
bufsize Size of value buffer

Return Value

Cookie value or NULL if not set

Discussion

This function gets a HTTP "cookie" value from the client request. NULL is returned if no cookie has been set by a prior request, or if the user has disabled or removed the cookie.

Use the papplClientSetCookie function to set a cookie in a response to a request.

Note: Cookies set with papplClientSetCookie will not be available to this function until the following request.

papplClientGetForm

Get form data from the web client.

int papplClientGetForm(pappl_client_t *client, cups_option_t **form);

Parameters

client Client
form Form variables

Return Value

Number of form variables read

Discussion

For HTTP GET requests, the form data is collected from the request URI. For HTTP POST requests, the form data is read from the client.

The returned form values must be freed using the cupsFreeOptions function.

Note: Because the form data is read from the client connection, this function can only be called once per request.

papplClientGetHTTP

Get the HTTP connection associated with a client object.

http_t *papplClientGetHTTP(pappl_client_t *client);

Parameters

client Client

Return Value

HTTP connection

Discussion

This function returns the HTTP connection associated with the client and is used when sending response data directly to the client using the CUPS httpXxx functions.

papplClientGetHostName

Get the hostname from the client-supplied Host: field.

const char *papplClientGetHostName(pappl_client_t *client);

Parameters

client Client

Return Value

Hostname or NULL for none

Discussion

This function returns the hostname that was used in the request and should be used in any URLs or URIs that you generate.

papplClientGetHostPort

Get the port from the client-supplied Host: field.

int papplClientGetHostPort(pappl_client_t *client);

Parameters

client Client

Return Value

Port number or 0 for none

Discussion

This function returns the port number that was used in the request and should be used in any URLs or URIs that you generate.

papplClientGetJob

Get the target job for an IPP request.

pappl_job_t *papplClientGetJob(pappl_client_t *client);

Parameters

client Client

Return Value

Target job or NULL if none

Discussion

This function returns the job associated with the current IPP request. NULL is returned if the request does not target a job.

papplClientGetMethod

Get the HTTP request method.

http_state_t papplClientGetMethod(pappl_client_t *client);

Parameters

client Client

Return Value

HTTP method

Discussion

This function returns the HTTP request method that was used, for example HTTP_STATE_GET for a GET request or HTTP_STATE_POST for a POST request.

papplClientGetOperation

Get the IPP operation code.

ipp_op_t papplClientGetOperation(pappl_client_t *client);

Parameters

client Client

Return Value

IPP operation code

Discussion

This function returns the IPP operation code associated with the current IPP request.

papplClientGetOptions

Get the options from the request URI.

const char *papplClientGetOptions(pappl_client_t *client);

Parameters

client Client

Return Value

Options or NULL if none

Discussion

This function returns any options that were passed in the HTTP request URI. The options are the characters after the "?" character, for example a request URI of "/mypage?name=value" will have an options string of "name=value".

NULL is returned if the request URI did not contain any options.

Note: HTTP GET form variables are normally accessed using the papplClientGetForm function. This function should only be used when getting non-form data.

papplClientGetPrinter

Get the target printer for an IPP request.

pappl_printer_t *papplClientGetPrinter(pappl_client_t *client);

Parameters

client Client

Return Value

Target printer or NULL if none

Discussion

This function returns the printer associated with the current IPP request. NULL is returned if the request does not target a printer.

papplClientGetRequest

Get the IPP request message.

ipp_t *papplClientGetRequest(pappl_client_t *client);

Parameters

client Client

Return Value

IPP request message

Discussion

This function returns the attributes in the current IPP request, for use with the CUPS ippFindAttribute, ippFindNextAttribute, ippFirstAttribute, and ippNextAttribute functions.

papplClientGetResponse

Get the IPP response message.

ipp_t *papplClientGetResponse(pappl_client_t *client);

Parameters

client Client

Return Value

IPP response message

Discussion

This function returns the attributes in the current IPP response, for use with the CUPS ippAddXxx and ippSetXxx functions. Use the papplClientRespondIPP function to set the status code and message, if any.

papplClientGetSystem

Get the containing system for the client.

pappl_system_t *papplClientGetSystem(pappl_client_t *client);

Parameters

client Client

Return Value

System

Discussion

This function returns the system object that contains the client.

papplClientGetURI

Get the HTTP request URI.

const char *papplClientGetURI(pappl_client_t *client);

Parameters

client Client

Return Value

Request URI

Discussion

This function returns the URI that was sent in the current HTTP request.

Note: Any options in the URI are removed and can be accessed separately using the papplClientGetOptions function.

papplClientGetUsername

Get the authenticated username, if any.

const char *papplClientGetUsername(pappl_client_t *client);

Parameters

client Client

Return Value

Authenticated username or NULL if none

Discussion

This function returns the current authenticated username, if any.

papplClientHTMLAuthorize

Handle authorization for the web interface.

bool papplClientHTMLAuthorize(pappl_client_t *client);

Parameters

client Client

Return Value

true if authorized, false otherwise

Discussion

The web interface supports both authentication against user accounts and authentication using a single administrative access password. This function handles the details of authentication for the web interface based on the system authentication service configuration (the "auth_service" argument to papplSystemCreate).

Note: IPP operation callbacks needing to perform authorization should use the papplClientIsAuthorized function instead.

papplClientHTMLEscape

Send a string to a web browser client.

void papplClientHTMLEscape(pappl_client_t *client, const char *s, size_t slen);

Parameters

client Client
s String to write
slen Number of characters to write (0 for nul-terminated)

Discussion

This function sends the specified string to the web browser client and escapes special characters as HTML entities as needed, for example "&" is sent as &amp;.

papplClientHTMLFooter

Show the web interface footer.

void papplClientHTMLFooter(pappl_client_t *client);

Parameters

client Client

Discussion

This function sends the standard web interface footer followed by a trailing 0-length chunk to finish the current HTTP response. Use the papplSystemSetFooterHTML function to add any custom HTML needed in the footer.

papplClientHTMLHeader

Show the web interface header and title.

void papplClientHTMLHeader(pappl_client_t *client, const char *title, int refresh);

Parameters

client Client
title Title
refresh Refresh time in seconds (0 for no refresh)

Discussion

This function sends the standard web interface header and title. If the "refresh" argument is greater than zero, the page will automatically reload after that many seconds.

Use the papplSystemAddLink function to add system-wide navigation links to the header. Similarly, use papplPrinterAddLink to add printer-specific links, which will appear in the web interface printer if the system is not configured to support multiple printers (the PAPPL_SOPTIONS_MULTI_QUEUE option to papplSystemCreate).

papplClientHTMLPrinterFooter

Show the web interface footer for printers.

void papplClientHTMLPrinterFooter(pappl_client_t *client);

Parameters

client Client

Discussion

This function sends the standard web interface footer for a printer followed by a trailing 0-length chunk to finish the current HTTP response. Use the papplSystemSetFooterHTML function to add any custom HTML needed in the footer.

papplClientHTMLPrinterHeader

Show the web interface header and title for printers.

void papplClientHTMLPrinterHeader(pappl_client_t *client, pappl_printer_t *printer, const char *title, int refresh, const char *label, const char *path_or_url);

Parameters

client Client
printer Printer
title Title
refresh Refresh time in seconds or 0 for none
label Button label or NULL for none
path_or_url Button path or NULL for none

Discussion

This function sends the standard web interface header and title for a printer. If the "refresh" argument is greater than zero, the page will automatically reload after that many seconds.

If "label" and "path_or_url" are non-NULL strings, an additional navigation link is included with the title header - this is typically used for an action button ("Change").

Use the papplSystemAddLink function to add system-wide navigation links to the header. Similarly, use papplPrinterAddLink to add printer-specific links, which will appear in the web interface printer if the system is not configured to support multiple printers (the PAPPL_SOPTIONS_MULTI_QUEUE option to papplSystemCreate).

papplClientHTMLPrintf

Send formatted text to the web browser client, escaping as needed.

void papplClientHTMLPrintf(pappl_client_t *client, const char *format, ...);

Parameters

client Client
format Printf-style format string
... Additional arguments as needed

Discussion

This function sends formatted text to the web browser client using printf-style formatting codes. The format string itself is not escaped to allow for embedded HTML, however strings inserted using the '%c' or %s codes are escaped properly for HTML - "&" is sent as &amp;, etc.

papplClientHTMLPuts

Send a HTML string to the web browser client.

void papplClientHTMLPuts(pappl_client_t *client, const char *s);

Parameters

client Client
s String

Discussion

This function sends a HTML string to the client without performing any escaping of special characters.

papplClientHTMLStartForm

Start a HTML form.

void papplClientHTMLStartForm(pappl_client_t *client, const char *action, bool multipart);

Parameters

client Client
action Form action URL
multipart true if the form allows file uploads, false otherwise

Discussion

This function starts a HTML form with the specified "action" path and includes the CSRF token as a hidden variable. If the "multipart" argument is true, the form is annotated to support file attachments up to 2MiB in size.

papplClientIsAuthorized

Determine whether a client is authorized for administrative requests.

http_status_t papplClientIsAuthorized(pappl_client_t *client);

Parameters

client Client

Return Value

HTTP status

Discussion

This function determines whether a client is authorized to submit an administrative request.

The return value is HTTP_STATUS_CONTINUE if access is authorized, HTTP_STATUS_FORBIDDEN if access is not allowed, HTTP_STATUS_UNAUTHORIZED if authorization is required, or HTTP_STATUS_UPGRADE_REQUIRED if the connection needs to be encrypted. All of these values can be passed to the papplClientRespond function.

papplClientIsValidForm

Validate HTML form variables.

bool papplClientIsValidForm(pappl_client_t *client, int num_form, cups_option_t *form);

Parameters

client Client
num_form Number of form variables
form Form variables

Return Value

true if the CSRF token is valid, false otherwise

Discussion

This function validates the contents of a HTML form using the CSRF token included as a hidden variable. When sending a HTML form you should use the papplClientStartForm function to start the HTML form and insert the CSRF token for later validation.

Note: Callers are expected to validate all other form variables.

papplClientRespond

Send a regular HTTP response.

bool papplClientRespond(pappl_client_t *client, http_status_t code, const char *content_encoding, const char *type, time_t last_modified, size_t length);

Parameters

client Client
code HTTP status of response
content_encoding Content-Encoding of response
type MIME media type of response
last_modified Last-Modified date/time or 0 for none
length Length of response or 0 for variable-length

Return Value

true on success, false on failure

Discussion

This function sends all of the required HTTP fields and includes standard messages for errors. The following values for "code" are explicitly supported:

Use the papplClientRespondRedirect when you need to redirect the client to another page.

papplClientRespondIPP

Send an IPP response.

ipp_t *papplClientRespondIPP(pappl_client_t *client, ipp_status_t status, const char *message, ...);

Parameters

client Client
status status-code
message printf-style status-message
... Additional args as needed

Return Value

IPP response message

Discussion

This function sets the return status for an IPP request and returns the current IPP response message. The "status" and "message" arguments replace any existing status-code and "status-message" attribute value that may be already present in the response.

Note: You should call this function prior to adding any response attributes.

papplClientRespondIPPUnsupported

Respond with an unsupported IPP attribute.

void papplClientRespondIPPUnsupported(pappl_client_t *client, ipp_attribute_t *attr);

Parameters

client Client
attr Atribute

Discussion

This function returns a 'client-error-attributes-or-values-not-supported' status code and adds the specified attribute to the unsupported attributes group in the response.

papplClientRespondRedirect

Respond with a redirect to another page.

bool papplClientRespondRedirect(pappl_client_t *client, http_status_t code, const char *path);

Parameters

client Client
code HTTP_STATUS_MOVED_PERMANENTLY or HTTP_STATUS_FOUND
path Redirection path/URL

Return Value

true on success, false otherwise

Discussion

This function sends a HTTP response that redirects the client to another page or URL. The most common "code" value to return is HTTP_STATUS_FOUND.

papplClientSetCookie

Set a cookie for the web browser client.

void papplClientSetCookie(pappl_client_t *client, const char *name, const char *value, int expires);

Parameters

client Client
name Cookie name
value Cookie value
expires Expiration in seconds from now, 0 for a session cookie

Discussion

This function sets the value of a cookie for the client by updating the Set-Cookie header in the HTTP response that will be sent. The "name" and "value" strings must contain only valid characters for a cookie and its value as documented in RFC 6265, which basically means letters, numbers, "@", "-", ".", and "_".

The "expires" argument specifies how long the cookie will remain active in seconds, for example 3600 seconds is one hour and 86400 seconds is one day. If the value is zero or less, a "session" cookie is created instead which will expire as soon as the web browser is closed.

papplDeviceAddScheme

Add a device URI scheme.

void papplDeviceAddScheme(const char *scheme, pappl_devtype_t dtype, pappl_devlist_cb_t list_cb, pappl_devopen_cb_t open_cb, pappl_devclose_cb_t close_cb, pappl_devread_cb_t read_cb, pappl_devwrite_cb_t write_cb, pappl_devstatus_cb_t status_cb, pappl_devid_cb_t id_cb);

Parameters

scheme URI scheme
dtype Device type (PAPPL_DEVTYPE_CUSTOM_LOCAL or PAPPL_DEVTYPE_CUSTOM_NETWORK)
list_cb List devices callback, if any
open_cb Open callback
close_cb Close callback
read_cb Read callback
write_cb Write callback
status_cb Status callback, if any
id_cb IEEE-1284 device ID callback, if any

Discussion

This function registers a device URI scheme with PAPPL, so that devices using the named scheme can receive print data, report status information, and so forth. PAPPL includes support for the following URI schemes:

The "scheme" parameter specifies the URI scheme and must consist of lowercase letters, digits, "-", "_", and/or ".", for example "x-foo" or "com.example.bar".

The "dtype" parameter specifies the device type and should be PAPPL_DTYPE_CUSTOM_LOCAL for locally connected printers and PAPPL_DTYPE_CUSTOM_NETWORK for network printers.

Each of the callbacks corresponds to one of the papplDevice functions:

The "open_cb" callback typically calls papplDeviceSetData to store a pointer to contextual information for the connection while the "close_cb", "id_cb", "read_cb", "write_cb", and "status_cb" callbacks typically call papplDeviceGetData to retrieve it.

papplDeviceClose

Close a device connection.

void papplDeviceClose(pappl_device_t *device);

Parameters

device Device to close

Discussion

This function flushes any pending write data and closes the connection to a device.

papplDeviceError

Report an error on a device.

void papplDeviceError(pappl_device_t *device, const char *message, ...);

Parameters

device Device
message Printf-style error message
... Additional arguments as needed

Discussion

This function reports an error on a device using the client-supplied callback function. It is normally called from any custom device URI scheme callbacks you implement.

papplDeviceFlush

Flush any buffered data to the device.

void papplDeviceFlush(pappl_device_t *device);

Parameters

device Device

Discussion

This function flushes any pending write data sent using the papplDevicePrintf, papplDevicePuts, or papplDeviceWrite functions to the device.

papplDeviceGetData

Get device-specific data.

void *papplDeviceGetData(pappl_device_t *device);

Parameters

device Device

Return Value

Device data pointer

Discussion

This function returns any device-specific data that has been set by the device open callback. It is normally only called from any custom device URI scheme callbacks you implement.

papplDeviceGetID

Get the IEEE-1284 device ID.

char *papplDeviceGetID(pappl_device_t *device, char *buffer, size_t bufsize);

Parameters

device Device
buffer Buffer for IEEE-1284 device ID
bufsize Size of buffer

Return Value

IEEE-1284 device ID or NULL on failure

Discussion

This function queries the IEEE-1284 device ID from the device and copies it to the provided buffer. The buffer must be at least 64 bytes and should be at least 1024 bytes in length.

Note: This function can block for up to several seconds depending on the type of connection.

papplDeviceGetMetrics

Get the device metrics.

pappl_devmetrics_t *papplDeviceGetMetrics(pappl_device_t *device, pappl_devmetrics_t *metrics);

Parameters

device Device
metrics Buffer for metrics data

Return Value

Metrics data

Discussion

This function returns a copy of the device metrics data, which includes the number, length (in bytes), and duration (in milliseconds) of read, status, and write requests for the current session. This information is normally used for performance measurement and optimization during development of a printer application. It can also be useful diagnostic information.

papplDeviceGetStatus

Get the printer status bits.

pappl_preason_t papplDeviceGetStatus(pappl_device_t *device);

Parameters

device Device

Return Value

IPP "printer-state-reasons" values

Discussion

This function returns the current printer status bits, as applicable to the current device.

The status bits for USB devices come from the original Centronics parallel printer "standard" which was later formally standardized in IEEE 1284-1984 and the USB Device Class Definition for Printing Devices. Some vendor extensions are also supported.

The status bits for network devices come from the hrPrinterDetectedErrorState property that is defined in the SNMP Printer MIB v2 (RFC 3805).

This function returns a pappl_preason_t bitfield which can be passed to the papplPrinterSetReasons function. Use the PAPPL_PREASON_DEVICE_STATUS value as the value of the "remove" argument.

Note: This function can block for several seconds while getting the status information.

papplDeviceIsSupported

Determine whether a given URI is supported.

bool papplDeviceIsSupported(const char *uri);

Parameters

uri URI

Return Value

true if supported, false otherwise

Discussion

This function determines whether a given URI or URI scheme is supported as a device.

papplDeviceList

List available devices.

bool papplDeviceList(pappl_devtype_t types, pappl_device_cb_t cb, void *data, pappl_deverror_cb_t err_cb, void *err_data);

Parameters

types Device types
cb Callback function
data User data for callback
err_cb Error callback or NULL for default
err_data Data for error callback

Return Value

true if the callback returned true, false otherwise

Discussion

This function lists the available devices, calling the "cb" function once per device that is discovered/listed. The callback function receives the device URI, IEEE-1284 device ID (if any), and "data" pointer, and returns true to stop listing devices and false to continue.

The "types" argument determines which devices are listed, for example PAPPL_DEVTYPE_ALL will list all types of devices while PAPPL_DEVTYPE_USB only lists USB printers.

Any errors are reported using the supplied "err_cb" function. If you specify NULL for this argument, errors are sent to stderr.

Note: This function will block (not return) until each of the device URI schemes has reported all of the devices or the supplied callback function returns true.

papplDeviceOpen

Open a connection to a device.

pappl_device_t *papplDeviceOpen(const char *device_uri, const char *name, pappl_deverror_cb_t err_cb, void *err_data);

Parameters

device_uri Device URI
name Job name
err_cb Error callback or NULL for default
err_data Data for error callback

Return Value

Device connection or NULL on error

Discussion

This function opens a connection to the specified device URI. The "name" argument provides textual context for the connection and is usually the name (title) of the print job.

Any errors are reported using the supplied "err_cb" function. If you specify NULL for this argument, errors are sent to stderr.

papplDeviceParseID

Parse an IEEE-1284 device ID string.

int papplDeviceParseID(const char *device_id, cups_option_t **pairs);

Parameters

device_id IEEE-1284 device ID string
pairs Key/value pairs

Return Value

Number of key/value pairs

Discussion

This function parses an IEEE-1284 device ID string and returns an array of key/value pairs as a cups_option_t array. The returned array must be freed using the cupsFreeOptions function.

papplDevicePrintf

Write a formatted string.

ssize_t papplDevicePrintf(pappl_device_t *device, const char *format, ...);

Parameters

device Device
format Printf-style format string
... Additional args as needed

Return Value

Number of characters or -1 on error

Discussion

This function buffers a formatted string that will be sent to the device. The "format" argument accepts all printf format specifiers and behaves identically to that function.

Call the papplDeviceFlush function to ensure that the formatted string is immediately sent to the device.

papplDevicePuts

Write a literal string.

ssize_t papplDevicePuts(pappl_device_t *device, const char *s);

Parameters

device Device
s Literal string

Return Value

Number of characters or -1 on error

Discussion

This function buffers a literal string that will be sent to the device. Call the papplDeviceFlush function to ensure that the literal string is immediately sent to the device.

papplDeviceRead

Read from a device.

ssize_t papplDeviceRead(pappl_device_t *device, void *buffer, size_t bytes);

Parameters

device Device
buffer Read buffer
bytes Max bytes to read

Return Value

Number of bytes read or -1 on error

Discussion

This function reads data from the device. Depending on the device, this function may block indefinitely.

papplDeviceSetData

Set device-specific data.

void papplDeviceSetData(pappl_device_t *device, void *data);

Parameters

device Device
data Device data pointer

Discussion

This function sets any device-specific data needed to communicate with the device. It is normally only called from the open callback that was registered for the device URI scheme.

papplDeviceWrite

Write to a device.

ssize_t papplDeviceWrite(pappl_device_t *device, const void *buffer, size_t bytes);

Parameters

device Device
buffer Write buffer
bytes Number of bytes to write

Return Value

Number of bytes written or -1 on error

Discussion

This function buffers data that will be sent to the device. Call the papplDeviceFlush function to ensure that the data is immediately sent to the device.

papplJobCancel

Cancel a job.

void papplJobCancel(pappl_job_t *job);

Parameters

job Job

Discussion

This function cancels the specified job. If the 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.

papplJobCreatePrintOptions

Create the printer options for a job.

pappl_pr_options_t *papplJobCreatePrintOptions(pappl_job_t *job, unsigned num_pages, bool color);

Parameters

job Job
num_pages Number of pages (0 for unknown)
color Is the document in color?

Return Value

Job options data or NULL on error

Discussion

This function allocates a printer options structure and computes the print options for a job based upon the Job Template attributes submitted in the print request and the default values set in the printer driver data.

The "num_pages" and "color" arguments specify the number of pages and whether the document contains non-grayscale colors - this information typically comes from parsing the job file.

papplJobDeletePrintOptions

Delete a job options structure.

void papplJobDeletePrintOptions(pappl_pr_options_t *options);

Parameters

options Options

Discussion

This function frees the memory used for a job options structure.

papplJobFilterImage

Filter an image in memory.

bool papplJobFilterImage(pappl_job_t *job, pappl_device_t *device, pappl_pr_options_t *options, const unsigned char *pixels, int width, int height, int depth, int ppi, bool smoothing);

Parameters

job Job
device Device
options Print options
pixels Pointer to the top-left corner of the image data
width Width in columns
height Height in lines
depth Bytes per pixel (1 for grayscale or 3 for sRGB)
ppi Pixels per inch (0 for unknown)
smoothing true to smooth/interpolate the image, false for nearest-neighbor sampling

Return Value

true on success, false otherwise

Discussion

This function will print a grayscale or sRGB image using the printer's raster driver interface, scaling and positioning the image as necessary based on the job options, and printing as many copies as requested.

The image data is an array of grayscale ("depth" = 1) or sRGB ("depth" = 3) pixels starting at the top-left corner of the image.

The image resolution ("ppi") is expressed in pixels per inch and is used for some "print-scaling" modes. Pass 0 if the image has no explicit resolution information.

papplJobGetAttribute

Get an attribute from a job.

ipp_attribute_t *papplJobGetAttribute(pappl_job_t *job, const char *name);

Parameters

job Job
name Attribute name

Return Value

Attribute or NULL if not found

Discussion

This function gets the named IPP attribute from a job. The returned attribute can be examined using the ippGetXxx functions.

papplJobGetData

Get per-job driver data.

void *papplJobGetData(pappl_job_t *job);

Parameters

job Job

Return Value

Per-job driver data or NULL if none

Discussion

This function returns the driver data associated with the job. It is normally only called from drivers to maintain state for the processing of the job, for example to store bitmap compression information.

papplJobGetFilename

Get the job's filename.

const char *papplJobGetFilename(pappl_job_t *job);

Parameters

job Job

Return Value

Filename or NULL if none

Discussion

This function returns the filename for the job's document data.

papplJobGetFormat

Get the MIME media type for the job's file.

const char *papplJobGetFormat(pappl_job_t *job);

Parameters

job Job

Return Value

MIME media type or NULL for none

Discussion

This function returns the MIME media type for the job's document data.

papplJobGetID

Get the job ID value.

int papplJobGetID(pappl_job_t *job);

Parameters

job Job

Return Value

Job ID or 0 for none

Discussion

This function returns the job's unique integer identifier.

papplJobGetImpressions

Get the number of impressions (sides) in the job.

int papplJobGetImpressions(pappl_job_t *job);

Parameters

job Job

Return Value

Number of impressions in job

Discussion

This function returns the number of impressions in the job's document data. An impression is one side of an output page.

papplJobGetImpressionsCompleted

Get the number of completed impressions (sides) in the job.

int papplJobGetImpressionsCompleted(pappl_job_t *job);

Parameters

job Job

Return Value

Number of completed impressions in job

Discussion

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

papplJobGetMessage

Get the current job message string, if any.

const char *papplJobGetMessage(pappl_job_t *job);

Parameters

job Job

Return Value

Current "job-state-message" value or NULL for none

Discussion

This function returns the current job message string, if any.

papplJobGetName

Get the job name/title.

const char *papplJobGetName(pappl_job_t *job);

Parameters

job Job

Return Value

Job name/title or NULL for none

Discussion

This function returns the name or title of the job.

papplJobGetPrinter

Get the printer for the job.

pappl_printer_t *papplJobGetPrinter(pappl_job_t *job);

Parameters

job Job

Return Value

Printer

Discussion

This function returns the printer containing the job.

papplJobGetReasons

Get the current job state reasons.

pappl_jreason_t papplJobGetReasons(pappl_job_t *job);

Parameters

job Job

Return Value

IPP "job-state-reasons" bits

Discussion

This function returns the current job state reasons bitfield.

papplJobGetState

Get the current job state.

ipp_jstate_t papplJobGetState(pappl_job_t *job);

Parameters

job Job

Return Value

IPP "job-state" value

Discussion

This function returns the current job processing state, which is represented as an enumeration:

papplJobGetTimeCompleted

Get the job completion time, if any.

time_t papplJobGetTimeCompleted(pappl_job_t *job);

Parameters

job Job

Return Value

Date/time when the job completed or 0 if not completed

Discussion

This function returns the date and time when the job reached the completed, canceled, or aborted states. 0 is returned if the job is not yet in one of those states.

papplJobGetTimeCreated

Get the job creation time.

time_t papplJobGetTimeCreated(pappl_job_t *job);

Parameters

job Job

Return Value

Date/time when the job was created

Discussion

This function returns the date and time when the job was created.

papplJobGetTimeProcessed

Get the job processing time.

time_t papplJobGetTimeProcessed(pappl_job_t *job);

Parameters

job Job

Return Value

Date/time when the job started processing (printing) or 0 if not yet processed

Discussion

This function returns the date and time when the job started processing (printing).

papplJobGetUsername

Get the name of the user that submitted the job.

const char *papplJobGetUsername(pappl_job_t *job);

Parameters

job Job

Return Value

Username or NULL for unknown

Discussion

This function returns the name of the user that submitted the job.

papplJobIsCanceled

Return whether the job is canceled.

bool papplJobIsCanceled(pappl_job_t *job);

Parameters

job Job

Return Value

true if the job is canceled or aborted, false otherwise

Discussion

This function returns true if the job has been canceled or aborted.

papplJobOpenFile

Create or open a file for the document in a job.

int papplJobOpenFile(pappl_job_t *job, char *fname, size_t fnamesize, const char *directory, const char *ext, const char *mode);

Parameters

job Job
fname Filename buffer
fnamesize Size of filename buffer
directory Directory to store in (NULL for default)
ext Extension (NULL for default)
mode Open mode - "r" for reading or "w" for writing

Return Value

File descriptor or -1 on error

Discussion

This function creates or opens a file for a job. The "fname" and "fnamesize" arguments specify the location and size of a buffer to store the job filename, which incorporates the "directory", printer ID, job ID, job name (title), and "ext" values. The job name is "sanitized" to only contain alphanumeric characters.

The "mode" argument is "r" to read an existing job file or "w" to write a new job file. New files are created with restricted permissions for security purposes.

papplJobSetData

Set the per-job driver data pointer.

void papplJobSetData(pappl_job_t *job, void *data);

Parameters

job Job
data Data pointer

Discussion

This function sets the driver data for the specified job. It is normally only called from drivers to maintain state for the processing of the job, for example to store bitmap compression information.

papplJobSetImpressions

Set the number of impressions (sides) in a job.

void papplJobSetImpressions(pappl_job_t *job, int impressions);

Parameters

job Job
impressions Number of impressions/sides

Discussion

This function sets the number of impressions in a job. An impression is one side of an output page.

papplJobSetImpressionsCompleted

Add completed impressions (sides) to the job.

void papplJobSetImpressionsCompleted(pappl_job_t *job, int add);

Parameters

job Job
add Number of impressions/sides to add

Discussion

This function updates the number of completed impressions in a job. An impression is one side of an output page.

papplJobSetMessage

Set the job message string.

void papplJobSetMessage(pappl_job_t *job, const char *message, ...);

Parameters

job Job
message Printf-style message string
... Additional arguments as needed

Discussion

This function sets the job message string using a printf-style format string.

Note: The maximum length of the job message string is 1023 bytes.

papplJobSetReasons

Set the job state reasons bit values.

void papplJobSetReasons(pappl_job_t *job, pappl_jreason_t add, pappl_jreason_t remove);

Parameters

job Job
add IPP "job-state-reasons" bit value(s) to add
remove IPP "job-state-reasons" bit value(s) to remove

Discussion

This function updates the job state reasons bitfield. The "remove" bits are cleared first, then the "add" bits are set.

papplLog

Log a message for the system.

void papplLog(pappl_system_t *system, pappl_loglevel_t level, const char *message, ...);

Parameters

system System
level Log level
message Printf-style message string
... Additional arguments as needed

Discussion

This function sends a message to the system's log file. The "level" argument specifies the urgency of the message:

The "message" argument specifies a printf-style format string. Values logged using the "%c" and "%s" format specifiers are sanitized to not contain control characters.

papplLogClient

Log a message for a client.

void papplLogClient(pappl_client_t *client, pappl_loglevel_t level, const char *message, ...);

Parameters

client Client
level Log level
message Printf-style message string
... Additional arguments as needed

Discussion

This function sends a client message to the system's log file. The "level" argument specifies the urgency of the message:

The "message" argument specifies a printf-style format string. Values logged using the "%c" and "%s" format specifiers are sanitized to not contain control characters.

papplLogDevice

Log a device error for the system...

void papplLogDevice(const char *message, void *data);

Parameters

message Message
data System

Discussion

This function sends a device error message to the system's log file.

papplLogJob

Log a message for a job.

void papplLogJob(pappl_job_t *job, pappl_loglevel_t level, const char *message, ...);

Parameters

job Job
level Log level
message Printf-style message string
... Additional arguments as needed

Discussion

This function sends a job message to the system's log file. The "level" argument specifies the urgency of the message:

The "message" argument specifies a printf-style format string. Values logged using the "%c" and "%s" format specifiers are sanitized to not contain control characters.

papplLogPrinter

Log a message for a printer.

void papplLogPrinter(pappl_printer_t *printer, pappl_loglevel_t level, const char *message, ...);

Parameters

printer Printer
level Log level
message Printf-style message string
... Additional arguments as needed

Discussion

This function sends a printer message to the system's log file. The "level" argument specifies the urgency of the message:

The "message" argument specifies a printf-style format string. Values logged using the "%c" and "%s" format specifiers are sanitized to not contain control characters.

papplMainloop

Run a standard main loop for printer applications.

int papplMainloop(int argc, char *argv[], const char *version, const char *footer_html, int num_drivers, pappl_pr_driver_t *drivers, pappl_pr_autoadd_cb_t autoadd_cb, pappl_pr_driver_cb_t driver_cb, const char *subcmd_name, pappl_ml_subcmd_cb_t subcmd_cb, pappl_ml_system_cb_t system_cb, pappl_ml_usage_cb_t usage_cb, void *data);

Parameters

argc Number of command line arguments
argv[] Command line arguments
version Version number
footer_html Footer HTML or NULL for none
num_drivers Number of drivers
drivers Drivers
autoadd_cb Auto-add callback or NULL for none
driver_cb Driver callback
subcmd_name Sub-command name or NULL for none
subcmd_cb Sub-command callback or NULL for none
system_cb System callback or NULL for default
usage_cb Usage callback or NULL for default
data Context pointer

Return Value

Exit status

Discussion

This function runs a standard main loop for a printer application. The "argc" and "argv" arguments are those provided to the main function.

The "version" argument specifies a numeric version number for the printer application that conforms to semantic versioning guidelines with up to four numbers, for example "1.2.3.4".

The "footer_html" argument specifies HTML text to use in the footer of the web interface. If NULL, the footer is omitted.

The "num_drivers", "drivers", and "driver_cb" arguments specify a list of drivers and the driver callback for printers. Specify 0 and NULL if the drivers are configured in the system callback. The "autoadd_cb" argument specifies a callback for automatically adding new printers with the "autoadd" sub-command and for auto-detecting the driver when adding manually.

The "usage_cb" argument specifies a callback that displays a usage/help summary. If NULL, a generic summary is shown as needed.

The "subcmd_name" and "subcmd_cb" arguments specify the name and a callback for a custom sub-command. If NULL, no custom sub-commands will be supported.

The "system_cb" argument specifies a function that will create a new pappl_system_t object. If NULL, a default system object is created.

The "data" argument provides application-specific data for each of the callbacks.

papplPrinterAddLink

Add a printer link to the navigation header.

void papplPrinterAddLink(pappl_printer_t *printer, const char *label, const char *path_or_url, pappl_loptions_t options);

Parameters

printer Printer
label Label string
path_or_url Path or URL
options Link options

Discussion

This function adds a navigation link for a printer. The "path_or_url" argument specifies a absolute path such as "/ipp/print/example/page" or an absolute URL such as "https://www.example.com/". The "options" argument specifies where the link is shown and whether the link should redirect an absolute path to the secure ("https://.../path") web interface.

papplPrinterCancelAllJobs

Cancel all jobs on the printer.

void papplPrinterCancelAllJobs(pappl_printer_t *printer);

Parameters

printer Printer

Discussion

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

Parameters

printer Printer

Discussion

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

Parameters

system System
printer_id printer-id value or 0 for new
printer_name Human-readable printer name
driver_name Driver name
device_id IEEE-1284 device ID
device_uri Device URI

Return Value

Printer or NULL on error

Discussion

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:

papplPrinterDelete

Delete a printer.

void papplPrinterDelete(pappl_printer_t *printer);

Parameters

printer Printer

Discussion

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

papplPrinterFindJob

Find a job.

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

Parameters

printer Printer
job_id Job ID

Return Value

Job or NULL if not found

Discussion

This function finds a job submitted to a printer using its integer ID value.

papplPrinterGetContact

Get the "printer-contact" value.

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

Parameters

printer Printer
contact Contact

Return Value

Contact

Discussion

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

Parameters

printer Printer
buffer String buffer
bufsize Size of string buffer

Return Value

DNS-SD service name or NULL for none

Discussion

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

Parameters

printer Printer

Return Value

IEEE-1284 device ID string

Discussion

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

Parameters

printer Printer

Return Value

Device URI string

Discussion

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

Parameters

printer Printer

Return Value

Copy of driver attributes

Discussion

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

Parameters

printer Printer
data Pointer to driver data structure to fill

Return Value

Driver data or NULL if none

Discussion

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

Parameters

printer Printer

Return Value

Driver name or NULL for none

Discussion

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

Parameters

printer Printer
buffer String buffer
bufsize Size of string buffer

Return Value

"geo:" URI or NULL for unknown

Discussion

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

Parameters

printer Printer

Return Value

"printer-id" value or 0 for none

Discussion

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

Parameters

printer Printer

Return Value

Number of printed impressions/sides

Discussion

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

Parameters

printer Printer
buffer String buffer
bufsize Size of string buffer

Return Value

Location or NULL for none

Discussion

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

Parameters

printer Printer

Return Value

Maximum number of active jobs

Discussion

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

Parameters

printer Printer

Return Value

Maximum number of completed jobs

Discussion

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

Parameters

printer Printer

Return Value

Printer name

Discussion

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

papplPrinterGetNextJobID

Get the next job ID.

int papplPrinterGetNextJobID(pappl_printer_t *printer);

Parameters

printer Printer

Return Value

Next job ID or 0 for none

Discussion

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

Parameters

printer Printer

Return Value

Number of active print jobs

Discussion

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

Parameters

printer Printer

Return Value

Number of completed print jobs

Discussion

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

Parameters

printer Printer

Return Value

Total number of print jobs

Discussion

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

Parameters

printer Printer
buffer String buffer
bufsize Size of string buffer

Return Value

Organization name or NULL for none

Discussion

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

Parameters

printer Printer
buffer String buffer
bufsize Size of string buffer

Return Value

Organizational unit name or NULL for none

Discussion

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

Parameters

printer Printer
subpath Sub-path or NULL for none
buffer String buffer
bufsize Size of string buffer

Return Value

URI path or NULL on error

Discussion

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

Parameters

printer Printer
buffer String buffer
bufsize Size of string buffer

Return Value

Print authorization group name or NULL for none

Discussion

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

Parameters

printer Printer

Return Value

"printer-state-reasons" bit values

Discussion

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

Parameters

printer Printer

Return Value

"printer-state" value

Discussion

This function returns the current printer state as an enumeration:

papplPrinterGetSupplies

Get the current "printer-supplies" values.

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

Parameters

printer Printer
max_supplies Maximum number of supplies
supplies Array for supplies

Return Value

Number of values

Discussion

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

Parameters

printer Printer

Return Value

System

Discussion

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

Parameters

printer Printer
cb Callback function
data Callback data
job_index First job to iterate (1-based)
limit Maximum jobs to iterate or 0 for no limit

Discussion

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

Parameters

printer Printer
cb Callback function
data Callback data
job_index First job to iterate (1-based)
limit Maximum jobs to iterate, 0 for no limit

Discussion

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

Parameters

printer Printer
cb Callback function
data Callback data
job_index First job to iterate (1-based)
limit Maximum jobs to iterate, 0 for no limit

Discussion

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

Parameters

printer Printer

Return Value

Device or NULL if not possible

Discussion

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

Parameters

printer Printer

Discussion

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

papplPrinterRemoveLink

Remove a printer link from the navigation header.

void papplPrinterRemoveLink(pappl_printer_t *printer, const char *label);

Parameters

printer Printer
label Label string

Discussion

This function removes the named link for the printer.

papplPrinterResume

Resume (start) a printer.

void papplPrinterResume(pappl_printer_t *printer);

Parameters

printer Printer

Discussion

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

Parameters

printer Printer
contact Contact

Discussion

This function sets the printer's contact information.

papplPrinterSetDNSSDName

Set the DNS-SD service name.

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

Parameters

printer Printer
value DNS-SD service name or NULL for none

Discussion

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

Parameters

printer Printer
data Driver data
attrs Additional capability attributes or NULL for none

Return Value

true on success, false on failure

Discussion

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

Note: This function regenerates all of the driver-specific capability attributes like "media-col-database", "sides-supported", and so forth. Use the papplPrinterSetDriverDefaults or papplPrinterSetReadyMedia functions to efficiently change the "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);

Parameters

printer Printer
data Driver data
num_vendor Number of vendor options
vendor Vendor options

Return Value

true on success or false on failure

Discussion

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

Note: Unlike papplPrinterSetPrintDriverData, this function only changes the "xxx_default" members of the driver data and is considered lightweight.

papplPrinterSetGeoLocation

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

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

Parameters

printer Printer
value "geo:" URI or NULL for unknown

Discussion

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

Parameters

printer Printer
add Number of impressions/sides to add

Discussion

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

Parameters

printer Printer
value Location ("Bob's Office", etc.) or NULL for none

Discussion

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

Parameters

printer Printer
max_active_jobs Maximum number of active jobs, 0 for unlimited

Discussion

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

Note: This limit does not apply to streaming raster formats such as PWG 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);

Parameters

printer Printer
max_completed_jobs Maximum number of completed jobs, 0 for unlimited

Discussion

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

Parameters

printer Printer
next_job_id Next "job-id" value

Discussion

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

Note: This function is normally only called once to restore the previous state of the printer.

papplPrinterSetOrganization

Set the organization name.

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

Parameters

printer Printer
value Organization name or NULL for none

Discussion

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

Parameters

printer Printer
value Organizational unit name or NULL for none

Discussion

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

Parameters

printer Printer
value Print authorization group or NULL for none

Discussion

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

Note: The authorization group is only used if the system is created with a named authorization service.

papplPrinterSetReadyMedia

Set the ready (loaded) media.

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

Parameters

printer Printer
num_ready Number of ready media
ready Array of ready media

Return Value

true on success or false on failure

Discussion

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

Parameters

printer Printer
add "printer-state-reasons" bit values to add or PAPPL_PREASON_NONE for none
remove "printer-state-reasons" bit values to remove or PAPPL_PREASON_NONE for none

Discussion

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

Parameters

printer Printer
num_supplies Number of supplies
supplies Array of supplies

Discussion

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

Parameters

printer Printer
vendor_id USB vendor ID
product_id USB product ID
options USB gadget options
storagefile USB storage file, if any

Discussion

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.

Note: USB gadget functionality is currently only available when running on Linux with compatible hardware such as the Raspberry Pi.

papplSystemAddLink

Add a link to the navigation header.

void papplSystemAddLink(pappl_system_t *system, const char *label, const char *path_or_url, pappl_loptions_t options);

Parameters

system System
label Label string
path_or_url Path or URL
options Link options

Discussion

This function adds a navigation link for the system. The "path_or_url" argument specifies a absolute path such as "/page" or an absolute URL such as "https://www.example.com/". The "options" argument specifies where the link is shown and whether the link should redirect an absolute path to the secure ("https://.../path") web interface.

papplSystemAddListeners

Add network or domain socket listeners.

bool papplSystemAddListeners(pappl_system_t *system, const char *name);

Parameters

system System
name Hostname, domain socket filename, or NULL

Return Value

true on success, false on failure

Discussion

This function adds socket listeners. The "name" parameter specifies the listener address. Names starting with a slash (/) specify a UNIX domain socket path, otherwise the name is treated as a fully-qualified domain name or numeric IPv4 or IPv6 address. If name is NULL, the "any" addresses are used ("0.0.0.0" and "[::]").

Listeners cannot be added after papplSystemRun is called.

papplSystemAddMIMEFilter

Add a file filter to the system.

void papplSystemAddMIMEFilter(pappl_system_t *system, const char *srctype, const char *dsttype, pappl_mime_filter_cb_t cb, void *data);

Parameters

system System
srctype Source MIME media type (constant) string
dsttype Destination MIME media type (constant) string
cb Filter callback function
data Filter callback data

Discussion

This function adds a file filter to the system to be used for processing different kinds of document data in print jobs. The "srctype" and "dsttype" arguments specify the source and destination MIME media types as constant strings. A destination MIME media type of "image/pwg-raster" specifies a filter that uses the driver's raster interface. Other destination types imply direct submission to the output device using the papplDeviceXxx functions.

Note: This function may not be called while the system is running.

papplSystemAddResourceCallback

Add a dynamic resource that uses a callback function.

void papplSystemAddResourceCallback(pappl_system_t *system, const char *path, const char *format, pappl_resource_cb_t cb, void *data);

Parameters

system System object
path Resource path
format MIME media type for content such as "text/html"
cb Callback function
data Callback data

Discussion

This function adds a dynamic resource at the specified path. When a client GET or POST request is received at the specified path, the "cb" function will be called with the client pointer and "data" pointer to respond to it.

Resource callbacks are most often used to implement custom web pages.

Note: Any custom web page that is added prior to calling the papplSystemRun function will replace the corresponding standard web page at the same path.

papplSystemAddResourceData

Add a static data resource.

void papplSystemAddResourceData(pappl_system_t *system, const char *path, const char *format, const void *data, size_t datalen);

Parameters

system System object
path Resource path
format MIME media type such as "image/png"
data Resource data
datalen Size of resource data

Discussion

This function adds a static resource at the specified path. The provided data is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

papplSystemAddResourceDirectory

Add external files in a directory as resources.

void papplSystemAddResourceDirectory(pappl_system_t *system, const char *basepath, const char *directory);

Parameters

system System object
basepath Base resource path
directory Directory containing resource files

Discussion

This function adds static resources from the specified directory under the specified path. The directory is scanned and only those files present at the time of the call are available, and those files must remain stable for as long as the resources are added to the system..

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

papplSystemAddResourceFile

Add an external file as a resource.

void papplSystemAddResourceFile(pappl_system_t *system, const char *path, const char *format, const char *filename);

Parameters

system System object
path Resource path
format MIME media type such as "image/png"
filename Filename

Discussion

This function adds a static resource at the specified path. The provided file is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

papplSystemAddResourceString

Add a static data resource as a C string.

void papplSystemAddResourceString(pappl_system_t *system, const char *path, const char *format, const char *data);

Parameters

system System object
path Resource path
format MIME media type such as "image/png"
data Resource data

Discussion

This function adds a static resource at the specified path. The provided data is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

papplSystemAddStringsData

Add a static localization file resource.

void papplSystemAddStringsData(pappl_system_t *system, const char *path, const char *language, const char *data);

Parameters

system System object
path Resource path
language ISO language tag such as "en-US", "fr-CA", etc.
data Nul-terminated string containing strings file data

Discussion

This function adds a static localization resource at the specified path. Localization files use the NeXTStep strings ("text/strings") format defined in PWG Candidate Standard 5100.13-2013. The provided data is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

papplSystemAddStringsFile

Add an external localization file resource.

void papplSystemAddStringsFile(pappl_system_t *system, const char *path, const char *language, const char *filename);

Parameters

system System object
path Resource path
language ISO language tag such as "en-US", "fr-CA", etc.
filename Filename

Discussion

This function adds a static localization resource at the specified path. Localization files use the NeXTStep strings ("text/strings") format defined in PWG Candidate Standard 5100.13-2013. The provided file is not copied to the resource and must remain stable for as long as the resource is added to the system.

Note: Any resource that is added prior to calling the papplSystemRun function will replace the corresponding standard resource at the same path.

papplSystemCleanJobs

Clean out old (completed) jobs.

void papplSystemCleanJobs(pappl_system_t *system);

Parameters

system System

Discussion

This function deletes all old (completed) jobs above the limit set by the papplPrinterSetMaxCompletedJobs function. The level may temporarily exceed this limit if the jobs were completed within the last 60 seconds.

Note: This function is normally called automatically from the papplSystemRun function.

papplSystemCreate

Create a system object.

pappl_system_t *papplSystemCreate(pappl_soptions_t options, const char *name, int port, const char *subtypes, const char *spooldir, const char *logfile, pappl_loglevel_t loglevel, const char *auth_service, bool tls_only);

Parameters

options Server options
name System name
port Port number or 0 for auto
subtypes DNS-SD sub-types or NULL for none
spooldir Spool directory or NULL for default
logfile Log file or NULL for default
loglevel Log level
auth_service PAM authentication service or NULL for none
tls_only Only support TLS connections?

Return Value

System object

Discussion

This function creates a new system object, which is responsible for managing all the printers, jobs, and resources used by the printer application.

The "options" argument specifies which options are enabled for the server:

The "name" argument specifies a human-readable name for the system.

The "port" argument specifies the port number to bind to. A value of 0 will cause an available port number to be assigned when the first listener is added with the papplSystemAddListeners function.

The "subtypes" argument specifies one or more comma-delimited DNS-SD service sub-types such as "_print" and "_universal".

The "spooldir" argument specifies the location of job files. If NULL, a temporary directory is created.

The "logfile" argument specifies where to send log messages. If NULL, the log messages are written to a temporary file.

The "loglevel" argument specifies the initial logging level.

The "auth_service" argument specifies a PAM authentication service name. If NULL, no user authentication will be provided.

The "tls_only" argument controls whether the printer application will accept unencrypted connections. In general, this argument should always be false (allow unencrypted connections) since not all clients support encrypted printing.

papplSystemDelete

Delete a system object.

void papplSystemDelete(pappl_system_t *system);

Parameters

system System object

Discussion

Note: A system object cannot be deleted while the system is running.

papplSystemFindPrinter

Find a printer by resource, ID, or device URI.

pappl_printer_t *papplSystemFindPrinter(pappl_system_t *system, const char *resource, int printer_id, const char *device_uri);

Parameters

system System
resource Resource path or NULL
printer_id Printer ID or 0
device_uri Device URI or NULL

Return Value

Printer or NULL if none

Discussion

This function finds a printer contained in the system using its resource path, unique integer identifier, or device URI. If none of these is specified, the current default printer is returned.

papplSystemGetAdminGroup

Get the current administrative group, if any.

char *papplSystemGetAdminGroup(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Admin group or NULL if none

Discussion

This function copies the current administrative group, if any, to the specified buffer.

papplSystemGetAuthService

Get the PAM authorization service, if any.

const char *papplSystemGetAuthService(pappl_system_t *system);

Parameters

system System

Return Value

PAM authorization service or NULL if none

Discussion

This function returns the PAM authorization service being used by the system for authentication, if any.

papplSystemGetContact

Get the "system-contact" value.

pappl_contact_t *papplSystemGetContact(pappl_system_t *system, pappl_contact_t *contact);

Parameters

system System
contact Contact

Return Value

Contact

Discussion

This function copies the current system contact information to the specified buffer.

papplSystemGetDNSSDName

Get the current DNS-SD service name.

char *papplSystemGetDNSSDName(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Current DNS-SD service name or NULL for none

Discussion

This function copies the current DNS-SD service name of the system, if any, to the specified buffer.

papplSystemGetDefaultPrintGroup

Get the default print group, if any.

char *papplSystemGetDefaultPrintGroup(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Default print group or NULL if none

Discussion

This function copies the current default print group, if any, to the specified buffer.

papplSystemGetDefaultPrinterID

Get the current "default-printer-id" value.

int papplSystemGetDefaultPrinterID(pappl_system_t *system);

Parameters

system System

Return Value

"default-printer-id" value

Discussion

This function returns the positive integer identifier for the current default printer or 0 if there is no default printer.

papplSystemGetFooterHTML

Get the footer HTML for the web interface, if any.

const char *papplSystemGetFooterHTML(pappl_system_t *system);

Parameters

system System

Return Value

Footer HTML or NULL if none

Discussion

This function returns the HTML for the web page footer, if any. The footer HTML can be set using the papplSystemSetFooterHTML function.

papplSystemGetGeoLocation

Get the system geo-location string, if any.

char *papplSystemGetGeoLocation(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

"geo:" URI or NULL for none

Discussion

This function copies the current system geographic location as a "geo:" URI to the specified buffer.

papplSystemGetHostname

Get the system hostname.

char *papplSystemGetHostname(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Hostname

Discussion

This function copies the current system hostname to the specified buffer.

papplSystemGetLocation

Get the system location string, if any.

char *papplSystemGetLocation(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Location string or NULL for none

Discussion

This function copies the current human-readable location, if any, to the specified buffer.

papplSystemGetLogLevel

pappl_loglevel_t papplSystemGetLogLevel(pappl_system_t *system);

Parameters

system System

Return Value

Get the system log level.

This function returns the current system log level as an enumeration.

papplSystemGetMaxLogSize

Get the maximum log file size.

size_t papplSystemGetMaxLogSize(pappl_system_t *system);

Parameters

system System

Return Value

Maximum log file size or 0 for none

Discussion

This function gets the maximum log file size, which is only used when logging directly to a file. When the limit is reached, the current log file is renamed to "filename.O" and a new log file is created. Set the maximum size to 0 to disable log file rotation.

The default maximum log file size is 1MiB or 1048576 bytes.

papplSystemGetName

Get the system name.

char *papplSystemGetName(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Name string

Discussion

This function copies the current system name to the specified buffer.

papplSystemGetNextPrinterID

Get the next "printer-id" value.

int papplSystemGetNextPrinterID(pappl_system_t *system);

Parameters

system System

Return Value

Next "printer-id" value

Discussion

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

papplSystemGetOptions

Get the system options.

pappl_soptions_t papplSystemGetOptions(pappl_system_t *system);

Parameters

system System

Return Value

System options

Discussion

This function returns the system options as a bitfield.

papplSystemGetOrganization

Get the system organization string, if any.

char *papplSystemGetOrganization(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Organization string or NULL for none

Discussion

This function copies the current organization name, if any, to the specified buffer.

papplSystemGetOrganizationalUnit

Get the system organizational unit string, if any.

char *papplSystemGetOrganizationalUnit(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Organizational unit string or NULL for none

Discussion

This function copies the current organizational unit name, if any, to the specified buffer.

papplSystemGetPassword

Get the current web site access password.

char *papplSystemGetPassword(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Password hash

Discussion

This function copies the current web site password hash, if any, to the specified buffer.

Note: The access password is only used when the PAM authentication service is not set.

papplSystemGetPort

Get the port number for network connections to the system.

int papplSystemGetPort(pappl_system_t *system);

Parameters

system System

Return Value

Port number

Discussion

This function returns the port number that is used for network connections to the system.

papplSystemGetServerHeader

Get the Server: header for HTTP responses.

const char *papplSystemGetServerHeader(pappl_system_t *system);

Parameters

system System

Return Value

Server: header string or NULL for none

Discussion

This function returns the value of the HTTP "Server:" header that is used by the system.

papplSystemGetSessionKey

Get the current session key.

char *papplSystemGetSessionKey(pappl_system_t *system, char *buffer, size_t bufsize);

Parameters

system System
buffer String buffer
bufsize Size of string buffer

Return Value

Session key

Discussion

This function copies the current session key to the specified buffer. The session key is used for web interface forms to provide CSRF protection and is refreshed periodically.

papplSystemGetTLSOnly

Get the TLS-only state of the system.

bool papplSystemGetTLSOnly(pappl_system_t *system);

Parameters

system System

Return Value

true if the system is only accepting TLS encrypted connections, false otherwise

Discussion

This function returns whether the system will only accept encrypted connections.

papplSystemGetUUID

Get the "system-uuid" value.

const char *papplSystemGetUUID(pappl_system_t *system);

Parameters

system System

Return Value

"system-uuid" value

Discussion

This function returns the system's UUID value.

papplSystemGetVersions

Get the firmware names and versions.

int papplSystemGetVersions(pappl_system_t *system, int max_versions, pappl_version_t *versions);

Parameters

system System
max_versions Maximum number of versions to return
versions Versions array or NULL for don't care

Return Value

Number of firmware versions

Discussion

This function copies the system firmware information to the specified buffer. The return value is always the number of firmware versions that have been set using the papplSystemSetVersions function, regardless of the value of the "max_versions" argument.

papplSystemHashPassword

Generate a password hash using salt and password strings.

char *papplSystemHashPassword(pappl_system_t *system, const char *salt, const char *password, char *buffer, size_t bufsize);

Parameters

system System
salt Existing password hash or NULL to generate a new hash
password Plain-text password string
buffer String buffer
bufsize Size of string buffer

Return Value

Hashed password

Discussion

This function generates a password hash using the "salt" and "password" strings. The "salt" string should be NULL to generate a new password hash or the value of an existing password hash to verify that a given plaintext "password" string matches the password hash.

Note: Hashed access passwords are only used when the PAM authentication service is not set.

papplSystemIsRunning

Return whether the system is running.

bool papplSystemIsRunning(pappl_system_t *system);

Parameters

system System

Return Value

true if the system is running, false otherwise

Discussion

This function returns whether the system is running.

papplSystemIsShutdown

Return whether the system has been shutdown.

bool papplSystemIsShutdown(pappl_system_t *system);

Parameters

system System

Return Value

true if the system is shutdown, false otherwise

Discussion

This function returns whether the system is shutdown or scheduled to shutdown.

papplSystemIteratePrinters

Iterate all of the printers.

void papplSystemIteratePrinters(pappl_system_t *system, pappl_printer_cb_t cb, void *data);

Parameters

system System
cb Callback function
data Callback data

Discussion

This function iterates each of the printers managed by the system. The "cb" function is called once per printer with the "system" and "data" values.

papplSystemLoadState

Load the previous system state.

bool papplSystemLoadState(pappl_system_t *system, const char *filename);

Parameters

system System
filename File to load

Return Value

true on success, false on failure

Discussion

This function loads the previous system state from a file created by the papplSystemSaveState function. The system state contains all of the system object values, the list of printers, and the jobs for each printer.

When loading a printer definition, if the printer cannot be created (e.g., because the driver name is no longer valid) then that printer and all of its job history will be lost. In the case of a bad driver name, a printer application's driver callback can perform any necessary mapping of the driver name, including the use its auto-add callback to find a compatible new driver.

Note: This function must be called prior to papplSystemRun.

papplSystemMatchDriver

const char *papplSystemMatchDriver(pappl_system_t *system, const char *device_id);

Parameters

system System
device_id IEEE-1284 device ID string

Return Value

Match a driver to an IEEE-1284 device ID.

papplSystemRemoveLink

Remove a link from the navigation header.

void papplSystemRemoveLink(pappl_system_t *system, const char *label);

Parameters

system System
label Label string

Discussion

This function removes the named link for the system.

papplSystemRemoveResource

Remove a resource at the specified path.

void papplSystemRemoveResource(pappl_system_t *system, const char *path);

Parameters

system System object
path Resource path

Discussion

This function removes a resource at the specified path.

papplSystemRun

Run the printer application.

void papplSystemRun(pappl_system_t *system);

Parameters

system System

Discussion

This function runs the printer application, accepting new connections, handling requests, and processing jobs as needed. It returns once the system is shutdown, either through an IPP request or SIGTERM.

papplSystemSaveState

Save the current system state.

bool papplSystemSaveState(pappl_system_t *system, const char *filename);

Parameters

system System
filename File to save

Return Value

true on success, false on failure

Discussion

This function saves the current system state to a file. It is typically used with the papplSystemSetSaveCallback function to periodically save the state: 

papplSystemSetSaveCallback(system, (pappl_save_cb_t)papplSystemSaveState,
    (void *)filename);
```
inter cannot be created (e.g., because the driver name is no longer valid) then that printer and all of its job history will be lost. In the case of a bad driver name, a printer application's driver callback can perform any necessary mapping of the driver name, including the use its auto-add callback to find a compatible new driver.

Note: This function must be called prior to papplSystemRun

papplSystemSetAdminGroup

Set the administrative group.

void papplSystemSetAdminGroup(pappl_system_t *system, const char *value);

Parameters

system System
value Admin group

Discussion

This function sets the group name used for administrative requests such as adding or deleting a printer.

Note: The administrative group is only used when the PAM authorization service is also set when the system is created.

papplSystemSetContact

Set the "system-contact" value.

void papplSystemSetContact(pappl_system_t *system, pappl_contact_t *contact);

Parameters

system System
contact Contact

Discussion

This function sets the system contact value.

papplSystemSetDNSSDName

Set the DNS-SD service name.

void papplSystemSetDNSSDName(pappl_system_t *system, const char *value);

Parameters

system System
value DNS-SD service name or NULL for none

Discussion

This function sets the DNS-SD service name of the system. If NULL, the DNS-SD registration is removed.

papplSystemSetDefaultPrintGroup

Set the default print group.

void papplSystemSetDefaultPrintGroup(pappl_system_t *system, const char *value);

Parameters

system System
value Default print group or NULL for none

Discussion

This function sets the default group name used for print requests.

Note: The default print group is only used when the PAM authorization service is also set when the system is created.

papplSystemSetDefaultPrinterID

Set the "default-printer-id" value.

void papplSystemSetDefaultPrinterID(pappl_system_t *system, int default_printer_id);

Parameters

system System
default_printer_id "default-printer-id" value

Discussion

This function sets the default printer using its unique positive integer identifier.

papplSystemSetFooterHTML

Set the footer HTML for the web interface.

void papplSystemSetFooterHTML(pappl_system_t *system, const char *html);

Parameters

system System
html Footer HTML or NULL for none

Discussion

This function sets the footer HTML for the web interface.

Note: The footer HTML can only be set prior to calling papplSystemRun.

papplSystemSetGeoLocation

Set the geographic location string.

void papplSystemSetGeoLocation(pappl_system_t *system, const char *value);

Parameters

system System
value "geo:" URI or NULL for none

Discussion

This function sets the geographic location of the system as a "geo:" URI. If NULL, the location is cleared.

papplSystemSetHostname

Set the system hostname.

void papplSystemSetHostname(pappl_system_t *system, const char *value);

Parameters

system System
value Hostname or NULL for default

Discussion

This function sets the system hostname. If NULL, the default hostname is used.

papplSystemSetLocation

Set the system location string, if any.

void papplSystemSetLocation(pappl_system_t *system, const char *value);

Parameters

system System
value Location or NULL for none

Discussion

This function sets the human-readable location of the system. If NULL, the location is cleared.

papplSystemSetLogLevel

Set the system log level

void papplSystemSetLogLevel(pappl_system_t *system, pappl_loglevel_t loglevel);

Parameters

system System
loglevel Log Level

Discussion

This function sets the log level as an enumeration.

papplSystemSetMIMECallback

Set the MIME typing callback for the system.

void papplSystemSetMIMECallback(pappl_system_t *system, pappl_mime_cb_t cb, void *data);

Parameters

system System
cb Callback function
data Callback data

Discussion

This function sets a custom MIME typing callback for the system. The MIME typing callback extends the built-in MIME typing support for other media types that are supported by the application, typically vendor print formats.

The callback function receives a buffer containing the initial bytes of the document data, the length of the buffer, and the callback data. It can then return NULL if the content is not recognized or a constant string containing the MIME media type, for example "application/vnd.hp-pcl" for HP PCL print data.

papplSystemSetMaxLogSize

Set the maximum log file size in bytes.

void papplSystemSetMaxLogSize(pappl_system_t *system, size_t maxsize);

Parameters

system System
maxsize Maximum log size in bytes or 0 for none

Discussion

This function sets the maximum log file size in bytes, which is only used when logging directly to a file. When the limit is reached, the current log file is renamed to "filename.O" and a new log file is created. Set the maximum size to 0 to disable log file rotation.

The default maximum log file size is 1MiB or 1048576 bytes.

papplSystemSetNextPrinterID

Set the next "printer-id" value.

void papplSystemSetNextPrinterID(pappl_system_t *system, int next_printer_id);

Parameters

system System
next_printer_id Next "printer-id" value

Discussion

This function sets the unique positive integer identifier that will be used for the next printer that is created. It is typically only called as part of restoring the state of a system.

Note: The next printer ID can only be set prior to calling papplSystemRun.

papplSystemSetOperationCallback

Set the IPP operation callback.

void papplSystemSetOperationCallback(pappl_system_t *system, pappl_ipp_op_cb_t cb, void *data);

Parameters

system System
cb Callback function
data Callback data

Discussion

This function sets a custom IPP operation handler for the system that is called for any IPP operations that are not handled by the built-in IPP services.

Note: The operation callback can only be set prior to calling papplSystemRun.

papplSystemSetOrganization

Set the system organization string, if any.

void papplSystemSetOrganization(pappl_system_t *system, const char *value);

Parameters

system System
value Organization or NULL for none

Discussion

This function sets the organization name for the system. If NULL, the name is cleared.

papplSystemSetOrganizationalUnit

Set the system organizational unit string, if any.

void papplSystemSetOrganizationalUnit(pappl_system_t *system, const char *value);

Parameters

system System
value Organizational unit or NULL for none

Discussion

This function sets the organizational unit name for the system. If NULL, the name is cleared.

papplSystemSetPassword

Set the access password hash string.

void papplSystemSetPassword(pappl_system_t *system, const char *hash);

Parameters

system System
hash Hash string

Discussion

This function sets the hash for the web access password. The hash string is generated using the papplSystemHashPassword function.

Note: The access password is only used when the PAM authentication service is not set.

papplSystemSetPrinterDrivers

Set the list of drivers and the driver callbacks.

void papplSystemSetPrinterDrivers(pappl_system_t *system, int num_drivers, pappl_pr_driver_t *drivers, pappl_pr_autoadd_cb_t autoadd_cb, pappl_pr_create_cb_t create_cb, pappl_pr_driver_cb_t driver_cb, void *data);

Parameters

system System
num_drivers Number of drivers
drivers Drivers
autoadd_cb Auto-add callback function or NULL if none
create_cb Printer creation callback function or NULL if none
driver_cb Driver initialization callback function
data Callback data

Discussion

This function sets the lists of printer drivers, the optional auto-add callback function, the optional creation callback, and the required driver initialization callback function.

The auto-add callback ("autoadd_cb") finds a compatible driver name for the specified printer. It is used when the client or user specifies the "auto" driver name, and for the "autoadd" sub-command for the papplMainloop API.

The creation callback ("create_cb") is called at the end of printer creation to make any common changes or additions to a new printer. It is typically used to add extra web pages, add per-printer static resources, and/or initialize the contact and location information.

The driver initialization callback ("driver_cb") is called to initialize the pappl_pr_driver_data_t structure, which provides all of the printer capabilities and callbacks for printing.

papplSystemSetSaveCallback

Set the save callback.

void papplSystemSetSaveCallback(pappl_system_t *system, pappl_save_cb_t cb, void *data);

Parameters

system System
cb Callback function
data Callback data

Discussion

This function sets a callback that is used to periodically save the current system state. Typically the callback function ("cb") is papplSystemSaveState and the callback data ("data") is the name of the state file: 

papplSystemSetSaveCallback(system, (pappl_save_cb_t)papplSystemSaveState,
    (void *)filename);

Note: The save callback can only be set prior to calling papplSystemRun.

papplSystemSetUUID

Set the system UUID.

void papplSystemSetUUID(pappl_system_t *system, const char *value);

Parameters

system System
value UUID

Discussion

This function sets the system UUID value, overriding the default (generated) value. It is typically used when restoring the state of a previous incarnation of the system.

Note: The UUID can only be set prior to calling papplSystemRun.

papplSystemSetVersions

Set the firmware names and versions.

void papplSystemSetVersions(pappl_system_t *system, int num_versions, pappl_version_t *versions);

Parameters

system System
num_versions Number of versions
versions Firmware versions

Discussion

This function sets the names and versions of each firmware/software component of the printer application.

papplSystemShutdown

Shutdown the system.

void papplSystemShutdown(pappl_system_t *system);

Parameters

system System

Discussion

This function tells the system to perform an orderly shutdown of all printers and to terminate the main loop.

Data Types

pappl_client_t

Client connection object

typedef struct _pappl_client_s pappl_client_t;

pappl_color_mode_t

Bitfield for IPP "print-color-mode" values

typedef unsigned pappl_color_mode_t;

pappl_contact_t

Contact information

typedef struct pappl_contact_s pappl_contact_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_devclose_cb_t

Device close callback

typedef void (*pappl_devclose_cb_t)(pappl_device_t *device);

pappl_deverror_cb_t

Device error callback

typedef void (*pappl_deverror_cb_t)(const char *message, void *err_data);

pappl_device_cb_t

Device callback - return true to stop, false to continue

typedef bool (*pappl_device_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);

pappl_device_t

Device connection object

typedef struct _pappl_device_s pappl_device_t;

pappl_devid_cb_t

Device ID callback

typedef char *(*pappl_devid_cb_t)(pappl_device_t *device, char *buffer, size_t bufsize);

pappl_devlist_cb_t

Device list callback

typedef bool (*pappl_devlist_cb_t)(pappl_device_cb_t cb, void *data, pappl_deverror_cb_t err_cb, void *err_data);

pappl_devmetrics_t

Device metrics

typedef struct pappl_devmetrics_s pappl_devmetrics_t;

pappl_devopen_cb_t

Device open callback

typedef bool (*pappl_devopen_cb_t)(pappl_device_t *device, const char *device_uri, const char *name);

pappl_devread_cb_t

Device read callback

typedef ssize_t (*pappl_devread_cb_t)(pappl_device_t *device, void *buffer, size_t bytes);

pappl_devstatus_cb_t

Device status callback

typedef pappl_preason_t (*pappl_devstatus_cb_t)(pappl_device_t *device);

pappl_devtype_t

Device type bitfield

typedef unsigned pappl_devtype_t;

pappl_devwrite_cb_t

Device write callback

typedef ssize_t (*pappl_devwrite_cb_t)(pappl_device_t *device, const void *buffer, size_t bytes);

pappl_dither_t[16][16]

16x16 dither array

typedef unsigned char pappl_dither_t[16][16];

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_ipp_op_cb_t

IPP operation callback function

typedef bool (*pappl_ipp_op_cb_t)(pappl_client_t *client, void *data);

pappl_job_cb_t

papplIterateXxxJobs callback function

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

pappl_job_t

Job object

typedef struct _pappl_job_s pappl_job_t;

pappl_jreason_t

Bitfield for IPP "job-state-reasons" values

typedef unsigned int pappl_jreason_t;

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_loglevel_t

Log levels

typedef enum pappl_loglevel_e pappl_loglevel_t;

pappl_loptions_t

Bitfield for link options

typedef unsigned short pappl_loptions_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_mime_cb_t

MIME typing callback function

typedef const char *(*pappl_mime_cb_t)(const unsigned char *header, size_t headersize, void *data);

pappl_mime_filter_cb_t

Filter callback function

typedef bool (*pappl_mime_filter_cb_t)(pappl_job_t *job, pappl_device_t *device, void *data);

pappl_ml_subcmd_cb_t

Sub-command callback

typedef int (*pappl_ml_subcmd_cb_t)(const char *base_name, int num_options, cups_option_t *options, int num_files, char **files, void *data);

pappl_ml_system_cb_t

System callback

typedef pappl_system_t *(*pappl_ml_system_cb_t)(int num_options, cups_option_t *options, void *data);

pappl_ml_usage_cb_t

Program usage callback

typedef void (*pappl_ml_usage_cb_t)(void *data);

pappl_pr_autoadd_cb_t

Auto-add callback

typedef const char *(*pappl_pr_autoadd_cb_t)(const char *device_info, const char *device_uri, const char *device_id, void *data);

pappl_pr_create_cb_t

Printer creation callback

typedef void (*pappl_pr_create_cb_t)(pappl_printer_t *printer, void *data);

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_driver_cb_t

Driver callback function

typedef bool (*pappl_pr_driver_cb_t)(pappl_system_t *system, const char *driver_name, const char *device_uri, const char *device_id, pappl_pr_driver_data_t *driver_data, ipp_t **driver_attrs, void *data);

pappl_pr_driver_data_t

Print driver data

typedef struct pappl_pr_driver_data_s pappl_pr_driver_data_t;

pappl_pr_driver_t

Printer driver information

typedef struct pappl_pr_driver_s pappl_pr_driver_t;

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_options_t

Combined print job options

typedef struct pappl_pr_options_s pappl_pr_options_t;

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_preason_t

Bitfield for IPP "printer-state-reasons" values

typedef unsigned int pappl_preason_t;

pappl_printer_cb_t

Printer iterator callback function

typedef void (*pappl_printer_cb_t)(pappl_printer_t *printer, void *data);

pappl_printer_t

Printer object

typedef struct _pappl_printer_s pappl_printer_t;

pappl_raster_type_t

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

typedef unsigned pappl_raster_type_t;

pappl_resource_cb_t

Dynamic resource callback function

typedef bool (*pappl_resource_cb_t)(pappl_client_t *client, void *data);

pappl_save_cb_t

Save callback function

typedef bool (*pappl_save_cb_t)(pappl_system_t *system, void *data);

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_soptions_t

Bitfield for system options

typedef unsigned pappl_soptions_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_system_t

System object

typedef struct _pappl_system_s pappl_system_t;

pappl_uoptions_t

USB gadget options bitfield

typedef unsigned pappl_uoptions_t;

pappl_version_t

Firmware version information

typedef struct pappl_version_s pappl_version_t;

Structures

pappl_contact_s

Contact information

struct pappl_contact_s {
    char email[256];
    char name[256];
    char telephone[256];
};

Members

email[256] Contact email address
name[256] Contact name
telephone[256] Contact phone number

pappl_devmetrics_s

Device metrics

struct pappl_devmetrics_s {
    size_t read_bytes;
    size_t read_msecs;
    size_t read_requests;
    size_t status_msecs;
    size_t status_requests;
    size_t write_bytes;
    size_t write_msecs;
    size_t write_requests;
};

Members

read_bytes Total number of bytes read
read_msecs Total number of milliseconds spent reading
read_requests Total number of read requests
status_msecs Total number of milliseconds spent getting status
status_requests Total number of status requests
write_bytes Total number of bytes written
write_msecs Total number of milliseconds spent writing
write_requests Total number of write requests

pappl_icon_s

Printer PNG icon structure

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

Members

data PNG icon data, if any
datalen Size of PNG icon data
filename[256] External filename, if any

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

Members

bottom_margin Bottom margin in hundredths of millimeters
left_margin Left margin in hundredths of millimeters
left_offset Left offset in hundredths of millimeters
right_margin Right margin in hundredths of millimeters
size_length Height in hundredths of millimeters
size_name[64] PWG media size name
size_width Width in hundredths of millimeters
source[64] PWG media source name
top_margin Top margin in hundredths of millimeters
top_offset Top offset in hundredths of millimeters
tracking Media tracking
type[64] PWG media type name

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

Members

bin[PAPPL_MAX_BIN] Output bins
bin_default Default output bin
borderless Borderless margins supported?
bottom_top Bottom and top margins in hundredths of millimeters
color_default "print-color-mode-default" value
color_supported "print-color-mode" values
content_default "print-content-default" value
darkness_configured printer-darkness-configured
darkness_default print-darkness-default
darkness_supported printer/print-darkness-supported (0 for none)
delete_cb Printer deletion callback
duplex Duplex printing modes supported
extension Extension data (managed by driver)
features[PAPPL_MAX_VENDOR] "ipp-features-supported" values
finishings "finishings-supported" values
force_raster_type Force a particular raster type?
format Printer-specific format
gdither 'auto', 'text', and 'graphic' dither array
has_supplies Printer has supplies to report
icons[3] "printer-icons" values
identify_cb Identify-Printer callback
identify_default "identify-actions-default" values
identify_supported "identify-actions-supported" values
input_face_up Does input media come in face-up?
kind "printer-kind" values
left_offset_supported[2] media-left-offset-supported (0,0 for none)
left_right Left and right margins in hundredths of millimeters
make_and_model[128] "printer-make-and-model" value
media[PAPPL_MAX_MEDIA] Supported media
media_default Default media
media_ready[PAPPL_MAX_SOURCE] Ready media
mode_configured label-mode-configured
mode_supported label-mode-supported
num_bin Number of output bins
num_features Number of "ipp-features-supported" values
num_media Number of supported media
num_resolution Number of printer resolutions
num_source Number of media sources (trays/rolls)
num_type Number of media types
num_vendor Number of vendor attributes
orient_default "orientation-requested-default" value
output_face_up Does output media come out face-up?
pdither 'photo' dither array
ppm "pages-per-minute" value
ppm_color "pages-per-minute-color" value, if any
printfile_cb Print (raw) file callback
quality_default "print-quality-default" value
raster_types "pwg-raster-document-type-supported" values
rendjob_cb End raster job callback
rendpage_cb End raster page callback
rstartjob_cb Start raster job callback
rstartpage_cb Start raster page callback
rwriteline_cb Write raster line callback
scaling_default "print-scaling-default" value
sides_default "sides-default" value
sides_supported "sides-supported" values
source[PAPPL_MAX_SOURCE] Media sources
speed_default print-speed-default
speed_supported[2] print-speed-supported (0,0 for none)
status_cb Status callback
tear_offset_configured label-tear-offset-configured
tear_offset_supported[2] label-tear-offset-supported (0,0 for none)
testpage_cb Test page callback
top_offset_supported[2] media-top-offset-supported (0,0 for none)
tracking_supported media-tracking-supported
type[PAPPL_MAX_TYPE] Media types
vendor[PAPPL_MAX_VENDOR] Vendor attribute names
x_default Default horizontal resolution
x_resolution[PAPPL_MAX_RESOLUTION] Horizontal printer resolutions
y_default Default vertical resolution
y_resolution[PAPPL_MAX_RESOLUTION] Vertical printer resolutions

pappl_pr_driver_s

Printer driver information

struct pappl_pr_driver_s {
    const char *description;
    const char *device_id;
    void *extension;
    const char *name;
};

Members

description Driver description (usually the make and model)
device_id IEEE-1284 device ID
extension Extension data pointer
name Driver name

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

Members

copies "copies" value
darkness_configured "printer-darkness-configured" value
dither Dither array, if any
finishings "finishings" value(s)
first_page First page in page-ranges, starting at 1
header Raster header
last_page Last page in page-ranges, starting at 1
media "media"/"media-col" value
num_pages Number of pages in job
num_vendor Number of vendor options
orientation_requested "orientation-requested" value
output_bin[64] "output-bin" value
print_color_mode "print-color-mode" value
print_content_optimize "print-content-optimize" value
print_darkness "print-darkness" value
print_quality "print-quality" value
print_scaling "print-scaling" value
print_speed "print-speed" value
printer_resolution[2] "printer-resolution" value in dots per inch
sides "sides" value
vendor Vendor options

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

Members

color Color, if any
description[256] Description
is_consumed Is this a supply that is consumed?
level Level (0-100, -1 = unknown)
type Type

pappl_version_s

Firmware version information

struct pappl_version_s {
    char name[64];
    char patches[64];
    char sversion[64];
    unsigned short version[4];
};

Members

name[64] "xxx-firmware-name" value
patches[64] "xxx-firmware-patches" value
sversion[64] "xxx-firmware-string-version" value
version[4] "xxx-firmware-version" value

Constants

pappl_color_mode_e

IPP "print-color-mode" bit values

Constants

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

Constants

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_devtype_e

Device type bit values

Constants

PAPPL_DEVTYPE_ALL All printers
PAPPL_DEVTYPE_CUSTOM_LOCAL Local printer using a custom interface or protocol
PAPPL_DEVTYPE_CUSTOM_NETWORK Network printer using a custom interface or protocol
PAPPL_DEVTYPE_DNS_SD Network printers discovered via DNS-SD/mDNS
PAPPL_DEVTYPE_FILE Local file/directory
PAPPL_DEVTYPE_LOCAL All local printers
PAPPL_DEVTYPE_NETWORK All network printers
PAPPL_DEVTYPE_SNMP Network printers discovered via SNMP
PAPPL_DEVTYPE_SOCKET Network printers using raw socket
PAPPL_DEVTYPE_USB USB printers

pappl_duplex_e

Duplex printing support

Constants

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

Constants

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

Constants

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_jreason_e

IPP "job-state-reasons" bit values

Constants

PAPPL_JREASON_ABORTED_BY_SYSTEM 'aborted-by-system'
PAPPL_JREASON_COMPRESSION_ERROR 'compression-error'
PAPPL_JREASON_DOCUMENT_FORMAT_ERROR 'document-format-error'
PAPPL_JREASON_DOCUMENT_PASSWORD_ERROR 'document-password-error'
PAPPL_JREASON_DOCUMENT_PERMISSION_ERROR 'document-permission-error'
PAPPL_JREASON_DOCUMENT_UNPRINTABLE_ERROR 'document-unprintable-error'
PAPPL_JREASON_ERRORS_DETECTED 'errors-detected'
PAPPL_JREASON_JOB_CANCELED_AT_DEVICE 'job-canceled-at-device'
PAPPL_JREASON_JOB_CANCELED_BY_USER 'job-canceled-by-user'
PAPPL_JREASON_JOB_COMPLETED_SUCCESSFULLY 'job-completed-successfully'
PAPPL_JREASON_JOB_COMPLETED_WITH_ERRORS 'job-completed-with-errors'
PAPPL_JREASON_JOB_COMPLETED_WITH_WARNINGS 'job-completed-with-warnings'
PAPPL_JREASON_JOB_DATA_INSUFFICIENT 'job-data-insufficient'
PAPPL_JREASON_JOB_INCOMING 'job-incoming'
PAPPL_JREASON_JOB_PRINTING 'job-printing'
PAPPL_JREASON_JOB_QUEUED 'job-queued'
PAPPL_JREASON_JOB_SPOOLING 'job-spooling'
PAPPL_JREASON_NONE 'none'
PAPPL_JREASON_PRINTER_STOPPED 'printer-stopped'
PAPPL_JREASON_PRINTER_STOPPED_PARTLY 'printer-stopped-partly'
PAPPL_JREASON_PROCESSING_TO_STOP_POINT 'processing-to-stop-point'
PAPPL_JREASON_QUEUED_IN_DEVICE 'queued-in-device'
PAPPL_JREASON_WARNINGS_DETECTED 'warnings-detected'

pappl_kind_e

IPP "printer-kind" bit values

Constants

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

Constants

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_loglevel_e

Log levels

Constants

PAPPL_LOGLEVEL_DEBUG Debug message
PAPPL_LOGLEVEL_ERROR Error message
PAPPL_LOGLEVEL_FATAL Fatal message
PAPPL_LOGLEVEL_INFO Informational message
PAPPL_LOGLEVEL_UNSPEC Not specified
PAPPL_LOGLEVEL_WARN Warning message

pappl_loptions_e

Link option bits

Constants

PAPPL_LOPTIONS_CONFIGURATION Link shown in configuration section
PAPPL_LOPTIONS_HTTPS_REQUIRED Link requires HTTPS
PAPPL_LOPTIONS_JOB Link shown in job(s) section
PAPPL_LOPTIONS_LOGGING Link shown in logging section
PAPPL_LOPTIONS_NAVIGATION Link shown in navigation bar
PAPPL_LOPTIONS_NETWORK Link shown in network section
PAPPL_LOPTIONS_OTHER Link shown in other section
PAPPL_LOPTIONS_PRINTER Link shown in printer(s) section
PAPPL_LOPTIONS_SECURITY Link shown in security section
PAPPL_LOPTIONS_STATUS Link shown in status section
PAPPL_LOPTIONS_TLS Link shown in TLS section

pappl_media_tracking_e

IPP "media-tracking" bit values

Constants

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

Constants

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

Constants

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

Constants

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

Constants

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_soptions_e

System option bits

Constants

PAPPL_SOPTIONS_DNSSD_HOST Use hostname in DNS-SD service names instead of serial number/UUID
PAPPL_SOPTIONS_MULTI_QUEUE Support multiple printers
PAPPL_SOPTIONS_NONE No options
PAPPL_SOPTIONS_RAW_SOCKET Accept jobs via raw sockets
PAPPL_SOPTIONS_USB_PRINTER Accept jobs via USB for default printer (embedded Linux only)
PAPPL_SOPTIONS_WEB_INTERFACE Enable the standard web pages
PAPPL_SOPTIONS_WEB_LOG Enable the log file page
PAPPL_SOPTIONS_WEB_NETWORK Enable the network settings page
PAPPL_SOPTIONS_WEB_REMOTE Allow remote queue management (vs. localhost only)
PAPPL_SOPTIONS_WEB_SECURITY Enable the user/password settings page
PAPPL_SOPTIONS_WEB_TLS Enable the TLS settings page

pappl_supply_color_e

"printer-supply" color values

Constants

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

Constants

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

Constants

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