-<!doctype html>
+<!DOCTYPE html>
<html>
<!-- SECTION: Programming -->
<head>
<title>CUPS Programming Manual</title>
<meta name="keywords" content="Programming">
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
- <meta name="creator" content="Mini-XML v2.11">
+ <meta name="creator" content="codedoc v3.1">
<meta name="author" content="Michael R Sweet">
- <meta name="copyright" content="Copyright © 2007-2017 by Apple Inc. All Rights Reserved.">
- <meta name="version" content="2.2.5">
+ <meta name="copyright" content="Copyright © 2007-2022 by Apple Inc. All Rights Reserved.">
+ <meta name="version" content="2.3.6">
<style type="text/css"><!--
body, p, h1, h2, h3, h4 {
font-family: sans-serif;
<body>
<h1 class="title">CUPS Programming Manual</h1>
<p>Michael R Sweet</p>
- <p>Copyright © 2007-2017 by Apple Inc. All Rights Reserved.</p>
+ <p>Copyright © 2007-2020 by Apple Inc. All Rights Reserved.</p>
<div class="contents">
<h2 class="title">Contents</h2>
<ul class="contents">
<li><a href="#cupsCopyDestInfo">cupsCopyDestInfo</a></li>
<li><a href="#cupsCreateDestJob">cupsCreateDestJob</a></li>
<li><a href="#cupsDoAuthentication">cupsDoAuthentication</a></li>
+ <li><a href="#cupsEncodeOption">cupsEncodeOption</a></li>
<li><a href="#cupsEncodeOptions">cupsEncodeOptions</a></li>
<li><a href="#cupsEncodeOptions2">cupsEncodeOptions2</a></li>
<li><a href="#cupsEncryption">cupsEncryption</a></li>
<li><a href="#ipp_pstate_t">ipp_pstate_t</a></li>
<li><a href="#ipp_quality_t">ipp_quality_t</a></li>
<li><a href="#ipp_res_t">ipp_res_t</a></li>
+ <li><a href="#ipp_rstate_t">ipp_rstate_t</a></li>
+ <li><a href="#ipp_sstate_t">ipp_sstate_t</a></li>
<li><a href="#ipp_state_t">ipp_state_t</a></li>
<li><a href="#ipp_t">ipp_t</a></li>
</ul></li>
<li><a href="#ipp_pstate_e">ipp_pstate_e</a></li>
<li><a href="#ipp_quality_e">ipp_quality_e</a></li>
<li><a href="#ipp_res_e">ipp_res_e</a></li>
+ <li><a href="#ipp_rstate_e">ipp_rstate_e</a></li>
+ <li><a href="#ipp_sstate_e">ipp_sstate_e</a></li>
<li><a href="#ipp_state_e">ipp_state_e</a></li>
<li><a href="#ipp_status_e">ipp_status_e</a></li>
<li><a href="#ipp_tag_e">ipp_tag_e</a></li>
<p>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 <code><cups/cups.h></code> header.</p>
<p>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 <code>http_t</code>. The <code>CUPS_HTTP_DEFAULT</code> constant can be used when you want to talk to the CUPS scheduler.</p>
<h3><a id="guidelines">Guidelines</a></h3>
- <p>When writing software that uses the "cups" library:</p>
+ <p>When writing software (other than printer drivers) that uses the "cups" library:</p>
<ul>
<li>Do not use undocumented or deprecated APIs,</li>
<li>Do not rely on pre-configured printers,</li>
</ul>
<p>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.</p>
<p>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.</p>
+ <blockquote>
+ <p><strong>Note:</strong></p>
+ <p>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 <a href="https://www.cups.org/documentation.html">CUPS.org</a> for more information.</p>
+</blockquote>
<h3><a id="terms-used-in-this-document">Terms Used in This Document</a></h3>
- <p>A <em>Destination</em> is a printer or print queue that accepts print jobs. A <em>Print</em> <em>Job</em> is one or more documents that are processed by a destination using options supplied when creating the job. A <em>Document</em> is a file (JPEG image, PDF file, etc.) suitable for printing. An <em>Option</em> controls some aspect of printing, such as the media used. <em>Media</em> is the sheets or roll that is printed on. An <em>Attribute</em> is an option encoded for an Internet Printing Protocol (IPP) request.</p>
+ <p>A <em>Destination</em> is a printer or print queue that accepts print jobs. A <em>Print</em> <em>Job</em> is a collection of one or more documents that are processed by a destination using options supplied when creating the job. A <em>Document</em> is a file (JPEG image, PDF file, etc.) suitable for printing. An <em>Option</em> controls some aspect of printing, such as the media used. <em>Media</em> is the sheets or roll that is printed on. An <em>Attribute</em> is an option encoded for an Internet Printing Protocol (IPP) request.</p>
<h3><a id="compiling-programs-that-use-the-cups-api">Compiling Programs That Use the CUPS API</a></h3>
<p>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.</p>
<p>The following simple program lists the available destinations:</p>
<p>In the project window, click on the <em>Build</em> <em>Phases</em> group and expand the <em>Link</em> <em>Binary</em> <em>with</em> <em>Libraries</em> section. Click <em>+</em>, type "libcups" to show the library, and then double-click on <code>libcups.tbd</code>.</p>
<p>Finally, click on the <code>main.c</code> file in the sidebar and copy the example program to the file. Build and run (CMD+R) to see the list of destinations.</p>
<h4><a id="compiling-with-gcc">Compiling with GCC</a></h4>
- <p>From the command-line, create a file called <code>sample.c</code> 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:</p>
+ <p>From the command-line, create a file called <code>simple.c</code> 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:</p>
<pre><code>gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
./simple
</code></pre>
</ul>
<p>The callback function returns 0 to stop enumeration or 1 to continue.</p>
<blockquote>
- <p>Note that the callback function will likely be called multiple times for the same destination, so it is up to the caller to suppress any duplicate destinations.</p>
+ <p><strong>Note:</strong></p>
+ <p>The callback function will likely be called multiple times for the same destination, so it is up to the caller to suppress any duplicate destinations.</p>
</blockquote>
<p>The following example shows how to use <code>cupsEnumDests</code> to get a filtered array of destinations:</p>
<pre><code>typedef struct
"printer-uri", NULL, printer_uri);
</code></pre>
<blockquote>
- <p>Note: If we wanted to query the scheduler instead of the device, we would look up the "printer-uri-supported" option instead of the "device-uri" value.</p>
+ <p><strong>Note:</strong></p>
+ <p>If we wanted to query the scheduler instead of the device, we would look up the "printer-uri-supported" option instead of the "device-uri" value.</p>
</blockquote>
<p>The <code>ippAddString</code> function adds the "printer-uri" attribute the the IPP request. The <code>IPP_TAG_OPERATION</code> argument specifies that the attribute is part of the operation. The <code>IPP_TAG_URI</code> argument specifies that the value is a Universal Resource Identifier (URI) string. The <code>NULL</code> argument specifies there is no language (English, French, Japanese, etc.) associated with the string, and the <code>printer_uri</code> argument specifies the string value.</p>
<p>The IPP Get-Printer-Attributes request also supports an IPP attribute called "requested-attributes" that lists the attributes and values you are interested in. For example, the following code requests the printer state attributes:</p>
<br>
Use the <a href="#cupsSaveDests"><code>cupsSaveDests</code></a> function to save the updated list of
destinations to the user's lpoptions file.</p>
-<h3 class="function"><span class="info"> CUPS 2.3 </span><a id="cupsAddDestMediaOptions">cupsAddDestMediaOptions</a></h3>
+<h3 class="function"><span class="info"> CUPS 2.3
/macOS 10.14 </span><a id="cupsAddDestMediaOptions">cupsAddDestMediaOptions</a></h3>
<p class="description">Add the option corresponding to the specified media size.</p>
<p class="code">
int cupsAddDestMediaOptions(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, unsigned flags, <a href="#cups_size_t">cups_size_t</a> *size, int num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
status, prior to resubmitting your request.
</p>
+<h3 class="function"><span class="info"> CUPS 2.3/macOS 10.14 </span><a id="cupsEncodeOption">cupsEncodeOption</a></h3>
+ <p class="description">Encode a single option into an IPP attribute.</p>
+<p class="code">
+<a href="#ipp_attribute_t">ipp_attribute_t</a> *cupsEncodeOption(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group_tag, const char *name, const char *value);</p>
+<h4 class="parameters">Parameters</h4>
+<table class="list"><tbody>
+<tr><th>ipp</th>
+ <td class="description">IPP request/response</td></tr>
+<tr><th>group_tag</th>
+ <td class="description">Attribute group</td></tr>
+<tr><th>name</th>
+ <td class="description">Option name</td></tr>
+<tr><th>value</th>
+ <td class="description">Option string value</td></tr>
+</tbody></table>
+<h4 class="returnvalue">Return Value</h4>
+ <p class="description">New attribute or <code>NULL</code> on error</p>
<h3 class="function"><a id="cupsEncodeOptions">cupsEncodeOptions</a></h3>
<p class="description">Encode printer options into IPP attributes.</p>
<p class="code">
<h4 class="parameters">Parameters</h4>
<table class="list"><tbody>
<tr><th>ipp</th>
- <td class="description">Request to add to</td></tr>
+ <td class="description">IPP request/response</td></tr>
<tr><th>num_options</th>
<td class="description">Number of options</td></tr>
<tr><th>options</th>
<h4 class="parameters">Parameters</h4>
<table class="list"><tbody>
<tr><th>ipp</th>
- <td class="description">Request to add to</td></tr>
+ <td class="description">IPP request/response</td></tr>
<tr><th>num_options</th>
<td class="description">Number of options</td></tr>
<tr><th>options</th>
<p class="description">Resolution units</p>
<p class="code">
typedef enum <a href="#ipp_res_e">ipp_res_e</a> ipp_res_t;
+</p>
+ <h3 class="typedef"><a id="ipp_rstate_t">ipp_rstate_t</a></h3>
+ <p class="description">resource-state values</p>
+ <p class="code">
+typedef enum <a href="#ipp_rstate_e">ipp_rstate_e</a> ipp_rstate_t;
+</p>
+ <h3 class="typedef"><a id="ipp_sstate_t">ipp_sstate_t</a></h3>
+ <p class="description">system-state values</p>
+ <p class="code">
+typedef enum <a href="#ipp_sstate_e">ipp_sstate_e</a> ipp_sstate_t;
</p>
<h3 class="typedef"><a id="ipp_state_t">ipp_state_t</a></h3>
<p class="description">ipp_t state values</p>
<tr><th>HTTP_FIELD_ACCEPT_LANGUAGE </th> <td class="description">Accept-Language field</td></tr>
<tr><th>HTTP_FIELD_ACCEPT_RANGES </th> <td class="description">Accept-Ranges field</td></tr>
<tr><th>HTTP_FIELD_ALLOW <span class="info"> CUPS 1.7/macOS 10.9 </span></th> <td class="description">Allow field </td></tr>
+ <tr><th>HTTP_FIELD_AUTHENTICATION_INFO <span class="info"> CUPS 2.2.9) </span></th> <td class="description">Authentication-Info field (</td></tr>
<tr><th>HTTP_FIELD_AUTHORIZATION </th> <td class="description">Authorization field</td></tr>
<tr><th>HTTP_FIELD_CONNECTION </th> <td class="description">Connection field</td></tr>
<tr><th>HTTP_FIELD_CONTENT_ENCODING </th> <td class="description">Content-Encoding field</td></tr>
<tr><th>IPP_FINISHINGS_EDGE_STITCH_RIGHT </th> <td class="description">Stitch along right side</td></tr>
<tr><th>IPP_FINISHINGS_EDGE_STITCH_TOP </th> <td class="description">Stitch along top edge</td></tr>
<tr><th>IPP_FINISHINGS_FOLD </th> <td class="description">Fold (any type)</td></tr>
- <tr><th>IPP_FINISHINGS_FOLD_ACCORDIAN </th> <td class="description">Accordian-fold the paper vertically into four sections</td></tr>
+ <tr><th>IPP_FINISHINGS_FOLD_ACCORDION </th> <td class="description">Accordion-fold the paper vertically into four sections</td></tr>
<tr><th>IPP_FINISHINGS_FOLD_DOUBLE_GATE </th> <td class="description">Fold the top and bottom quarters of the paper towards the midline, then fold in half vertically</td></tr>
<tr><th>IPP_FINISHINGS_FOLD_ENGINEERING_Z </th> <td class="description">Fold the paper vertically into two small sections and one larger, forming an elongated Z</td></tr>
<tr><th>IPP_FINISHINGS_FOLD_GATE </th> <td class="description">Fold the top and bottom quarters of the paper towards the midline</td></tr>
<tr><th>IPP_FINISHINGS_PUNCH_DUAL_LEFT </th> <td class="description">Punch 2 holes left side</td></tr>
<tr><th>IPP_FINISHINGS_PUNCH_DUAL_RIGHT </th> <td class="description">Punch 2 holes right side</td></tr>
<tr><th>IPP_FINISHINGS_PUNCH_DUAL_TOP </th> <td class="description">Punch 2 holes top edge</td></tr>
- <tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_BOTTOM </th> <td class="description">Pucnh multiple holes bottom edge</td></tr>
- <tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_LEFT </th> <td class="description">Pucnh multiple holes left side</td></tr>
- <tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_RIGHT </th> <td class="description">Pucnh multiple holes right side</td></tr>
- <tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_TOP </th> <td class="description">Pucnh multiple holes top edge</td></tr>
+ <tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_BOTTOM </th> <td class="description">Punch multiple holes bottom edge</td></tr>
+ <tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_LEFT </th> <td class="description">Punch multiple holes left side</td></tr>
+ <tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_RIGHT </th> <td class="description">Punch multiple holes right side</td></tr>
+ <tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_TOP </th> <td class="description">Punch multiple holes top edge</td></tr>
<tr><th>IPP_FINISHINGS_PUNCH_QUAD_BOTTOM </th> <td class="description">Punch 4 holes bottom edge</td></tr>
<tr><th>IPP_FINISHINGS_PUNCH_QUAD_LEFT </th> <td class="description">Punch 4 holes left side</td></tr>
<tr><th>IPP_FINISHINGS_PUNCH_QUAD_RIGHT </th> <td class="description">Punch 4 holes right side</td></tr>
<table class="list"><tbody>
<tr><th>IPP_RES_PER_CM </th> <td class="description">Pixels per centimeter</td></tr>
<tr><th>IPP_RES_PER_INCH </th> <td class="description">Pixels per inch</td></tr>
+</tbody></table>
+ <h3 class="enumeration"><a id="ipp_rstate_e">ipp_rstate_e</a></h3>
+ <p class="description">resource-state values</p>
+ <h4 class="constants">Constants</h4>
+ <table class="list"><tbody>
+ <tr><th>IPP_RSTATE_ABORTED </th> <td class="description">Resource has been aborted and is pending deletion.</td></tr>
+ <tr><th>IPP_RSTATE_AVAILABLE </th> <td class="description">Resource is available for installation.</td></tr>
+ <tr><th>IPP_RSTATE_CANCELED </th> <td class="description">Resource has been canceled and is pending deletion.</td></tr>
+ <tr><th>IPP_RSTATE_INSTALLED </th> <td class="description">Resource is installed.</td></tr>
+ <tr><th>IPP_RSTATE_PENDING </th> <td class="description">Resource is created but has no data yet.</td></tr>
+</tbody></table>
+ <h3 class="enumeration"><a id="ipp_sstate_e">ipp_sstate_e</a></h3>
+ <p class="description">system-state values</p>
+ <h4 class="constants">Constants</h4>
+ <table class="list"><tbody>
+ <tr><th>IPP_SSTATE_IDLE </th> <td class="description">At least one printer is idle and none are processing a job.</td></tr>
+ <tr><th>IPP_SSTATE_PROCESSING </th> <td class="description">At least one printer is processing a job.</td></tr>
+ <tr><th>IPP_SSTATE_STOPPED </th> <td class="description">All printers are stopped.</td></tr>
</tbody></table>
<h3 class="enumeration"><a id="ipp_state_e">ipp_state_e</a></h3>
<p class="description">ipp_t state values</p>
projects / thirdparty / cups.git / blobdiff