Administration APIs

Please file issues on Github to provide feedback on this document.

Introduction

CUPS provides the "cups" library to talk to the different parts of CUPS and with Internet Printing Protocol (IPP) printers. The "cups" library functions are accessed by including the <cups/cups.h> header.

CUPS is based on the Internet Printing Protocol ("IPP"), which allows clients (applications) to communicate with a server (the scheduler, printers, etc.) to get a list of destinations, send print jobs, and so forth. You identify which server you want to communicate with using a pointer to the opaque structure http_t. The CUPS_HTTP_DEFAULT constant can be used when you want to talk to the CUPS scheduler.

Guidelines

When writing software (other than printer drivers) that uses the "cups" library:

Do not use undocumented or deprecated APIs,
Do not rely on pre-configured printers,
Do not assume that printers support specific features or formats, and
Do not rely on implementation details (PPDs, etc.)
Do not use undocumented or deprecated APIs,
+
Do not rely on pre-configured printers,
+
Do not assume that printers support specific features or formats, and
+
Do not rely on implementation details (PPDs, etc.)
+

CUPS is designed to insulate users and developers from the implementation details of printers and file formats. The goal is to allow an application to supply a print file in a standard format with the user intent ("print four copies, two-sided on A4 media, and staple each copy") and have the printing system manage the printer communication and format conversion needed.

Similarly, printer and job management applications can use standard query operations to obtain the status information in a common, generic form and use standard management operations to control the state of those printers and jobs.

Note:

CUPS printer drivers necessarily depend on specific file formats and certain implementation details of the CUPS software. Please consult the Postscript and raster printer driver developer documentation on CUPS.org for more information.

Terms Used in This Document

A Destination is a printer or print queue that accepts print jobs. A Print Job is a collection of one or more documents that are processed by a destination using options supplied when creating the job. A Document is a file (JPEG image, PDF file, etc.) suitable for printing. An Option controls some aspect of printing, such as the media used. Media is the sheets or roll that is printed on. An Attribute is an option encoded for an Internet Printing Protocol (IPP) request.

Compiling Programs That Use the CUPS API

Terms Used in This Document

A Destination is a printer or print queue that accepts print jobs. A Print Job is a collection of one or more documents that are processed by a destination using options supplied when creating the job. A Document is a file (JPEG image, PDF file, etc.) suitable for printing. An Option controls some aspect of printing, such as the media used. Media is the sheets or roll that is printed on. An Attribute is an option encoded for an Internet Printing Protocol (IPP) request.

Compiling Programs That Use the CUPS API

The CUPS libraries can be used from any C, C++, or Objective C program. The method of compiling against the libraries varies depending on the operating system and installation of CUPS. The following sections show how to compile a simple program (shown below) in two common environments.

The following simple program lists the available destinations:

#include <stdio.h>
@@ -562,20 +556,20 @@ int main(void)
   return (0);
 }

Compiling with Xcode

In Xcode, choose New Project... from the File menu (or press SHIFT+CMD+N), then select the Command Line Tool under the macOS Application project type. Click Next and enter a name for the project, for example "firstcups". Click Next and choose a project directory. The click Next to create the project.

In the project window, click on the Build Phases group and expand the Link Binary with Libraries section. Click +, type "libcups" to show the library, and then double-click on libcups.tbd.

Compiling with Xcode

In Xcode, choose New Project... from the File menu (or press SHIFT+CMD+N), then select the Command Line Tool under the macOS Application project type. Click Next and enter a name for the project, for example "firstcups". Click Next and choose a project directory. The click Next to create the project.

In the project window, click on the Build Phases group and expand the Link Binary with Libraries section. Click +, type "libcups" to show the library, and then double-click on libcups.tbd.

Finally, click on the main.c file in the sidebar and copy the example program to the file. Build and run (CMD+R) to see the list of destinations.

Compiling with GCC

From the command-line, create a file called sample.c using your favorite editor, copy the example to this file, and save. Then run the following command to compile it with GCC and run it:

gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
 ./simple

The cups-config command provides the compiler flags (cups-config --cflags) and libraries (cups-config --libs) needed for the local system.

Working with Destinations

Destinations, which in CUPS represent individual printers or classes (collections or pools) of printers, are represented by the cups_dest_t structure which includes the name (name), instance (instance, saved options/settings), whether the destination is the default for the user (is_default), and the options and basic information associated with that destination (num_options and options).

Historically destinations have been manually maintained by the administrator of a system or network, but CUPS also supports dynamic discovery of destinations on the current network.

Finding Available Destinations

The cupsEnumDests function finds all of the available destinations:

 int
  cupsEnumDests(unsigned flags, int msec, int *cancel,
@@ -587,24 +581,42 @@ int main(void)
     The cancel argument points to an integer variable that, when set to a non-zero value, will cause enumeration to stop as soon as possible. It can be NULL if not needed.
     The type and mask arguments are bitfields that allow the caller to filter the destinations based on categories and/or capabilities. The destination's "printer-type" value is masked by the mask value and compared to the type value when filtering. For example, to only enumerate destinations that are hosted on the local system, pass CUPS_PRINTER_LOCAL for the type argument and CUPS_PRINTER_DISCOVERED for the mask argument. The following constants can be used for filtering:
     
-    CUPS_PRINTER_CLASS: A collection of destinations.
-    CUPS_PRINTER_FAX: A facsimile device.
-    CUPS_PRINTER_LOCAL: A local printer or class. This constant has the value 0 (no bits set) and is only used for the type argument and is paired with the CUPS_PRINTER_REMOTE or CUPS_PRINTER_DISCOVERED constant passed in the mask argument.
-    CUPS_PRINTER_REMOTE: A remote (shared) printer or class.
-    CUPS_PRINTER_DISCOVERED: An available network printer or class.
-    CUPS_PRINTER_BW: Can do B&W printing.
-    CUPS_PRINTER_COLOR: Can do color printing.
-    CUPS_PRINTER_DUPLEX: Can do two-sided printing.
-    CUPS_PRINTER_STAPLE: Can staple output.
-    CUPS_PRINTER_COLLATE: Can quickly collate copies.
-    CUPS_PRINTER_PUNCH: Can punch output.
-    CUPS_PRINTER_COVER: Can cover output.
-    CUPS_PRINTER_BIND: Can bind output.
-    CUPS_PRINTER_SORT: Can sort output (mailboxes, etc.)
-    CUPS_PRINTER_SMALL: Can print on Letter/Legal/A4-size media.
-    CUPS_PRINTER_MEDIUM: Can print on Tabloid/B/C/A3/A2-size media.
-    CUPS_PRINTER_LARGE: Can print on D/E/A1/A0-size media.
-    CUPS_PRINTER_VARIABLE: Can print on rolls and custom-size media.
+        CUPS_PRINTER_CLASS: A collection of destinations.
+
+        CUPS_PRINTER_FAX: A facsimile device.
+
+        CUPS_PRINTER_LOCAL: A local printer or class. This constant has the value 0 (no bits set) and is only used for the type argument and is paired with the CUPS_PRINTER_REMOTE or CUPS_PRINTER_DISCOVERED constant passed in the mask argument.
+
+        CUPS_PRINTER_REMOTE: A remote (shared) printer or class.
+
+        CUPS_PRINTER_DISCOVERED: An available network printer or class.
+
+        CUPS_PRINTER_BW: Can do B&W printing.
+
+        CUPS_PRINTER_COLOR: Can do color printing.
+
+        CUPS_PRINTER_DUPLEX: Can do two-sided printing.
+
+        CUPS_PRINTER_STAPLE: Can staple output.
+
+        CUPS_PRINTER_COLLATE: Can quickly collate copies.
+
+        CUPS_PRINTER_PUNCH: Can punch output.
+
+        CUPS_PRINTER_COVER: Can cover output.
+
+        CUPS_PRINTER_BIND: Can bind output.
+
+        CUPS_PRINTER_SORT: Can sort output (mailboxes, etc.)
+
+        CUPS_PRINTER_SMALL: Can print on Letter/Legal/A4-size media.
+
+        CUPS_PRINTER_MEDIUM: Can print on Tabloid/B/C/A3/A2-size media.
+
+        CUPS_PRINTER_LARGE: Can print on D/E/A1/A0-size media.
+
+        CUPS_PRINTER_VARIABLE: Can print on rolls and custom-size media.
+
 
     The cb argument specifies a function to call for every destination that is found:
     typedef int (*cups_dest_cb_t)(void *user_data,
@@ -613,9 +625,12 @@ int main(void)
 
     The callback function receives a copy of the user_data argument along with a bitfield (flags) and the destination that was found. The flags argument can have any of the following constant (bit) values set:
     
-    CUPS_DEST_FLAGS_MORE: There are more destinations coming.
-    CUPS_DEST_FLAGS_REMOVED: The destination has gone away and should be removed from the list of destinations a user can select.
-    CUPS_DEST_FLAGS_ERROR: An error occurred. The reason for the error can be found by calling the cupsLastError and/or cupsLastErrorString functions.
+        CUPS_DEST_FLAGS_MORE: There are more destinations coming.
+
+        CUPS_DEST_FLAGS_REMOVED: The destination has gone away and should be removed from the list of destinations a user can select.
+
+        CUPS_DEST_FLAGS_ERROR: An error occurred. The reason for the error can be found by calling the cupsLastError and/or cupsLastErrorString functions.
+
 
     The callback function returns 0 to stop enumeration or 1 to continue.
     
@@ -689,34 +704,45 @@ my_get_dests(cups_ptype_t type, cups_ptype_t mask,
   return (user_data.num_dests);
 }

Basic Destination Information

The num_options and options members of the cups_dest_t structure provide basic attributes about the destination in addition to the user default options and values for that destination. The following names are predefined for various destination attributes:

"auth-info-required": The type of authentication required for printing to this destination: "none", "username,password", "domain,username,password", or "negotiate" (Kerberos).
"printer-info": The human-readable description of the destination such as "My Laser Printer".
"printer-is-accepting-jobs": "true" if the destination is accepting new jobs, "false" otherwise.
"printer-is-shared": "true" if the destination is being shared with other computers, "false" otherwise.
"printer-location": The human-readable location of the destination such as "Lab 4".
"printer-make-and-model": The human-readable make and model of the destination such as "ExampleCorp LaserPrinter 4000 Series".
"printer-state": "3" if the destination is idle, "4" if the destination is printing a job, and "5" if the destination is stopped.
"printer-state-change-time": The UNIX time when the destination entered the current state.
"printer-state-reasons": Additional comma-delimited state keywords for the destination such as "media-tray-empty-error" and "toner-low-warning".
"printer-type": The cups_ptype_t value associated with the destination.
"printer-uri-supported": The URI associated with the destination; if not set, this destination was discovered but is not yet setup as a local printer.
"auth-info-required": The type of authentication required for printing to this destination: "none", "username,password", "domain,username,password", or "negotiate" (Kerberos).
+
"printer-info": The human-readable description of the destination such as "My Laser Printer".
+
"printer-is-accepting-jobs": "true" if the destination is accepting new jobs, "false" otherwise.
+
"printer-is-shared": "true" if the destination is being shared with other computers, "false" otherwise.
+
"printer-location": The human-readable location of the destination such as "Lab 4".
+
"printer-make-and-model": The human-readable make and model of the destination such as "ExampleCorp LaserPrinter 4000 Series".
+
"printer-state": "3" if the destination is idle, "4" if the destination is printing a job, and "5" if the destination is stopped.
+
"printer-state-change-time": The UNIX time when the destination entered the current state.
+
"printer-state-reasons": Additional comma-delimited state keywords for the destination such as "media-tray-empty-error" and "toner-low-warning".
+
"printer-type": The cups_ptype_t value associated with the destination.
+
"printer-uri-supported": The URI associated with the destination; if not set, this destination was discovered but is not yet setup as a local printer.
+

Use the cupsGetOption function to retrieve the value. For example, the following code gets the make and model of a destination:

const char *model = cupsGetOption("printer-make-and-model",
                                   dest->num_options,
                                   dest->options);

Detailed Destination Information

Once a destination has been chosen, the cupsCopyDestInfo function can be used to gather detailed information about the destination:

cups_dinfo_t *
 cupsCopyDestInfo(http_t *http, cups_dest_t *dest);

The http argument specifies a connection to the CUPS scheduler and is typically the constant CUPS_HTTP_DEFAULT. The dest argument specifies the destination to query.

The cups_dinfo_t structure that is returned contains a snapshot of the supported options and their supported, ready, and default values. It also can report constraints between different options and values, and recommend changes to resolve those constraints.

Getting Supported Options and Values

The cupsCheckDestSupported function can be used to test whether a particular option or option and value is supported:

int
 cupsCheckDestSupported(http_t *http, cups_dest_t *dest,
@@ -726,16 +752,26 @@ cupsCheckDestSupported(http_t *http, cups_dest_t *dest,

The option argument specifies the name of the option to check. The following constants can be used to check the various standard options:

CUPS_COPIES: Controls the number of copies that are produced.
CUPS_FINISHINGS: A comma-delimited list of integer constants that control the finishing processes that are applied to the job, including stapling, punching, and folding.
CUPS_MEDIA: Controls the media size that is used, typically one of the following: CUPS_MEDIA_3X5, CUPS_MEDIA_4X6, CUPS_MEDIA_5X7, CUPS_MEDIA_8X10, CUPS_MEDIA_A3, CUPS_MEDIA_A4, CUPS_MEDIA_A5, CUPS_MEDIA_A6, CUPS_MEDIA_ENV10, CUPS_MEDIA_ENVDL, CUPS_MEDIA_LEGAL, CUPS_MEDIA_LETTER, CUPS_MEDIA_PHOTO_L, CUPS_MEDIA_SUPERBA3, or CUPS_MEDIA_TABLOID.
CUPS_MEDIA_SOURCE: Controls where the media is pulled from, typically either CUPS_MEDIA_SOURCE_AUTO or CUPS_MEDIA_SOURCE_MANUAL.
CUPS_MEDIA_TYPE: Controls the type of media that is used, typically one of the following: CUPS_MEDIA_TYPE_AUTO, CUPS_MEDIA_TYPE_ENVELOPE, CUPS_MEDIA_TYPE_LABELS, CUPS_MEDIA_TYPE_LETTERHEAD, CUPS_MEDIA_TYPE_PHOTO, CUPS_MEDIA_TYPE_PHOTO_GLOSSY, CUPS_MEDIA_TYPE_PHOTO_MATTE, CUPS_MEDIA_TYPE_PLAIN, or CUPS_MEDIA_TYPE_TRANSPARENCY.
CUPS_NUMBER_UP: Controls the number of document pages that are placed on each media side.
CUPS_ORIENTATION: Controls the orientation of document pages placed on the media: CUPS_ORIENTATION_PORTRAIT or CUPS_ORIENTATION_LANDSCAPE.
CUPS_PRINT_COLOR_MODE: Controls whether the output is in color (CUPS_PRINT_COLOR_MODE_COLOR), grayscale (CUPS_PRINT_COLOR_MODE_MONOCHROME), or either (CUPS_PRINT_COLOR_MODE_AUTO).
CUPS_PRINT_QUALITY: Controls the generate quality of the output: CUPS_PRINT_QUALITY_DRAFT, CUPS_PRINT_QUALITY_NORMAL, or CUPS_PRINT_QUALITY_HIGH.
CUPS_SIDES: Controls whether prints are placed on one or both sides of the media: CUPS_SIDES_ONE_SIDED, CUPS_SIDES_TWO_SIDED_PORTRAIT, or CUPS_SIDES_TWO_SIDED_LANDSCAPE.
CUPS_COPIES: Controls the number of copies that are produced.
+
CUPS_FINISHINGS: A comma-delimited list of integer constants that control the finishing processes that are applied to the job, including stapling, punching, and folding.
+
CUPS_MEDIA: Controls the media size that is used, typically one of the following: CUPS_MEDIA_3X5, CUPS_MEDIA_4X6, CUPS_MEDIA_5X7, CUPS_MEDIA_8X10, CUPS_MEDIA_A3, CUPS_MEDIA_A4, CUPS_MEDIA_A5, CUPS_MEDIA_A6, CUPS_MEDIA_ENV10, CUPS_MEDIA_ENVDL, CUPS_MEDIA_LEGAL, CUPS_MEDIA_LETTER, CUPS_MEDIA_PHOTO_L, CUPS_MEDIA_SUPERBA3, or CUPS_MEDIA_TABLOID.
+
CUPS_MEDIA_SOURCE: Controls where the media is pulled from, typically either CUPS_MEDIA_SOURCE_AUTO or CUPS_MEDIA_SOURCE_MANUAL.
+
CUPS_MEDIA_TYPE: Controls the type of media that is used, typically one of the following: CUPS_MEDIA_TYPE_AUTO, CUPS_MEDIA_TYPE_ENVELOPE, CUPS_MEDIA_TYPE_LABELS, CUPS_MEDIA_TYPE_LETTERHEAD, CUPS_MEDIA_TYPE_PHOTO, CUPS_MEDIA_TYPE_PHOTO_GLOSSY, CUPS_MEDIA_TYPE_PHOTO_MATTE, CUPS_MEDIA_TYPE_PLAIN, or CUPS_MEDIA_TYPE_TRANSPARENCY.
+
CUPS_NUMBER_UP: Controls the number of document pages that are placed on each media side.
+
CUPS_ORIENTATION: Controls the orientation of document pages placed on the media: CUPS_ORIENTATION_PORTRAIT or CUPS_ORIENTATION_LANDSCAPE.
+
CUPS_PRINT_COLOR_MODE: Controls whether the output is in color (CUPS_PRINT_COLOR_MODE_COLOR), grayscale (CUPS_PRINT_COLOR_MODE_MONOCHROME), or either (CUPS_PRINT_COLOR_MODE_AUTO).
+
CUPS_PRINT_QUALITY: Controls the generate quality of the output: CUPS_PRINT_QUALITY_DRAFT, CUPS_PRINT_QUALITY_NORMAL, or CUPS_PRINT_QUALITY_HIGH.
+
CUPS_SIDES: Controls whether prints are placed on one or both sides of the media: CUPS_SIDES_ONE_SIDED, CUPS_SIDES_TWO_SIDED_PORTRAIT, or CUPS_SIDES_TWO_SIDED_LANDSCAPE.
+

If the value argument is NULL, the cupsCheckDestSupported function returns whether the option is supported by the destination. Otherwise, the function returns whether the specified value of the option is supported.

The cupsFindDestSupported function returns the IPP attribute containing the supported values for a given option:

Getting Default Values

There are two sets of default values - user defaults that are available via the num_options and options members of the cups_dest_t structure, and destination defaults that available via the cups_dinfo_t structure and the cupsFindDestDefault function which returns the IPP attribute containing the default value(s) for a given option:

ipp_attribute_t *
 cupsFindDestDefault(http_t *http, cups_dest_t *dest,
@@ -802,7 +838,7 @@ else
   putchar('\n');
 }

Getting Ready (Loaded) Values

The finishings and media options also support queries for the ready, or loaded, values. For example, a printer may have punch and staple finishers installed but be out of staples - the supported values will list both punch and staple finishing processes but the ready values will only list the punch processes. Similarly, a printer may support hundreds of different sizes of media but only have a single size loaded at any given time - the ready values are limited to the media that is actually in the printer.

The cupsFindDestReady function finds the IPP attribute containing the ready values for a given option:

ipp_attribute_t *
@@ -825,7 +861,7 @@ if (ready_finishings != NULL)
 else
   puts("no finishings are ready.");

Media Size Options

CUPS provides functions for querying the dimensions and margins for each of the supported media size options. The cups_size_t structure is used to describe a media size:

typedef struct cups_size_s
 {
@@ -850,11 +886,16 @@ cupsGetDestMediaBySize(http_t *http, cups_dest_t *dest,

The media, width, and length arguments specify the size to lookup. The flags argument specifies a bitfield controlling various lookup options:

CUPS_MEDIA_FLAGS_DEFAULT: Find the closest size supported by the printer.
CUPS_MEDIA_FLAGS_BORDERLESS: Find a borderless size.
CUPS_MEDIA_FLAGS_DUPLEX: Find a size compatible with two-sided printing.
CUPS_MEDIA_FLAGS_EXACT: Find an exact match for the size.
CUPS_MEDIA_FLAGS_READY: If the printer supports media sensing or configuration of the media in each tray/source, find the size amongst the "ready" media.
CUPS_MEDIA_FLAGS_DEFAULT: Find the closest size supported by the printer.
+
CUPS_MEDIA_FLAGS_BORDERLESS: Find a borderless size.
+
CUPS_MEDIA_FLAGS_DUPLEX: Find a size compatible with two-sided printing.
+
CUPS_MEDIA_FLAGS_EXACT: Find an exact match for the size.
+
CUPS_MEDIA_FLAGS_READY: If the printer supports media sensing or configuration of the media in each tray/source, find the size amongst the "ready" media.
+

If a matching size is found for the destination, the size information is stored in the structure pointed to by the size argument and 1 is returned. Otherwise 0 is returned.

For example, the following code prints the margins for two-sided printing on US Letter media:

Localizing Options and Values

CUPS provides three functions to get localized, human-readable strings in the user's current locale for options and values: cupsLocalizeDestMedia, cupsLocalizeDestOption, and cupsLocalizeDestValue:

const char *
 cupsLocalizeDestMedia(http_t *http, cups_dest_t *dest,
@@ -929,7 +970,7 @@ cupsLocalizeDestValue(http_t *http, cups_dest_t *dest,
                       cups_dinfo_t *info,
                       const char *option, const char *value);

Submitting a Print Job

Once you are ready to submit a print job, you create a job using the cupsCreateDestJob function:

ipp_status_t
 cupsCreateDestJob(http_t *http, cups_dest_t *dest,
@@ -980,10 +1021,14 @@ cupsFinishDestDocument(http_t *http, cups_dest_t *dest,

The docname argument specifies the name of the document, typically the original filename. The format argument specifies the MIME media type of the document, including the following constants:

CUPS_FORMAT_JPEG: "image/jpeg"
CUPS_FORMAT_PDF: "application/pdf"
CUPS_FORMAT_POSTSCRIPT: "application/postscript"
CUPS_FORMAT_TEXT: "text/plain"
CUPS_FORMAT_JPEG: "image/jpeg"
+
CUPS_FORMAT_PDF: "application/pdf"
+
CUPS_FORMAT_POSTSCRIPT: "application/postscript"
+
CUPS_FORMAT_TEXT: "text/plain"
+

The num_options and options arguments specify per-document print options, which at present must be 0 and NULL. The last_document argument specifies whether this is the last document in the job.

For example, the following code submits a PDF file to the job that was just created:

Sending IPP Requests

CUPS provides a rich API for sending IPP requests to the scheduler or printers, typically from management or utility applications whose primary purpose is not to send print jobs.

Connecting to the Scheduler or Printer

The connection to the scheduler or printer is represented by the HTTP connection type http_t. The cupsConnectDest function connects to the scheduler or printer associated with the destination:

http_t *
 cupsConnectDest(cups_dest_t *dest, unsigned flags, int msec,
@@ -1033,7 +1078,7 @@ http_t *http = cupsConnectDest(dest, CUPS_DEST_FLAGS_DEVICE,
                                30000, NULL, resource,
                                sizeof(resource), NULL, NULL);

Creating an IPP Request

IPP requests are represented by the IPP message type ipp_t and each IPP attribute in the request is representing using the type ipp_attribute_t. Each IPP request includes an operation code (IPP_OP_CREATE_JOB, IPP_OP_GET_PRINTER_ATTRIBUTES, etc.) and a 32-bit integer identifier.

The ippNewRequest function creates a new IPP request:

ipp_t *
@@ -1071,19 +1116,30 @@ ippAddStrings(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD,
     The ippAddStrings function adds an attribute with one or more strings, in this case three. The IPP_TAG_KEYWORD argument specifies that the strings are keyword values, which are used for attribute names. All strings use the same language (NULL), and the attribute will contain the three strings in the array requested_attributes.
     CUPS provides many functions to adding attributes of different types:
     
-    ippAddBoolean adds a boolean (IPP_TAG_BOOLEAN) attribute with one value.
-    ippAddInteger adds an enum (IPP_TAG_ENUM) or integer (IPP_TAG_INTEGER) attribute with one value.
-    ippAddIntegers adds an enum or integer attribute with one or more values.
-    ippAddOctetString adds an octetString attribute with one value.
-    ippAddOutOfBand adds a admin-defined (IPP_TAG_ADMINDEFINE), default (IPP_TAG_DEFAULT), delete-attribute (IPP_TAG_DELETEATTR), no-value (IPP_TAG_NOVALUE), not-settable (IPP_TAG_NOTSETTABLE), unknown (IPP_TAG_UNKNOWN), or unsupported (IPP_TAG_UNSUPPORTED_VALUE) out-of-band attribute.
-    ippAddRange adds a rangeOfInteger attribute with one range.
-    ippAddRanges adds a rangeOfInteger attribute with one or more ranges.
-    ippAddResolution adds a resolution attribute with one resolution.
-    ippAddResolutions adds a resolution attribute with one or more resolutions.
-    ippAddString adds a charset (IPP_TAG_CHARSET), keyword (IPP_TAG_KEYWORD), mimeMediaType (IPP_TAG_MIMETYPE), name (IPP_TAG_NAME and IPP_TAG_NAMELANG), naturalLanguage (IPP_TAG_NATURAL_LANGUAGE), text (IPP_TAG_TEXT and IPP_TAG_TEXTLANG), uri (IPP_TAG_URI), or uriScheme (IPP_TAG_URISCHEME) attribute with one value.
-    ippAddStrings adds a charset, keyword, mimeMediaType, name, naturalLanguage, text, uri, or uriScheme attribute with one or more values.
+        ippAddBoolean adds a boolean (IPP_TAG_BOOLEAN) attribute with one value.
+
+        ippAddInteger adds an enum (IPP_TAG_ENUM) or integer (IPP_TAG_INTEGER) attribute with one value.
+
+        ippAddIntegers adds an enum or integer attribute with one or more values.
+
+        ippAddOctetString adds an octetString attribute with one value.
+
+        ippAddOutOfBand adds a admin-defined (IPP_TAG_ADMINDEFINE), default (IPP_TAG_DEFAULT), delete-attribute (IPP_TAG_DELETEATTR), no-value (IPP_TAG_NOVALUE), not-settable (IPP_TAG_NOTSETTABLE), unknown (IPP_TAG_UNKNOWN), or unsupported (IPP_TAG_UNSUPPORTED_VALUE) out-of-band attribute.
+
+        ippAddRange adds a rangeOfInteger attribute with one range.
+
+        ippAddRanges adds a rangeOfInteger attribute with one or more ranges.
+
+        ippAddResolution adds a resolution attribute with one resolution.
+
+        ippAddResolutions adds a resolution attribute with one or more resolutions.
+
+        ippAddString adds a charset (IPP_TAG_CHARSET), keyword (IPP_TAG_KEYWORD), mimeMediaType (IPP_TAG_MIMETYPE), name (IPP_TAG_NAME and IPP_TAG_NAMELANG), naturalLanguage (IPP_TAG_NATURAL_LANGUAGE), text (IPP_TAG_TEXT and IPP_TAG_TEXTLANG), uri (IPP_TAG_URI), or uriScheme (IPP_TAG_URISCHEME) attribute with one value.
+
+        ippAddStrings adds a charset, keyword, mimeMediaType, name, naturalLanguage, text, uri, or uriScheme attribute with one or more values.
+
 
-    Sending the IPP Request
+    Sending the IPP Request
     Once you have created the IPP request, you can send it using the cupsDoRequest function. For example, the following code sends the IPP Get-Printer-Attributes request to the destination and saves the response:
     ipp_t *response = cupsDoRequest(http, request, resource);
 
@@ -1105,7 +1161,7 @@ ippAddStrings(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD,
   printf("Request failed: %s\n", cupsLastErrorString());
 }

Processing the IPP Response

Each response to an IPP request is also an IPP message (ipp_t) with its own IPP attributes (ipp_attribute_t) that includes a status code (IPP_STATUS_OK, IPP_STATUS_ERROR_BAD_REQUEST, etc.) and the corresponding 32-bit integer identifier from the request.

For example, the following code finds the printer state attributes and prints their values:

ipp_attribute_t *attr;
@@ -1142,7 +1198,7 @@ if ((attr = ippFindAttribute(response, "printer-state-reasons",
     Once you are done using the IPP response message, free it using the ippDelete function:
     ippDelete(response);
 
-    Authentication
+    Authentication
     CUPS normally handles authentication through the console. GUI applications should set a password callback using the cupsSetPasswordCB2 function:
     void
 cupsSetPasswordCB2(cups_password_cb2_t cb, void *user_data);
diff --git a/doc/help/postscript-driver.html b/doc/help/postscript-driver.html
index f94fa72fd..59832ebdc 100644
--- a/doc/help/postscript-driver.html
+++ b/doc/help/postscript-driver.html
@@ -5,7 +5,7 @@
     Developing PostScript Printer Drivers
     
     
-    
+    
     
     
     
@@ -450,6 +450,7 @@ h3.title {
 -->
   
   
+    
 
   
   
+    
 
   
   
+    
 
   
   
+

CUPS Programming Manual

CUPS Programming Manual

Contents

Introduction

Guidelines

Terms Used in This Document

Compiling Programs That Use the CUPS API

Compiling with Xcode

Compiling with GCC

Working with Destinations

Finding Available Destinations

Basic Destination Information

Detailed Destination Information

Getting Supported Options and Values

Getting Default Values

Getting Ready (Loaded) Values

Media Size Options

Localizing Options and Values

Submitting a Print Job

Sending IPP Requests

Connecting to the Scheduler or Printer

Creating an IPP Request

Sending the IPP Request

Processing the IPP Response

Authentication