<html>
<!-- SECTION: Programming -->
<head>
- <title>CUPS API</title>
- <meta name='keywords' content='Programming'>
- <meta name='creator' content='Mini-XML v2.3'>
- <style type='text/css'><!--
- h1, h2, h3, p { font-family: sans-serif; text-align: justify; }
- tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }
- pre { font-weight: bold; color: #7f0000; margin-left: 2em; }
- span.info { background: #000000; border: solid thin #000000; color: #ffffff; font-size: 80%; font-style: italic; font-weight: bold; white-space: nowrap; }
- h3 span.info { float: right; font-size: 100%; }
- h1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }
- --></style>
+<title>CUPS API</title>
+<meta name="keywords" content="Programming">
+<meta name="creator" content="Mini-XML v2.5">
+<style type="text/css"><!--
+BODY {
+ font-family: lucida grande, geneva, helvetica, arial, sans-serif;
+}
+
+H1, H2, H3, H4, H5, H6, P, TD, TH {
+ font-family: lucida grande, geneva, helvetica, arial, sans-serif;
+}
+
+KBD {
+ font-family: monaco, courier, monospace;
+ font-weight: bold;
+}
+
+PRE {
+ font-family: monaco, courier, monospace;
+}
+
+PRE.command {
+ margin-left: 36pt;
+}
+
+PRE.example {
+ background: #eeeeee;
+ border: dotted thin #999999;
+ margin-left: 36pt;
+ padding: 10px;
+}
+
+PRE.command EM, PRE.example EM {
+ font-family: lucida grande, geneva, helvetica, arial, sans-serif;
+}
+
+P.command {
+ font-family: monaco, courier, monospace;
+ margin-left: 36pt;
+}
+
+P.formula {
+ font-style: italic;
+ margin-left: 36pt;
+}
+
+BLOCKQUOTE {
+ background: #cccccc;
+ border: solid thin #999999;
+ padding: 10pt;
+}
+
+A:link, A:visited {
+ font-weight: normal;
+ text-decoration: none;
+}
+
+A:link:hover, A:visited:hover, A:active {
+ text-decoration: underline;
+}
+
+SUB, SUP {
+ font-size: 50%;
+}
+
+DIV.table TABLE {
+ border: solid thin #999999;
+ border-collapse: collapse;
+ border-spacing: 0;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+DIV.table CAPTION {
+ caption-side: top;
+ font-size: 120%;
+ font-style: italic;
+ font-weight: bold;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+DIV.table TABLE TD {
+ border: solid thin #cccccc;
+ padding-top: 5pt;
+}
+
+DIV.table TABLE TH {
+ background: #cccccc;
+ border: none;
+ border-bottom: solid thin #999999;
+}
+
+DIV.figure TABLE {
+ margin-left: auto;
+ margin-right: auto;
+}
+
+DIV.figure CAPTION {
+ caption-side: bottom;
+ font-size: 120%;
+ font-style: italic;
+ font-weight: bold;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+TH.label {
+ padding-top: 5pt;
+ text-align: right;
+ vertical-align: top;
+}
+
+HR {
+ border: solid thin;
+}
+
+SPAN.info {
+ background: #000000;
+ border: thin solid #000000;
+ color: #ffffff;
+ font-size: 80%;
+ font-style: italic;
+ font-weight: bold;
+ white-space: nowrap;
+}
+
+H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
+ float: right;
+ font-size: 100%;
+}
+
+H2.title, H3.title {
+ border-bottom: solid 2pt #000000;
+}
+
+DT {
+ margin-left: 36pt;
+ margin-top: 12pt;
+}
+
+DD {
+ margin-left: 54pt;
+}
+
+DL.category DT {
+ font-weight: bold;
+}
+
+P.summary {
+ margin-left: 36pt;
+ font-family: monaco, courier, monospace;
+}
+
+SPAN.message {
+ font-style: italic;
+ font-size: smaller;
+}
+
+DIV.summary TABLE {
+ border: solid thin #999999;
+ border-collapse: collapse;
+ border-spacing: 0;
+ margin: 10px;
+}
+
+DIV.summary TABLE TD, DIV.summary TABLE TH {
+ border: solid thin #999999;
+ padding: 5px;
+ text-align: left;
+ vertical-align: top;
+}
+
+DIV.summary TABLE THEAD TH {
+ background: #eeeeee;
+}
+
+/* API documentation styles... */
+div.body h1 {
+ margin: 0;
+}
+div.body h2 {
+ margin-top: 1.5em;
+}
+div.body h3, div.body h4, div.body h5 {
+ margin-bottom: 0.5em;
+ margin-top: 1.5em;
+}
+.class, .enumeration, .function, .struct, .typedef, .union {
+ border-bottom: solid thin #999999;
+ margin-bottom: 0;
+ margin-top: 2em;
+}
+.description {
+ margin-top: 0.5em;
+}
+code, p.code, pre, ul.code li {
+ font-family: monaco, courier, monospace;
+ font-size: 90%;
+}
+ul.code, ul.contents, ul.subcontents {
+ list-style-type: none;
+ margin: 0;
+ padding-left: 0;
+}
+ul.code li {
+ margin: 0;
+}
+ul.contents > li {
+ margin-top: 1em;
+}
+ul.contents li ul.code, ul.contents li ul.subcontents {
+ padding-left: 2em;
+}
+div.body dl {
+ margin-left: 0;
+ margin-top: 0;
+}
+div.body dt {
+ font-style: italic;
+ margin-left: 0;
+ margin-top: 0;
+}
+div.body dd {
+ margin-bottom: 0.5em;
+}
+
+/* This is just for the HTML files generated with the framedhelp target */
+div.contents {
+ background: #e8e8e8;
+ border: solid thin black;
+ padding: 10px;
+}
+div.contents h1 {
+ font-size: 110%;
+}
+div.contents h2 {
+ font-size: 100%;
+}
+div.contents ul.contents {
+ font-size: 80%;
+}
+div.contents ul.subcontents li {
+ margin-left: 1em;
+ text-indent: -1em;
+}
+--></style>
</head>
<body>
+<div class='body'>
<!--
- "$Id: api-cups.shtml 5138 2006-02-21 10:49:06Z mike $"
+ "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
+
+ CUPS API header for the Common UNIX Printing System (CUPS).
+
+ Copyright 2008 by Apple Inc.
+
+ These coded instructions, statements, and computer programs are the
+ property of Apple Inc. and are protected by Federal copyright
+ law. Distribution and use rights are outlined in the file "LICENSE.txt"
+ which should have been included with this file. If this file is
+ file is missing or damaged, see the license at "http://www.cups.org/".
+-->
+
+<h1 class="title">CUPS API</h1>
+
+<div class='summary'><table summary='General Information'>
+<thead>
+<tr>
+ <th>Header</th>
+ <th>cups/cups.h</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+ <th>Library</th>
+ <td>-lcups</td>
+</tr>
+<tr>
+ <th>See Also</th>
+ <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br>
+ Programming: <a href='api-array.html' target='_top'>Array API</a><br>
+ Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
+ Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br>
+ Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
+ Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
+ Programming: <a href='api-raster.html' target='_top'>Raster API</a></td>
+</tr>
+</tbody>
+</table></div>
+<h2 class="title">Contents</h2>
+<ul class="contents">
+</li>
+<li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
+<li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li>
+<li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li>
+<li><a href="#OPTIONS">Options</a></li>
+<li><a href="#PRINT_JOBS">Print Jobs</a></li>
+<li><a href="#ERROR_HANDLING">Error Handling</a></li>
+<li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li>
+</ul></li>
+<li><a href="#FUNCTIONS">Functions</a><ul class="code">
+<li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li>
+<li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li>
+<li><a href="#cupsCancelJob" title="Cancel a print job on the default server.">cupsCancelJob</a></li>
+<li><a href="#cupsCancelJob2" title="Cancel or purge a print job.">cupsCancelJob2</a></li>
+<li><a href="#cupsCreateJob" title="Create an empty job for streaming.">cupsCreateJob</a></li>
+<li><a href="#cupsEncryption" title="Get the default encryption settings.">cupsEncryption</a></li>
+<li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li>
+<li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li>
+<li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li>
+<li><a href="#cupsFreeOptions" title="Free all memory used by options.">cupsFreeOptions</a></li>
+<li><a href="#cupsGetClasses" title="Get a list of printer classes from the default server.">cupsGetClasses</a></li>
+<li><a href="#cupsGetDefault" title="Get the default printer or class for the default server.">cupsGetDefault</a></li>
+<li><a href="#cupsGetDefault2" title="Get the default printer or class for the specified server.">cupsGetDefault2</a></li>
+<li><a href="#cupsGetDest" title="Get the named destination from the list.">cupsGetDest</a></li>
+<li><a href="#cupsGetDests" title="Get the list of destinations from the default server.">cupsGetDests</a></li>
+<li><a href="#cupsGetDests2" title="Get the list of destinations from the specified server.">cupsGetDests2</a></li>
+<li><a href="#cupsGetFd" title="Get a file from the server.">cupsGetFd</a></li>
+<li><a href="#cupsGetFile" title="Get a file from the server.">cupsGetFile</a></li>
+<li><a href="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</a></li>
+<li><a href="#cupsGetJobs2" title="Get the jobs from the specified server.">cupsGetJobs2</a></li>
+<li><a href="#cupsGetNamedDest" title="Get options for the named destination.">cupsGetNamedDest</a></li>
+<li><a href="#cupsGetOption" title="Get an option value.">cupsGetOption</a></li>
+<li><a href="#cupsGetPPD" title="Get the PPD file for a printer on the default server.">cupsGetPPD</a></li>
+<li><a href="#cupsGetPPD2" title="Get the PPD file for a printer from the specified server.">cupsGetPPD2</a></li>
+<li><a href="#cupsGetPPD3" title="Get the PPD file for a printer on the specified
+server if it has changed.">cupsGetPPD3</a></li>
+<li><a href="#cupsGetPassword" title="Get a password from the user.">cupsGetPassword</a></li>
+<li><a href="#cupsGetPrinters" title="Get a list of printers from the default server.">cupsGetPrinters</a></li>
+<li><a href="#cupsGetServerPPD" title="Get an available PPD file from the server.">cupsGetServerPPD</a></li>
+<li><a href="#cupsLangDefault" title="Return the default language.">cupsLangDefault</a></li>
+<li><a href="#cupsLangEncoding" title="Return the character encoding (us-ascii, etc.)
+for the given language.">cupsLangEncoding</a></li>
+<li><a href="#cupsLangFlush" title="Flush all language data out of the cache.">cupsLangFlush</a></li>
+<li><a href="#cupsLangFree" title="Free language data.">cupsLangFree</a></li>
+<li><a href="#cupsLangGet" title="Get a language.">cupsLangGet</a></li>
+<li><a href="#cupsLastError" title="Return the last IPP status code.">cupsLastError</a></li>
+<li><a href="#cupsLastErrorString" title="Return the last IPP status-message.">cupsLastErrorString</a></li>
+<li><a href="#cupsNotifySubject" title="Return the subject for the given notification message.">cupsNotifySubject</a></li>
+<li><a href="#cupsNotifyText" title="Return the text for the given notification message.">cupsNotifyText</a></li>
+<li><a href="#cupsParseOptions" title="Parse options from a command-line argument.">cupsParseOptions</a></li>
+<li><a href="#cupsPrintFile" title="Print a file to a printer or class on the default server.">cupsPrintFile</a></li>
+<li><a href="#cupsPrintFile2" title="Print a file to a printer or class on the specified
+server.">cupsPrintFile2</a></li>
+<li><a href="#cupsPrintFiles" title="Print one or more files to a printer or class on the
+default server.">cupsPrintFiles</a></li>
+<li><a href="#cupsPrintFiles2" title="Print one or more files to a printer or class on the
+specified server.">cupsPrintFiles2</a></li>
+<li><a href="#cupsPutFd" title="Put a file on the server.">cupsPutFd</a></li>
+<li><a href="#cupsPutFile" title="Put a file on the server.">cupsPutFile</a></li>
+<li><a href="#cupsRemoveDest" title="Remove a destination from the destination list.">cupsRemoveDest</a></li>
+<li><a href="#cupsRemoveOption" title="Remove an option from an option array.">cupsRemoveOption</a></li>
+<li><a href="#cupsServer" title="Return the hostname/address of the default server.">cupsServer</a></li>
+<li><a href="#cupsSetDefaultDest" title="Set the default destination.">cupsSetDefaultDest</a></li>
+<li><a href="#cupsSetDests" title="Save the list of destinations for the default server.">cupsSetDests</a></li>
+<li><a href="#cupsSetDests2" title="Save the list of destinations for the specified server.">cupsSetDests2</a></li>
+<li><a href="#cupsSetEncryption" title="Set the encryption preference.">cupsSetEncryption</a></li>
+<li><a href="#cupsSetPasswordCB" title="Set the password callback for CUPS.">cupsSetPasswordCB</a></li>
+<li><a href="#cupsSetServer" title="Set the default server name.">cupsSetServer</a></li>
+<li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li>
+<li><a href="#cupsStartDocument" title="Add a document to a job created with cupsCreateJob().">cupsStartDocument</a></li>
+<li><a href="#cupsTempFd" title="Creates a temporary file.">cupsTempFd</a></li>
+<li><a href="#cupsTempFile" title="Generates a temporary filename.">cupsTempFile</a></li>
+<li><a href="#cupsTempFile2" title="Creates a temporary CUPS file.">cupsTempFile2</a></li>
+<li><a href="#cupsUser" title="Return the current user's name.">cupsUser</a></li>
+</ul>
+<li><a href="#TYPES">Data Types</a><ul class="code">
+ <li><a href="#cups_dest_t" title="Destination">cups_dest_t</a></li>
+ <li><a href="#cups_job_t" title="Job">cups_job_t</a></li>
+ <li><a href="#cups_option_t" title="Printer Options">cups_option_t</a></li>
+ <li><a href="#cups_password_cb_t" title="Password callback">cups_password_cb_t</a></li>
+ <li><a href="#cups_ptype_t" title="Printer type/capability bits">cups_ptype_t</a></li>
+</ul></li>
+<li><a href="#STRUCTURES">Structures</a><ul class="code">
+ <li><a href="#cups_dest_s" title="Destination">cups_dest_s</a></li>
+ <li><a href="#cups_job_s" title="Job">cups_job_s</a></li>
+ <li><a href="#cups_option_s" title="Printer Options">cups_option_s</a></li>
+</ul></li>
+<li><a href="#ENUMERATIONS">Constants</a><ul class="code">
+ <li><a href="#cups_ptype_e" title="Printer type/capability bit constants">cups_ptype_e</a></li>
+</ul></li>
+</ul>
+<!--
+ "$Id: api-cups.shtml 7337 2008-02-22 04:44:04Z mike $"
CUPS API introduction for the Common UNIX Printing System (CUPS).
- Copyright 1997-2006 by Easy Software Products.
+ Copyright 2007-2008 by Apple Inc.
+ Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
- property of Easy Software Products and are protected by Federal
- copyright law. Distribution and use rights are outlined in the file
- "LICENSE.txt" which should have been included with this file. If this
- file is missing or damaged please contact Easy Software Products
- at:
-
- Attn: CUPS Licensing Information
- Easy Software Products
- 44141 Airport View Drive, Suite 204
- Hollywood, Maryland 20636 USA
-
- Voice: (301) 373-9600
- EMail: cups-info@cups.org
- WWW: http://www.cups.org
+ property of Apple Inc. and are protected by Federal copyright
+ law. Distribution and use rights are outlined in the file "LICENSE.txt"
+ which should have been included with this file. If this file is
+ file is missing or damaged, see the license at "http://www.cups.org/".
-->
-<h2 class='title'>Introduction</h2>
+<h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
+
+<p>The CUPS API provides the convenience functions needed to support
+applications, filters, printer drivers, and backends that need to interface
+with the CUPS scheduler.</p>
+
+<h3><a name='CLIENTS_AND_SERVERS'>Clients and Servers</a></h3>
+
+<p>CUPS is based on the Internet Printing Protocol ("IPP"), which allows
+clients (applications) to communicate with a server (the scheduler) to get a
+list of printers, 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>. All of the examples in this document use the
+<code>CUPS_HTTP_DEFAULT</code> constant, referring to the default connection
+to the scheduler. The <a href='api-httpipp.html' target='_top'>HTTP and IPP
+APIs</a> document provides more information on server connections.</p>
-<p>The CUPS library provides a whole collection of interfaces
-needed to support the internal needs of the CUPS software as well
-as the needs of applications, filters, printer drivers, and
-backends.</p>
+<h3><a name='PRINTERS_AND_CLASSES'>Printers and Classes</a></h3>
-<p>Unlike the rest of CUPS, the CUPS API library is provided
-under the GNU Library General Public License. This means that you
-can use the CUPS API library in both proprietary and open-source
-programs.</p>
+<p>Printers and classes (collections of printers) are accessed through
+the <a href="#cups_dest_t"><code>cups_dest_t</code></a> structure which
+includes the name (<code>name</code>), instance (<code>instance</code> -
+a way of selecting certain saved options/settings), and the options and
+attributes associated with that destination (<code>num_options</code> and
+<code>options</code>). Destinations are created using the
+<a href="#cupsGetDests"><code>cupsGetDests</code></a> function and freed
+using the <a href='#cupsFreeDests'><code>cupsFreeDests</code></a> function.
+The <a href='#cupsGetDest'><code>cupsGetDest</code></a> function finds a
+specific destination for printing:</p>
-<h2 class='title'>General Usage</h2>
+<pre class='example'>
+#include <cups/cups.h>
-<p>The <var><cups/cups.h></var> header file must be included to
-use the CUPS functions.</p>
+<a href='#cups_dest_t'>cups_dest_t</a> *dests;
+int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests);
+<a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests);
-<p>Programs using these functions must be linked to the CUPS
-library: <var>libcups.a</var>, <var>libcups.so.2</var>,
-<var>libcups.2.dylib</var>, <var>libcups_s.a</var>, or
-<var>libcups2.lib</var> depending on the platform. The following
-command compiles <var>myprogram.c</var> using GCC and the CUPS
-library:</p>
+/* do something wiith dest */
-<pre class='command'>
-<kbd>gcc -o myprogram myprogram.c -lcups</kbd>
+<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
</pre>
-<h2 class='title'>Compatibility</h2>
+<p>Passing <code>NULL</code> to
+<a href='#cupsGetDest'><code>cupsGetDest</code></a> for the destination name
+will return the default destination. Similarly, passing a <code>NULL</code>
+instance will return the default instance for that destination.</p>
-<p>Unless otherwise specified, the CUPS API functions require
-CUPS 1.1 or higher.</p>
-<h2 class='title'>Contents</h2>
-<ul>
- <li><a href='#ENUMERATIONS'>Enumerations</a></li>
- <li><a href='#FUNCTIONS'>Functions</a></li>
- <li><a href='#STRUCTURES'>Structures</a></li>
- <li><a href='#TYPES'>Types</a></li>
-</ul>
-<!-- NEW PAGE -->
-<h2 class='title'><a name='ENUMERATIONS'>Enumerations</a></h2>
-<ul>
- <li><a href='#cups_ptype_e'><tt>cups_ptype_e</tt></a> </li>
-</ul>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cups_ptype_e'>cups_ptype_e</a></h3>
-<h4>Description</h4>
-<p>Not a typedef'd enum so we can OR</p>
-<h4>Values</h4>
-<div class='table'><table align='center' border='1' width='80%'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
+<div class='table'><table summary='Table 1: Printer Attributes' width='80%'>
+<caption>Table 1: <a name='TABLE1'>Printer Attributes</a></caption>
+<thead>
+<tr>
+ <th>Attribute Name</th>
+ <th>Description</th>
+</tr>
+</thead>
<tbody>
-<tr><td><tt>CUPS_PRINTER_AUTHENTICATED</tt> <span class='info'> CUPS 1.2 </span></td><td>Printer requires authentication </td></tr>
-<tr><td><tt>CUPS_PRINTER_BIND</tt> </td><td>Can bind output</td></tr>
-<tr><td><tt>CUPS_PRINTER_BW</tt> </td><td>Can do B&W printing</td></tr>
-<tr><td><tt>CUPS_PRINTER_CLASS</tt> </td><td>Printer class</td></tr>
-<tr><td><tt>CUPS_PRINTER_COLLATE</tt> </td><td>Can collage copies</td></tr>
-<tr><td><tt>CUPS_PRINTER_COLOR</tt> </td><td>Can do color printing</td></tr>
-<tr><td><tt>CUPS_PRINTER_COMMANDS</tt> <span class='info'> CUPS 1.2 </span></td><td>Printer supports maintenance commands </td></tr>
-<tr><td><tt>CUPS_PRINTER_COPIES</tt> </td><td>Can do copies</td></tr>
-<tr><td><tt>CUPS_PRINTER_COVER</tt> </td><td>Can cover output</td></tr>
-<tr><td><tt>CUPS_PRINTER_DEFAULT</tt> </td><td>Default printer on network</td></tr>
-<tr><td><tt>CUPS_PRINTER_DELETE</tt> <span class='info'> CUPS 1.2 </span></td><td>Delete printer </td></tr>
-<tr><td><tt>CUPS_PRINTER_DUPLEX</tt> </td><td>Can do duplexing</td></tr>
-<tr><td><tt>CUPS_PRINTER_FAX</tt> </td><td>Fax queue</td></tr>
-<tr><td><tt>CUPS_PRINTER_IMPLICIT</tt> </td><td>Implicit class</td></tr>
-<tr><td><tt>CUPS_PRINTER_LARGE</tt> </td><td>Can do D/E/A1/A0</td></tr>
-<tr><td><tt>CUPS_PRINTER_LOCAL</tt> </td><td>Local printer or class</td></tr>
-<tr><td><tt>CUPS_PRINTER_MEDIUM</tt> </td><td>Can do Tabloid/B/C/A3/A2</td></tr>
-<tr><td><tt>CUPS_PRINTER_NOT_SHARED</tt> <span class='info'> CUPS 1.2 </span></td><td>Printer is not shared </td></tr>
-<tr><td><tt>CUPS_PRINTER_OPTIONS</tt> </td><td>~(CLASS | REMOTE | IMPLICIT)</td></tr>
-<tr><td><tt>CUPS_PRINTER_PUNCH</tt> </td><td>Can punch output</td></tr>
-<tr><td><tt>CUPS_PRINTER_REJECTING</tt> </td><td>Printer is rejecting jobs</td></tr>
-<tr><td><tt>CUPS_PRINTER_REMOTE</tt> </td><td>Remote printer or class</td></tr>
-<tr><td><tt>CUPS_PRINTER_SMALL</tt> </td><td>Can do Letter/Legal/A4</td></tr>
-<tr><td><tt>CUPS_PRINTER_SORT</tt> </td><td>Can sort output</td></tr>
-<tr><td><tt>CUPS_PRINTER_STAPLE</tt> </td><td>Can staple output</td></tr>
-<tr><td><tt>CUPS_PRINTER_VARIABLE</tt> </td><td>Can do variable sizes</td></tr>
-</tbody></table></div>
-<!-- NEW PAGE -->
-<h2 class='title'><a name='FUNCTIONS'>Functions</a></h2>
-<ul>
- <li><a href='#cupsAddDest'><tt>cupsAddDest()</tt></a> </li>
- <li><a href='#cupsAddOption'><tt>cupsAddOption()</tt></a> </li>
- <li><a href='#cupsCancelJob'><tt>cupsCancelJob()</tt></a> </li>
- <li><a href='#cupsEncryption'><tt>cupsEncryption()</tt></a> </li>
- <li><a href='#cupsFreeDests'><tt>cupsFreeDests()</tt></a> </li>
- <li><a href='#cupsFreeJobs'><tt>cupsFreeJobs()</tt></a> </li>
- <li><a href='#cupsFreeOptions'><tt>cupsFreeOptions()</tt></a> </li>
- <li><a href='#cupsGetClasses'><tt>cupsGetClasses()</tt></a> <span class='info'> DEPRECATED </span></li>
- <li><a href='#cupsGetDefault'><tt>cupsGetDefault()</tt></a> </li>
- <li><a href='#cupsGetDefault2'><tt>cupsGetDefault2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
- <li><a href='#cupsGetDest'><tt>cupsGetDest()</tt></a> </li>
- <li><a href='#cupsGetDests'><tt>cupsGetDests()</tt></a> </li>
- <li><a href='#cupsGetDests2'><tt>cupsGetDests2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
- <li><a href='#cupsGetFd'><tt>cupsGetFd()</tt></a> <span class='info'> CUPS 1.1.20 </span></li>
- <li><a href='#cupsGetFile'><tt>cupsGetFile()</tt></a> <span class='info'> CUPS 1.1.20 </span></li>
- <li><a href='#cupsGetJobs'><tt>cupsGetJobs()</tt></a> </li>
- <li><a href='#cupsGetJobs2'><tt>cupsGetJobs2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
- <li><a href='#cupsGetOption'><tt>cupsGetOption()</tt></a> </li>
- <li><a href='#cupsGetPPD'><tt>cupsGetPPD()</tt></a> </li>
- <li><a href='#cupsGetPPD2'><tt>cupsGetPPD2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
- <li><a href='#cupsGetPassword'><tt>cupsGetPassword()</tt></a> </li>
- <li><a href='#cupsGetPrinters'><tt>cupsGetPrinters()</tt></a> <span class='info'> DEPRECATED </span></li>
- <li><a href='#cupsLangDefault'><tt>cupsLangDefault()</tt></a> </li>
- <li><a href='#cupsLangEncoding'><tt>cupsLangEncoding()</tt></a> </li>
- <li><a href='#cupsLangFlush'><tt>cupsLangFlush()</tt></a> </li>
- <li><a href='#cupsLangFree'><tt>cupsLangFree()</tt></a> </li>
- <li><a href='#cupsLangGet'><tt>cupsLangGet()</tt></a> </li>
- <li><a href='#cupsLastError'><tt>cupsLastError()</tt></a> </li>
- <li><a href='#cupsLastErrorString'><tt>cupsLastErrorString()</tt></a> <span class='info'> CUPS 1.2 </span></li>
- <li><a href='#cupsMarkOptions'><tt>cupsMarkOptions()</tt></a> </li>
- <li><a href='#cupsParseOptions'><tt>cupsParseOptions()</tt></a> </li>
- <li><a href='#cupsPrintFile'><tt>cupsPrintFile()</tt></a> </li>
- <li><a href='#cupsPrintFile2'><tt>cupsPrintFile2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
- <li><a href='#cupsPrintFiles'><tt>cupsPrintFiles()</tt></a> </li>
- <li><a href='#cupsPrintFiles2'><tt>cupsPrintFiles2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
- <li><a href='#cupsPutFd'><tt>cupsPutFd()</tt></a> <span class='info'> CUPS 1.1.20 </span></li>
- <li><a href='#cupsPutFile'><tt>cupsPutFile()</tt></a> <span class='info'> CUPS 1.1.20 </span></li>
- <li><a href='#cupsRemoveOption'><tt>cupsRemoveOption()</tt></a> <span class='info'> CUPS 1.2 </span></li>
- <li><a href='#cupsServer'><tt>cupsServer()</tt></a> </li>
- <li><a href='#cupsSetDests'><tt>cupsSetDests()</tt></a> </li>
- <li><a href='#cupsSetDests2'><tt>cupsSetDests2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
- <li><a href='#cupsSetEncryption'><tt>cupsSetEncryption()</tt></a> </li>
- <li><a href='#cupsSetPasswordCB'><tt>cupsSetPasswordCB()</tt></a> </li>
- <li><a href='#cupsSetServer'><tt>cupsSetServer()</tt></a> </li>
- <li><a href='#cupsSetUser'><tt>cupsSetUser()</tt></a> </li>
- <li><a href='#cupsTempFd'><tt>cupsTempFd()</tt></a> </li>
- <li><a href='#cupsTempFile'><tt>cupsTempFile()</tt></a> <span class='info'> DEPRECATED </span></li>
- <li><a href='#cupsTempFile2'><tt>cupsTempFile2()</tt></a> <span class='info'> CUPS 1.2 </span></li>
- <li><a href='#cupsUser'><tt>cupsUser()</tt></a> </li>
-</ul>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsAddDest'>cupsAddDest()</a></h3>
-<h4>Description</h4>
-<p>Add a destination to the list of destinations.
-
-Use the cupsSaveDests() function to save the updated list of destinations
-to the user's lpoptions file.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsAddDest(
- const char * name,
- const char * instance,
- int num_dests,
- <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
+<tr>
+ <td>"auth-info-required"</td>
+ <td>The type of authentication required for printing to this
+ destination: "none", "username,password", "domain,username,password",
+ or "negotiate" (Kerberos)</td>
+</tr>
+<tr>
+ <td>"printer-info"</td>
+ <td>The human-readable description of the destination such as "My
+ Laser Printer".</td>
+</tr>
+<tr>
+ <td>"printer-is-accepting-jobs"</td>
+ <td>"1" if the destination is accepting new jobs, "0" if not.</td>
+</tr>
+<tr>
+ <td>"printer-is-shared"</td>
+ <td>"1" if the destination is being shared with other computers, "0" if
+ not.</td>
+</tr>
+<tr>
+ <td>"printer-location"</td>
+ <td>The human-readable location of the destination such as "Lab 4".</td>
+</tr>
+<tr>
+ <td>"printer-make-and-model"</td>
+ <td>The human-readable make and model of the destination such as "HP
+ LaserJet 4000 Series".</td>
+</tr>
+<tr>
+ <td>"printer-state"</td>
+ <td>"3" if the destination is idle, "4" if the destination is printing
+ a job, and "5" if the destination is stopped.</td>
+</tr>
+<tr>
+ <td>"printer-state-change-time"</td>
+ <td>The UNIX time when the destination entered the current state.</td>
+</tr>
+<tr>
+ <td>"printer-state-reasons"</td>
+ <td>Additional comma-delimited state keywords for the destination
+ such as "media-tray-empty-error" and "toner-low-warning".</td>
+</tr>
+<tr>
+ <td>"printer-type"</td>
+ <td>The <a href='#cups_printer_t'><code>cups_printer_t</code></a>
+ value associated with the destination.</td>
+</tr>
+</tbody>
+</table></div>
+
+<h3><a name='OPTIONS'>Options</a></h3>
+
+<p>Options are stored in arrays of
+<a href='#cups_option_t'><code>cups_option_t</code></a> structures. Each
+option has a name (<code>name</code>) and value (<code>value</code>)
+associated with it. The <a href='#cups_dest_t'><code>cups_dest_t</code></a>
+<code>num_options</code> and <code>options</code> members contain the
+default options for a particular destination, along with several informational
+attributes about the destination as shown in <a href='#TABLE1'>Table 1</a>.
+The <a href='#cupsGetOption'><code>cupsGetOption</code></a> function gets
+the value for the named option. For example, the following code lists the
+available destinations and their human-readable descriptions:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
+<a href='#cups_dest_t'>cups_dest_t</a> *dests;
+int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests);
+<a href='#cups_dest_t'>cups_dest_t</a> *dest;
+int i;
+const char *value;
+
+for (i = num_dests, dest = dests; i > 0; i --, dest ++)
+ if (dest->instance == NULL)
+ {
+ value = <a href='#cupsGetOption'>cupsGetOption</a>("printer-info", dest->num_options, dest->options);
+ printf("%s (%s)\n", dest->name, value ? value : "no description");
+ }
+
+<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt></td><td>Name of destination</td></tr>
-<tr><td><tt>instance</tt></td><td>Instance of destination or NULL for none/primary</td></tr>
-<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
-<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>New number of destinations</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsAddOption'>cupsAddOption()</a></h3>
-<h4>Description</h4>
-<p>Add an option to an option array.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsAddOption(
- const char * name,
- const char * value,
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> ** options);
+
+<p>You can create your own option arrays using the
+<a href='#cupsAddOption'><code>cupsAddOption</code></a> function, which
+adds a single named option to an array:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
+int num_options = 0;
+<a href='#cups_option_t'>cups_option_t</a> *options = NULL;
+
+/* The returned num_options value is updated as needed */
+num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "value", num_options, &options);
+
+/* This adds a second option value */
+num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &options);
+
+/* This replaces the first option we added */
+num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &options);
</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt></td><td>Name of option</td></tr>
-<tr><td><tt>value</tt></td><td>Value of option</td></tr>
-<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Pointer to options</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Number of options</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsCancelJob'>cupsCancelJob()</a></h3>
-<h4>Description</h4>
-<p>Cancel a print job on the default server.
-
-Use the cupsLastError() and cupsLastErrorString() functions to get
-the cause of any failure.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsCancelJob(
- const char * name,
- int job);
+
+<p>Use a <code>for</code> loop to copy the options from a destination:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
+int i;
+int num_options = 0;
+<a href='#cups_option_t'>cups_option_t</a> *options = NULL;
+<a href='#cups_dest_t'>cups_dest_t</a> *dest;
+
+for (i = 0; i < dest->num_options; i ++)
+ num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value,
+ num_options, &options);
</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt></td><td>Name of printer or class</td></tr>
-<tr><td><tt>job</tt></td><td>Job ID</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>1 on success, 0 on failure</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsEncryption'>cupsEncryption()</a></h3>
-<h4>Description</h4>
-<p>Get the default encryption settings.
-
-The default encryption setting comes from the CUPS_ENCRYPTION
-environment variable, then the ~/.cupsrc file, and finally the
-/etc/cups/client.conf file. If not set, the default is
-HTTP_ENCRYPT_IF_REQUESTED.</p>
-<h4>Syntax</h4>
-<pre>
-http_encryption_t
-cupsEncryption(void);
+
+<p>Use the <a href='#cupsFreeOptions'><code>cupsFreeOptions</code></a>
+function to free the options array when you are done using it:</p>
+
+<pre class='example'>
+<a href='#cupsFreeOptions'>cupsFreeOptions</a>(num_options, options);
</pre>
-<h4>Arguments</h4>
-<p>None.</p>
-<h4>Returns</h4>
-<p>Encryption settings</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsFreeDests'>cupsFreeDests()</a></h3>
-<h4>Description</h4>
-<p>Free the memory used by the list of destinations.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsFreeDests(
- int num_dests,
- <a href='#cups_dest_t'>cups_dest_t</a> * dests);
+
+<h3><a name='PRINT_JOBS'>Print Jobs</a></h3>
+
+<p>Print jobs are identified by a locally-unique job ID number from 1 to
+2<sup>31</sup>-1 and have options and one or more files for printing to a
+single destination. The <a href='#cupsPrintFile'><code>cupsPrintFile</code></a>
+function creates a new job with one file. The following code prints the CUPS
+test page file:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
+<a href='#cups_dest_t'>cups_dest_t</a> *dest;
+int num_options;
+<a href='#cups_option_t'>cups_option_t</a> *options;
+int job_id;
+
+/* Print a single file */
+job_id = <a href='#cupsPrintFile'>cupsPrintFile</a>(dest->name, "/usr/share/cups/data/testprint.ps",
+ "Test Print", num_options, options);
</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
-<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsFreeJobs'>cupsFreeJobs()</a></h3>
-<h4>Description</h4>
-<p>Free memory used by job data.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsFreeJobs(
- int num_jobs,
- <a href='#cups_job_t'>cups_job_t</a> * jobs);
+
+<p>The <a href='#cupsPrintFiles'><code>cupsPrintFiles</code></a> function
+creates a job with multiple files. The files are provided in a
+<code>char *</code> array:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
+<a href='#cups_dest_t'>cups_dest_t</a> *dest;
+int num_options;
+<a href='#cups_option_t'>cups_option_t</a> *options;
+int job_id;
+char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" };
+
+/* Print three files */
+job_id = <a href='#cupsPrintFiles'>cupsPrintFiles</a>(dest->name, 3, files, "Test Print", num_options, options);
</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>num_jobs</tt></td><td>Number of jobs</td></tr>
-<tr><td><tt>jobs</tt></td><td>Jobs</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsFreeOptions'>cupsFreeOptions()</a></h3>
-<h4>Description</h4>
-<p>Free all memory used by options.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsFreeOptions(
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> * options);
+
+<p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a>
+function creates a new job with no files in it. Files are added using the
+<a href='#cupsStartDocument'><code>cupsStartDocument</code></a>,
+<a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>,
+and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions.
+The following example creates a job with 10 text files for printing:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
+<a href='#cups_dest_t'>cups_dest_t</a> *dest;
+int num_options;
+<a href='#cups_option_t'>cups_option_t</a> *options;
+int job_id;
+int i;
+char buffer[1024];
+
+/* Create the job */
+job_id = <a href='#cupsCreateJob'>cupsCreateJob</a>(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files",
+ num_options, options);
+
+/* If the job is created, add 10 files */
+if (job_id > 0)
+{
+ for (i = 1; i <= 10; i ++)
+ {
+ snprintf(buffer, sizeof(buffer), "file%d.txt", i);
+
+ <a href='#cupsStartDocument'>cupsStartDocument</a>(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer,
+ CUPS_FORMAT_TEXT, i == 10);
+
+ snprintf(buffer, sizeof(buffer),
+ "File %d\n"
+ "\n"
+ "One fish,\n"
+ "Two fish,\n
+ "Red fish,\n
+ "Blue fish\n", i);
+
+ /* cupsWriteRequestData can be called as many times as needed */
+ <a href='#cupsWriteRequestData'>cupsWriteRequestData</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));
+
+ <a href='#cupsFinishDocument'>cupsFinishDocument</a>(CUPS_HTTP_DEFAULT, dest->name);
+ }
+}
</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Pointer to options</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> DEPRECATED </span><a name='cupsGetClasses'>cupsGetClasses()</a></h3>
-<h4>Description</h4>
-<p>Get a list of printer classes from the default server.
-
-This function is deprecated - use cupsGetDests() instead.
-</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsGetClasses(
- char *** classes);
+<p>Once you have created a job, you can monitor its status using the
+<a href='#cupsGetJobs'><code>cupsGetJobs</code></a> function, which returns
+an array of <a href='#cups_job_t'><code>cups_job_t</code></a> structures.
+Each contains the job ID (<code>id</code>), destination name
+(<code>dest</code>), title (<code>title</code>), and other information
+associated with the job. The job array is freed using the
+<a href='#cupsFreeJobs'><code>cupsFreeJobs</code></a> function. The following
+example monitors a specific job ID, showing the current job state once every
+5 seconds until the job is completed:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
+<a href='#cups_dest_t'>cups_dest_t</a> *dest;
+int job_id;
+int num_jobs;
+<a href='#cups_job_t'>cups_job_t</a> *jobs;
+int i;
+ipp_jstate_t job_state = IPP_JOB_PENDING;
+
+while (job_state < IPP_JOB_STOPPED)
+{
+ /* Get my jobs (1) with any state (-1) */
+ num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&jobs, dest->name, 1, -1);
+
+ /* Loop to find my job */
+ job_state = IPP_JOB_COMPLETED;
+
+ for (i = 0; i < num_jobs; i ++)
+ if (jobs[i].id == job_id)
+ {
+ job_state = jobs[i].state;
+ break;
+ }
+
+ /* Free the job array */
+ <a href='#cupsFreeJobs'>cupsFreeJobs</a>(num_jobs, jobs);
+
+ /* Show the current state */
+ switch (job_state)
+ {
+ case IPP_JOB_PENDING :
+ printf("Job %d is pending.\n", job_id);
+ break;
+ case IPP_JOB_HELD :
+ printf("Job %d is held.\n", job_id);
+ break;
+ case IPP_JOB_PROCESSING :
+ printf("Job %d is processing.\n", job_id);
+ break;
+ case IPP_JOB_STOPPED :
+ printf("Job %d is stopped.\n", job_id);
+ break;
+ case IPP_JOB_CANCELED :
+ printf("Job %d is canceled.\n", job_id);
+ break;
+ case IPP_JOB_ABORTED :
+ printf("Job %d is aborted.\n", job_id);
+ break;
+ case IPP_JOB_COMPLETED :
+ printf("Job %d is completed.\n", job_id);
+ break;
+ }
+
+ /* Sleep if the job is not finished */
+ if (job_state < IPP_JOB_STOPPED)
+ sleep(5);
+}
</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>classes</tt></td><td>Classes</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Number of classes</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsGetDefault'>cupsGetDefault()</a></h3>
-<h4>Description</h4>
-<p>Get the default printer or class for the default server.
-
-This function returns the default printer or class as defined by
-the LPDEST or PRINTER environment variables. If these environment
-variables are not set, the server default destination is returned.
-Applications should use the cupsGetDests() and cupsGetDest() functions
-to get the user-defined default printer, as this function does not
-support the lpoptions-defined default printer.</p>
-<h4>Syntax</h4>
-<pre>
+
+<p>To cancel a job, use the
+<a href='#cupsCancelJob'><code>cupsCancelJob</code></a> function with the
+job ID:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
+<a href='#cups_dest_t'>cups_dest_t</a> *dest;
+int job_id;
+
+<a href='#cupsCancelJob'>cupsCancelJob</a>(dest->name, job_id);
+</pre>
+
+<h3><a name='ERROR_HANDLING'>Error Handling</a></h3>
+
+<p>If any of the CUPS API printing functions returns an error, the reason for
+that error can be found by calling the
+<a href='#cupsLastError'><code>cupsLastError</code></a> and
+<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> functions.
+<a href='#cupsLastError'><code>cupsLastError</code></a> returns the last IPP
+error code
+(<a href='api-httpipp.html#ipp_status_t'><code>ipp_status_t</code></a>)
+that was encountered, while
+<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> returns
+a (localized) human-readable string that can be shown to the user. For example,
+if any of the job creation functions returns a job ID of 0, you can use
+<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> to show
+the reason why the job could not be created:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
+int job_id;
+
+if (job_id == 0)
+ puts(cupsLastErrorString());
+</pre>
+
+<h3><a name='PASSWORDS_AND_AUTHENTICATION'>Passwords and Authentication</a></h3>
+
+<p>CUPS supports authentication of any request, including submission of print
+jobs. The default mechanism for getting the username and password is to use the
+login user and a password from the console.</p>
+
+<p>To support other types of applications, in particular Graphical User
+Interfaces ("GUIs"), the CUPS API provides functions to set the default
+username and to register a callback function that returns a password string.</p>
+
+<p>The <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a>
+function is used to set a password callback in your program. Only one
+function can be used at any time.</p>
+
+<p>The <a href="#cupsSetUser"><code>cupsSetUser</code></a> function sets the
+current username for authentication. This function can be called by your
+password callback function to change the current username as needed.</p>
+
+<p>The following example shows a simple password callback that gets a
+username and password from the user:</p>
+
+<pre class='example'>
+#include <cups/cups.h>
+
const char *
-cupsGetDefault(void);
+my_password_cb(const char *prompt)
+{
+ char user[65];
+
+
+ puts(prompt);
+
+ /* Get a username from the user */
+ printf("Username: ");
+ if (fgets(user, sizeof(user), stdin) == NULL)
+ return (NULL);
+
+ /* Strip the newline from the string and set the user */
+ user[strlen(user) - 1] = '\0';
+
+ <a href='#cupsSetUser'>cupsSetUser</a>(user);
+
+ /* Use getpass() to ask for the password... */
+ return (getpass("Password: "));
+}
+
+<a href='#cupsSetPasswordCB'>cupsSetPasswordCB</a>(my_password_cb);
</pre>
-<h4>Arguments</h4>
-<p>None.</p>
-<h4>Returns</h4>
-<p>Default printer or NULL</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsGetDefault2'>cupsGetDefault2()</a></h3>
-<h4>Description</h4>
-<p>Get the default printer or class for the specified server.
-
-This function returns the default printer or class as defined by
+
+<p>Similarly, a GUI could display the prompt string in a window with input
+fields for the username and password. The username should default to the
+string returned by the <a href="#cupsUser"><code>cupsUser</code></a>
+function.</p>
+<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
+<h3 class="function"><a name="cupsAddDest">cupsAddDest</a></h3>
+<p class="description">Add a destination to the list of destinations.</p>
+<p class="code">
+int cupsAddDest (<br>
+ const char *name,<br>
+ const char *instance,<br>
+ int num_dests,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> **dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>instance</dt>
+<dd class="description">Instance name or <code>NULL</code> for none/primary</dd>
+<dt>num_dests</dt>
+<dd class="description">Number of destinations</dd>
+<dt>dests</dt>
+<dd class="description">Destinations</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">New number of destinations</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function cannot be used to add a new class or printer queue,
+it only adds a new container of saved options for the named
+destination or instance.<br>
+<br>
+If the named destination already exists, the destination list is
+returned unchanged. Adding a new instance of a destination creates
+a copy of that destination's options.<br>
+<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"><a name="cupsAddOption">cupsAddOption</a></h3>
+<p class="description">Add an option to an option array.</p>
+<p class="code">
+int cupsAddOption (<br>
+ const char *name,<br>
+ const char *value,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> **options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Name of option</dd>
+<dt>value</dt>
+<dd class="description">Value of option</dd>
+<dt>num_options</dt>
+<dd class="description">Number of options</dd>
+<dt>options</dt>
+<dd class="description">Pointer to options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of options</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">New option arrays can be initialized simply by passing 0 for the
+"num_options" parameter.</p>
+<h3 class="function"><a name="cupsCancelJob">cupsCancelJob</a></h3>
+<p class="description">Cancel a print job on the default server.</p>
+<p class="code">
+int cupsCancelJob (<br>
+ const char *name,<br>
+ int job_id<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Name of printer or class</dd>
+<dt>job_id</dt>
+<dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on success, 0 on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code>
+to cancel the current job on the named destination.<br>
+<br>
+Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get
+the cause of any failure.</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsCancelJob2">cupsCancelJob2</a></h3>
+<p class="description">Cancel or purge a print job.</p>
+<p class="code">
+ipp_status_t cupsCancelJob2 (<br>
+ http_t *http,<br>
+ const char *name,<br>
+ int job_id,<br>
+ int purge<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>name</dt>
+<dd class="description">Name of printer or class</dd>
+<dt>job_id</dt>
+<dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd>
+<dt>purge</dt>
+<dd class="description">1 to purge, 0 to cancel</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">IPP status</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Canceled jobs remain in the job history while purged jobs are removed
+from the job history.<br>
+<br>
+Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code>
+to cancel the current job on the named destination.<br>
+<br>
+Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get
+the cause of any failure.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsCreateJob">cupsCreateJob</a></h3>
+<p class="description">Create an empty job for streaming.</p>
+<p class="code">
+int cupsCreateJob (<br>
+ http_t *http,<br>
+ const char *name,<br>
+ const char *title,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>title</dt>
+<dd class="description">Title of job</dd>
+<dt>num_options</dt>
+<dd class="description">Number of options</dd>
+<dt>options</dt>
+<dd class="description">Options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Job ID or 0 on error</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Use this function when you want to stream print data using the
+<a href="#cupsStartDocument"><code>cupsStartDocument</code></a>, <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a>, and
+<a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> functions. If you have one or more files to
+print, use the <a href="#cupsPrintFile2"><code>cupsPrintFile2</code></a> or <a href="#cupsPrintFiles2"><code>cupsPrintFiles2</code></a> function
+instead.
+
+</p>
+<h3 class="function"><a name="cupsEncryption">cupsEncryption</a></h3>
+<p class="description">Get the default encryption settings.</p>
+<p class="code">
+http_encryption_t cupsEncryption (void);</p>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Encryption settings</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
+environment variable, then the ~/.cups/client.conf file, and finally the
+/etc/cups/client.conf file. If not set, the default is
+<code>HTTP_ENCRYPT_IF_REQUESTED</code>.</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsFinishDocument">cupsFinishDocument</a></h3>
+<p class="description">Finish sending a document.</p>
+<p class="code">
+ipp_status_t cupsFinishDocument (<br>
+ http_t *http,<br>
+ const char *name<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Status of document submission</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>.
+
+</p>
+<h3 class="function"><a name="cupsFreeDests">cupsFreeDests</a></h3>
+<p class="description">Free the memory used by the list of destinations.</p>
+<p class="code">
+void cupsFreeDests (<br>
+ int num_dests,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>num_dests</dt>
+<dd class="description">Number of destinations</dd>
+<dt>dests</dt>
+<dd class="description">Destinations</dd>
+</dl>
+<h3 class="function"><a name="cupsFreeJobs">cupsFreeJobs</a></h3>
+<p class="description">Free memory used by job data.</p>
+<p class="code">
+void cupsFreeJobs (<br>
+ int num_jobs,<br>
+ <a href="#cups_job_t">cups_job_t</a> *jobs<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>num_jobs</dt>
+<dd class="description">Number of jobs</dd>
+<dt>jobs</dt>
+<dd class="description">Jobs</dd>
+</dl>
+<h3 class="function"><a name="cupsFreeOptions">cupsFreeOptions</a></h3>
+<p class="description">Free all memory used by options.</p>
+<p class="code">
+void cupsFreeOptions (<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>num_options</dt>
+<dd class="description">Number of options</dd>
+<dt>options</dt>
+<dd class="description">Pointer to options</dd>
+</dl>
+<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsGetClasses">cupsGetClasses</a></h3>
+<p class="description">Get a list of printer classes from the default server.</p>
+<p class="code">
+int cupsGetClasses (<br>
+ char ***classes<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>classes</dt>
+<dd class="description">Classes</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of classes</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
+
+</p>
+<h3 class="function"><a name="cupsGetDefault">cupsGetDefault</a></h3>
+<p class="description">Get the default printer or class for the default server.</p>
+<p class="code">
+const char *cupsGetDefault (void);</p>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Default printer or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function returns the default printer or class as defined by
the LPDEST or PRINTER environment variables. If these environment
variables are not set, the server default destination is returned.
-Applications should use the cupsGetDests() and cupsGetDest() functions
-to get the user-defined default printer, as this function does not
-support the lpoptions-defined default printer.
+Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a>
+functions to get the user-defined default printer, as this function does
+not support the lpoptions-defined default printer.</p>
+<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsGetDefault2">cupsGetDefault2</a></h3>
+<p class="description">Get the default printer or class for the specified server.</p>
+<p class="code">
+const char *cupsGetDefault2 (<br>
+ http_t *http<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Default printer or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function returns the default printer or class as defined by
+the LPDEST or PRINTER environment variables. If these environment
+variables are not set, the server default destination is returned.
+Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a>
+functions to get the user-defined default printer, as this function does
+not support the lpoptions-defined default printer.
</p>
-<h4>Syntax</h4>
-<pre>
-const char *
-cupsGetDefault2(
- http_t * http);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Default printer or NULL</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsGetDest'>cupsGetDest()</a></h3>
-<h4>Description</h4>
-<p>Get the named destination from the list.
-
-Use the cupsGetDests() or cupsGetDests2() functions to get a
+<h3 class="function"><a name="cupsGetDest">cupsGetDest</a></h3>
+<p class="description">Get the named destination from the list.</p>
+<p class="code">
+<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest (<br>
+ const char *name,<br>
+ const char *instance,<br>
+ int num_dests,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Destination name or <code>NULL</code> for the default destination</dd>
+<dt>instance</dt>
+<dd class="description">Instance name or <code>NULL</code></dd>
+<dt>num_dests</dt>
+<dd class="description">Number of destinations</dd>
+<dt>dests</dt>
+<dd class="description">Destinations</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Destination pointer or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a
list of supported destinations for the current user.</p>
-<h4>Syntax</h4>
-<pre>
-<a href='#cups_dest_t'>cups_dest_t</a> *
-cupsGetDest(
- const char * name,
- const char * instance,
- int num_dests,
- <a href='#cups_dest_t'>cups_dest_t</a> * dests);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt></td><td>Name of destination</td></tr>
-<tr><td><tt>instance</tt></td><td>Instance of destination</td></tr>
-<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
-<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Destination pointer or NULL</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsGetDests'>cupsGetDests()</a></h3>
-<h4>Description</h4>
-<p>Get the list of destinations from the default server.
-
-Starting with CUPS 1.2, the returned list of destinations include the
+<h3 class="function"><a name="cupsGetDests">cupsGetDests</a></h3>
+<p class="description">Get the list of destinations from the default server.</p>
+<p class="code">
+int cupsGetDests (<br>
+ <a href="#cups_dest_t">cups_dest_t</a> **dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>dests</dt>
+<dd class="description">Destinations</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of destinations</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
printer-info, printer-is-accepting-jobs, printer-is-shared,
printer-make-and-model, printer-state, printer-state-change-time,
-printer-state-reasons, and printer-type attributes as options.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsGetDests(
- <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Number of destinations</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsGetDests2'>cupsGetDests2()</a></h3>
-<h4>Description</h4>
-<p>Get the list of destinations from the specified server.
-
-Starting with CUPS 1.2, the returned list of destinations include the
+printer-state-reasons, and printer-type attributes as options.<br>
+<br>
+Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
+the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.</p>
+<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsGetDests2">cupsGetDests2</a></h3>
+<p class="description">Get the list of destinations from the specified server.</p>
+<p class="code">
+int cupsGetDests2 (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> **dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>dests</dt>
+<dd class="description">Destinations</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of destinations</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
printer-info, printer-is-accepting-jobs, printer-is-shared,
printer-make-and-model, printer-state, printer-state-change-time,
-printer-state-reasons, and printer-type attributes as options.
+printer-state-reasons, and printer-type attributes as options.<br>
+<br>
+Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
+the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.
</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsGetDests2(
- http_t * http,
- <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
-<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Number of destinations</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.20 </span><a name='cupsGetFd'>cupsGetFd()</a></h3>
-<h4>Description</h4>
-<p>Get a file from the server.
-
-This function returns HTTP_OK when the file is successfully retrieved.
+<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsGetFd">cupsGetFd</a></h3>
+<p class="description">Get a file from the server.</p>
+<p class="code">
+http_status_t cupsGetFd (<br>
+ http_t *http,<br>
+ const char *resource,<br>
+ int fd<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>resource</dt>
+<dd class="description">Resource name</dd>
+<dt>fd</dt>
+<dd class="description">File descriptor</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">HTTP status</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved.
</p>
-<h4>Syntax</h4>
-<pre>
-http_status_t
-cupsGetFd(
- http_t * http,
- const char * resource,
- int fd);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
-<tr><td><tt>resource</tt></td><td>Resource name</td></tr>
-<tr><td><tt>fd</tt></td><td>File descriptor</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>HTTP status</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.20 </span><a name='cupsGetFile'>cupsGetFile()</a></h3>
-<h4>Description</h4>
-<p>Get a file from the server.
-
-This function returns HTTP_OK when the file is successfully retrieved.
+<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsGetFile">cupsGetFile</a></h3>
+<p class="description">Get a file from the server.</p>
+<p class="code">
+http_status_t cupsGetFile (<br>
+ http_t *http,<br>
+ const char *resource,<br>
+ const char *filename<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>resource</dt>
+<dd class="description">Resource name</dd>
+<dt>filename</dt>
+<dd class="description">Filename</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">HTTP status</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved.
</p>
-<h4>Syntax</h4>
-<pre>
-http_status_t
-cupsGetFile(
- http_t * http,
- const char * resource,
- const char * filename);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
-<tr><td><tt>resource</tt></td><td>Resource name</td></tr>
-<tr><td><tt>filename</tt></td><td>Filename</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>HTTP status</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsGetJobs'>cupsGetJobs()</a></h3>
-<h4>Description</h4>
-<p>Get the jobs from the default server.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsGetJobs(
- <a href='#cups_job_t'>cups_job_t</a> ** jobs,
- const char * mydest,
- int myjobs,
- int completed);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>jobs</tt></td><td>Job data</td></tr>
-<tr><td><tt>mydest</tt></td><td>NULL = all destinations, *
-otherwise show jobs for mydest</td></tr>
-<tr><td><tt>myjobs</tt></td><td>0 = all users, 1 = mine</td></tr>
-<tr><td><tt>completed</tt></td><td>-1 = show all, 0 = active, *
-1 = completed jobs</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Number of jobs</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsGetJobs2'>cupsGetJobs2()</a></h3>
-<h4>Description</h4>
-<p>Get the jobs from the specified server.
+<h3 class="function"><a name="cupsGetJobs">cupsGetJobs</a></h3>
+<p class="description">Get the jobs from the default server.</p>
+<p class="code">
+int cupsGetJobs (<br>
+ <a href="#cups_job_t">cups_job_t</a> **jobs,<br>
+ const char *name,<br>
+ int myjobs,<br>
+ int whichjobs<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>jobs</dt>
+<dd class="description">Job data</dd>
+<dt>name</dt>
+<dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd>
+<dt>myjobs</dt>
+<dd class="description">0 = all users, 1 = mine</dd>
+<dt>whichjobs</dt>
+<dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of jobs</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
+of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
+pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
+jobs that are stopped, canceled, aborted, or completed.</p>
+<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3>
+<p class="description">Get the jobs from the specified server.</p>
+<p class="code">
+int cupsGetJobs2 (<br>
+ http_t *http,<br>
+ <a href="#cups_job_t">cups_job_t</a> **jobs,<br>
+ const char *name,<br>
+ int myjobs,<br>
+ int whichjobs<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>jobs</dt>
+<dd class="description">Job data</dd>
+<dt>name</dt>
+<dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd>
+<dt>myjobs</dt>
+<dd class="description">0 = all users, 1 = mine</dd>
+<dt>whichjobs</dt>
+<dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of jobs</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
+of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
+pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
+jobs that are stopped, canceled, aborted, or completed.
</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsGetJobs2(
- http_t * http,
- <a href='#cups_job_t'>cups_job_t</a> ** jobs,
- const char * mydest,
- int myjobs,
- int completed);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
-<tr><td><tt>jobs</tt></td><td>Job data</td></tr>
-<tr><td><tt>mydest</tt></td><td>NULL = all destinations, *
-otherwise show jobs for mydest</td></tr>
-<tr><td><tt>myjobs</tt></td><td>0 = all users, 1 = mine</td></tr>
-<tr><td><tt>completed</tt></td><td>-1 = show all, 0 = active, *
-1 = completed jobs</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Number of jobs</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsGetOption'>cupsGetOption()</a></h3>
-<h4>Description</h4>
-<p>Get an option value.</p>
-<h4>Syntax</h4>
-<pre>
-const char *
-cupsGetOption(
- const char * name,
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt></td><td>Name of option</td></tr>
-<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Options</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Option value or NULL</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsGetPPD'>cupsGetPPD()</a></h3>
-<h4>Description</h4>
-<p>Get the PPD file for a printer on the default server.
-
-For classes, cupsGetPPD() returns the PPD file for the first printer
-in the class.</p>
-<h4>Syntax</h4>
-<pre>
-const char *
-cupsGetPPD(
- const char * name);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt></td><td>Printer name</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Filename for PPD file</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsGetPPD2'>cupsGetPPD2()</a></h3>
-<h4>Description</h4>
-<p>Get the PPD file for a printer from the specified server.
-
-For classes, cupsGetPPD2() returns the PPD file for the first printer
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3>
+<p class="description">Get options for the named destination.</p>
+<p class="code">
+<a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br>
+ http_t *http,<br>
+ const char *name,<br>
+ const char *instance<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>name</dt>
+<dd class="description">Destination name or <code>NULL</code> for the default destination</dd>
+<dt>instance</dt>
+<dd class="description">Instance name or <code>NULL</code></dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Destination or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is optimized for retrieving a single destination and should
+be used instead of <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you either
+know the name of the destination or want to print to the default destination.
+If <code>NULL</code> is returned, the destination does not exist or there is no
+default destination.<br>
+<br>
+If "http" is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print
+server will be used.<br>
+<br>
+If "name" is <code>NULL</code>, the default printer for the current user will be
+returned.<br>
+<br>
+The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a
+"num_dests" value of 1.
+
+</p>
+<h3 class="function"><a name="cupsGetOption">cupsGetOption</a></h3>
+<p class="description">Get an option value.</p>
+<p class="code">
+const char *cupsGetOption (<br>
+ const char *name,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Name of option</dd>
+<dt>num_options</dt>
+<dd class="description">Number of options</dd>
+<dt>options</dt>
+<dd class="description">Options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Option value or <code>NULL</code></p>
+<h3 class="function"><a name="cupsGetPPD">cupsGetPPD</a></h3>
+<p class="description">Get the PPD file for a printer on the default server.</p>
+<p class="code">
+const char *cupsGetPPD (<br>
+ const char *name<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Filename for PPD file</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">For classes, <code>cupsGetPPD</code> returns the PPD file for the first printer
+in the class.<br>
+<br>
+The returned filename is stored in a static buffer and is overwritten with
+each call to <code>cupsGetPPD</code> or <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>.</p>
+<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsGetPPD2">cupsGetPPD2</a></h3>
+<p class="description">Get the PPD file for a printer from the specified server.</p>
+<p class="code">
+const char *cupsGetPPD2 (<br>
+ http_t *http,<br>
+ const char *name<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Filename for PPD file</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">For classes, <code>cupsGetPPD2</code> returns the PPD file for the first printer
+in the class.<br>
+<br>
+The returned filename is stored in a static buffer and is overwritten with
+each call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a> or <code>cupsGetPPD2</code>.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3>
+<p class="description">Get the PPD file for a printer on the specified
+server if it has changed.</p>
+<p class="code">
+http_status_t cupsGetPPD3 (<br>
+ http_t *http,<br>
+ const char *name,<br>
+ time_t *modtime,<br>
+ char *buffer,<br>
+ size_t bufsize<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>modtime</dt>
+<dd class="description">Modification time</dd>
+<dt>buffer</dt>
+<dd class="description">Filename buffer</dd>
+<dt>bufsize</dt>
+<dd class="description">Size of filename buffer</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">HTTP status</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The "modtime" parameter contains the modification time of any
+locally-cached content and is updated with the time from the PPD file on
+the server.<br>
+<br>
+The "buffer" parameter contains the local PPD filename. If it contains
+the empty string, a new temporary file is created, otherwise the existing
+file will be overwritten as needed.<br>
+<br>
+On success, <code>HTTP_OK</code> is returned for a new PPD file and
+<code>HTTP_NOT_MODIFIED</code> if the existing PPD file is up-to-date. Any other
+status is an error.<br>
+<br>
+For classes, <code>cupsGetPPD3</code> returns the PPD file for the first printer
in the class.
</p>
-<h4>Syntax</h4>
-<pre>
-const char *
-cupsGetPPD2(
- http_t * http,
- const char * name);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
-<tr><td><tt>name</tt></td><td>Printer name</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Filename for PPD file</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsGetPassword'>cupsGetPassword()</a></h3>
-<h4>Description</h4>
-<p>Get a password from the user.
-
-Uses the current password callback function. Returns NULL if the
+<h3 class="function"><a name="cupsGetPassword">cupsGetPassword</a></h3>
+<p class="description">Get a password from the user.</p>
+<p class="code">
+const char *cupsGetPassword (<br>
+ const char *prompt<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>prompt</dt>
+<dd class="description">Prompt string</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Password</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
user does not provide a password.</p>
-<h4>Syntax</h4>
-<pre>
-const char *
-cupsGetPassword(
- const char * prompt);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>prompt</tt></td><td>Prompt string</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Password</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> DEPRECATED </span><a name='cupsGetPrinters'>cupsGetPrinters()</a></h3>
-<h4>Description</h4>
-<p>Get a list of printers from the default server.
+<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsGetPrinters">cupsGetPrinters</a></h3>
+<p class="description">Get a list of printers from the default server.</p>
+<p class="code">
+int cupsGetPrinters (<br>
+ char ***printers<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>printers</dt>
+<dd class="description">Printers</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of printers</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
-This function is deprecated - use cupsGetDests() instead.
+</p>
+<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3>
+<p class="description">Get an available PPD file from the server.</p>
+<p class="code">
+char *cupsGetServerPPD (<br>
+ http_t *http,<br>
+ const char *name<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>name</dt>
+<dd class="description">Name of PPD file ("ppd-name")</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Name of PPD file or <code>NULL</code> on error</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function returns the named PPD file from the server. The
+list of available PPDs is provided by the IPP <code>CUPS_GET_PPDS</code>
+operation.<br>
+<br>
+You must remove (unlink) the PPD file when you are finished with
+it. The PPD filename is stored in a static location that will be
+overwritten on the next call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a>, <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>,
+or <a href="#cupsGetServerPPD"><code>cupsGetServerPPD</code></a>.
</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsGetPrinters(
- char *** printers);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>printers</tt></td><td>Printers</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Number of printers</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsLangDefault'>cupsLangDefault()</a></h3>
-<h4>Description</h4>
-<p>Return the default language.</p>
-<h4>Syntax</h4>
-<pre>
-cups_lang_t *
-cupsLangDefault(void);
-</pre>
-<h4>Arguments</h4>
-<p>None.</p>
-<h4>Returns</h4>
-<p>Language data</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsLangEncoding'>cupsLangEncoding()</a></h3>
-<h4>Description</h4>
-<p>Return the character encoding (us-ascii, etc.)
+<h3 class="function"><a name="cupsLangDefault">cupsLangDefault</a></h3>
+<p class="description">Return the default language.</p>
+<p class="code">
+cups_lang_t *cupsLangDefault (void);</p>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Language data</p>
+<h3 class="function"><a name="cupsLangEncoding">cupsLangEncoding</a></h3>
+<p class="description">Return the character encoding (us-ascii, etc.)
for the given language.</p>
-<h4>Syntax</h4>
-<pre>
-const char *
-cupsLangEncoding(
- cups_lang_t * lang);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>lang</tt></td><td>Language data</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Character encoding</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsLangFlush'>cupsLangFlush()</a></h3>
-<h4>Description</h4>
-<p>Flush all language data out of the cache.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsLangFlush(void);
-</pre>
-<h4>Arguments</h4>
-<p>None.</p>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsLangFree'>cupsLangFree()</a></h3>
-<h4>Description</h4>
-<p>Free language data.
-
-This does not actually free anything; use cupsLangFlush() for that.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsLangFree(
- cups_lang_t * lang);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>lang</tt></td><td>Language to free</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsLangGet'>cupsLangGet()</a></h3>
-<h4>Description</h4>
-<p>Get a language.</p>
-<h4>Syntax</h4>
-<pre>
-cups_lang_t *
-cupsLangGet(
- const char * language);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>language</tt></td><td>Language or locale</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Language data</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsLastError'>cupsLastError()</a></h3>
-<h4>Description</h4>
-<p>Return the last IPP status code.</p>
-<h4>Syntax</h4>
-<pre>
-ipp_status_t
-cupsLastError(void);
-</pre>
-<h4>Arguments</h4>
-<p>None.</p>
-<h4>Returns</h4>
-<p>IPP status code from last request</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsLastErrorString'>cupsLastErrorString()</a></h3>
-<h4>Description</h4>
-<p>Return the last IPP status-message.
+<p class="code">
+const char *cupsLangEncoding (<br>
+ cups_lang_t *lang<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>lang</dt>
+<dd class="description">Language data</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Character encoding</p>
+<h3 class="function"><a name="cupsLangFlush">cupsLangFlush</a></h3>
+<p class="description">Flush all language data out of the cache.</p>
+<p class="code">
+void cupsLangFlush (void);</p>
+<h3 class="function"><a name="cupsLangFree">cupsLangFree</a></h3>
+<p class="description">Free language data.</p>
+<p class="code">
+void cupsLangFree (<br>
+ cups_lang_t *lang<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>lang</dt>
+<dd class="description">Language to free</dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This does not actually free anything; use <a href="#cupsLangFlush"><code>cupsLangFlush</code></a> for that.</p>
+<h3 class="function"><a name="cupsLangGet">cupsLangGet</a></h3>
+<p class="description">Get a language.</p>
+<p class="code">
+cups_lang_t *cupsLangGet (<br>
+ const char *language<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>language</dt>
+<dd class="description">Language or locale</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Language data</p>
+<h3 class="function"><a name="cupsLastError">cupsLastError</a></h3>
+<p class="description">Return the last IPP status code.</p>
+<p class="code">
+ipp_status_t cupsLastError (void);</p>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">IPP status code from last request</p>
+<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsLastErrorString">cupsLastErrorString</a></h3>
+<p class="description">Return the last IPP status-message.</p>
+<p class="code">
+const char *cupsLastErrorString (void);</p>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">status-message text from last request</p>
+<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3>
+<p class="description">Return the subject for the given notification message.</p>
+<p class="code">
+char *cupsNotifySubject (<br>
+ cups_lang_t *lang,<br>
+ ipp_t *event<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>lang</dt>
+<dd class="description">Language data</dd>
+<dt>event</dt>
+<dd class="description">Event data</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Subject string or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned string must be freed by the caller using <code>free</code>.
</p>
-<h4>Syntax</h4>
-<pre>
-const char *
-cupsLastErrorString(void);
-</pre>
-<h4>Arguments</h4>
-<p>None.</p>
-<h4>Returns</h4>
-<p>status-message text from last request</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsMarkOptions'>cupsMarkOptions()</a></h3>
-<h4>Description</h4>
-<p>Mark command-line options in a PPD file.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsMarkOptions(
- ppd_file_t * ppd,
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>ppd</tt></td><td>PPD file</td></tr>
-<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Options</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>1 if conflicting</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsParseOptions'>cupsParseOptions()</a></h3>
-<h4>Description</h4>
-<p>Parse options from a command-line argument.
-
-This function converts space-delimited name/value pairs according
-to the PAPI text option ABNF specification. Collection values
-("name={a=... b=... c=...}") are stored with the curley brackets
-intact - use cupsParseOptions() on the value to extract the collection
-attributes.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsParseOptions(
- const char * arg,
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> ** options);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>arg</tt></td><td>Argument to parse</td></tr>
-<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Options found</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Number of options found</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsPrintFile'>cupsPrintFile()</a></h3>
-<h4>Description</h4>
-<p>Print a file to a printer or class on the default server.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsPrintFile(
- const char * name,
- const char * filename,
- const char * title,
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
-<tr><td><tt>filename</tt></td><td>File to print</td></tr>
-<tr><td><tt>title</tt></td><td>Title of job</td></tr>
-<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Options</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Job ID</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsPrintFile2'>cupsPrintFile2()</a></h3>
-<h4>Description</h4>
-<p>Print a file to a printer or class on the specified server.
+<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsNotifyText">cupsNotifyText</a></h3>
+<p class="description">Return the text for the given notification message.</p>
+<p class="code">
+char *cupsNotifyText (<br>
+ cups_lang_t *lang,<br>
+ ipp_t *event<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>lang</dt>
+<dd class="description">Language data</dd>
+<dt>event</dt>
+<dd class="description">Event data</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Message text or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned string must be freed by the caller using <code>free</code>.
</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsPrintFile2(
- http_t * http,
- const char * name,
- const char * filename,
- const char * title,
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
-<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
-<tr><td><tt>filename</tt></td><td>File to print</td></tr>
-<tr><td><tt>title</tt></td><td>Title of job</td></tr>
-<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Options</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Job ID</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsPrintFiles'>cupsPrintFiles()</a></h3>
-<h4>Description</h4>
-<p>Print one or more files to a printer or class on the
+<h3 class="function"><a name="cupsParseOptions">cupsParseOptions</a></h3>
+<p class="description">Parse options from a command-line argument.</p>
+<p class="code">
+int cupsParseOptions (<br>
+ const char *arg,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> **options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>arg</dt>
+<dd class="description">Argument to parse</dd>
+<dt>num_options</dt>
+<dd class="description">Number of options</dd>
+<dt>options</dt>
+<dd class="description">Options found</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of options found</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function converts space-delimited name/value pairs according
+to the PAPI text option ABNF specification. Collection values
+("name={a=... b=... c=...}") are stored with the curley brackets
+intact - use <code>cupsParseOptions</code> on the value to extract the
+collection attributes.</p>
+<h3 class="function"><a name="cupsPrintFile">cupsPrintFile</a></h3>
+<p class="description">Print a file to a printer or class on the default server.</p>
+<p class="code">
+int cupsPrintFile (<br>
+ const char *name,<br>
+ const char *filename,<br>
+ const char *title,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>filename</dt>
+<dd class="description">File to print</dd>
+<dt>title</dt>
+<dd class="description">Title of job</dd>
+<dt>num_options</dt>
+<dd class="description">Number of options</dd>
+<dt>options</dt>
+<dd class="description">Options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Job ID or 0 on error</p>
+<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsPrintFile2">cupsPrintFile2</a></h3>
+<p class="description">Print a file to a printer or class on the specified
+server.</p>
+<p class="code">
+int cupsPrintFile2 (<br>
+ http_t *http,<br>
+ const char *name,<br>
+ const char *filename,<br>
+ const char *title,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server</dd>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>filename</dt>
+<dd class="description">File to print</dd>
+<dt>title</dt>
+<dd class="description">Title of job</dd>
+<dt>num_options</dt>
+<dd class="description">Number of options</dd>
+<dt>options</dt>
+<dd class="description">Options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Job ID or 0 on error</p>
+<h3 class="function"><a name="cupsPrintFiles">cupsPrintFiles</a></h3>
+<p class="description">Print one or more files to a printer or class on the
default server.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsPrintFiles(
- const char * name,
- int num_files,
- const char ** files,
- const char * title,
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
-<tr><td><tt>num_files</tt></td><td>Number of files</td></tr>
-<tr><td><tt>files</tt></td><td>File(s) to print</td></tr>
-<tr><td><tt>title</tt></td><td>Title of job</td></tr>
-<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Options</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Job ID</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsPrintFiles2'>cupsPrintFiles2()</a></h3>
-<h4>Description</h4>
-<p>Print one or more files to a printer or class on the
-specified server.
+<p class="code">
+int cupsPrintFiles (<br>
+ const char *name,<br>
+ int num_files,<br>
+ const char **files,<br>
+ const char *title,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>num_files</dt>
+<dd class="description">Number of files</dd>
+<dt>files</dt>
+<dd class="description">File(s) to print</dd>
+<dt>title</dt>
+<dd class="description">Title of job</dd>
+<dt>num_options</dt>
+<dd class="description">Number of options</dd>
+<dt>options</dt>
+<dd class="description">Options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Job ID or 0 on error</p>
+<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3>
+<p class="description">Print one or more files to a printer or class on the
+specified server.</p>
+<p class="code">
+int cupsPrintFiles2 (<br>
+ http_t *http,<br>
+ const char *name,<br>
+ int num_files,<br>
+ const char **files,<br>
+ const char *title,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>num_files</dt>
+<dd class="description">Number of files</dd>
+<dt>files</dt>
+<dd class="description">File(s) to print</dd>
+<dt>title</dt>
+<dd class="description">Title of job</dd>
+<dt>num_options</dt>
+<dd class="description">Number of options</dd>
+<dt>options</dt>
+<dd class="description">Options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Job ID or 0 on error</p>
+<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsPutFd">cupsPutFd</a></h3>
+<p class="description">Put a file on the server.</p>
+<p class="code">
+http_status_t cupsPutFd (<br>
+ http_t *http,<br>
+ const char *resource,<br>
+ int fd<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>resource</dt>
+<dd class="description">Resource name</dd>
+<dt>fd</dt>
+<dd class="description">File descriptor</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">HTTP status</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored
+successfully.
</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsPrintFiles2(
- http_t * http,
- const char * name,
- int num_files,
- const char ** files,
- const char * title,
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
-<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
-<tr><td><tt>num_files</tt></td><td>Number of files</td></tr>
-<tr><td><tt>files</tt></td><td>File(s) to print</td></tr>
-<tr><td><tt>title</tt></td><td>Title of job</td></tr>
-<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Options</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Job ID</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.20 </span><a name='cupsPutFd'>cupsPutFd()</a></h3>
-<h4>Description</h4>
-<p>Put a file on the server.
-
-This function returns HTTP_CREATED when the file is stored successfully.
+<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsPutFile">cupsPutFile</a></h3>
+<p class="description">Put a file on the server.</p>
+<p class="code">
+http_status_t cupsPutFile (<br>
+ http_t *http,<br>
+ const char *resource,<br>
+ const char *filename<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>resource</dt>
+<dd class="description">Resource name</dd>
+<dt>filename</dt>
+<dd class="description">Filename</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">HTTP status</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored
+successfully.
</p>
-<h4>Syntax</h4>
-<pre>
-http_status_t
-cupsPutFd(
- http_t * http,
- const char * resource,
- int fd);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
-<tr><td><tt>resource</tt></td><td>Resource name</td></tr>
-<tr><td><tt>fd</tt></td><td>File descriptor</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>HTTP status</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.20 </span><a name='cupsPutFile'>cupsPutFile()</a></h3>
-<h4>Description</h4>
-<p>Put a file on the server.
-
-This function returns HTTP_CREATED when the file is stored successfully.
+<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3>
+<p class="description">Remove a destination from the destination list.</p>
+<p class="code">
+int cupsRemoveDest (<br>
+ const char *name,<br>
+ const char *instance,<br>
+ int num_dests,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> **dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>instance</dt>
+<dd class="description">Instance name or <code>NULL</code></dd>
+<dt>num_dests</dt>
+<dd class="description">Number of destinations</dd>
+<dt>dests</dt>
+<dd class="description">Destinations</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">New number of destinations</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Removing a destination/instance does not delete the class or printer
+queue, merely the lpoptions for that destination/instance. Use the
+<a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new
+options for the user.
</p>
-<h4>Syntax</h4>
-<pre>
-http_status_t
-cupsPutFile(
- http_t * http,
- const char * resource,
- const char * filename);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
-<tr><td><tt>resource</tt></td><td>Resource name</td></tr>
-<tr><td><tt>filename</tt></td><td>Filename</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>HTTP status</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsRemoveOption'>cupsRemoveOption()</a></h3>
-<h4>Description</h4>
-<p>Remove an option from an option array.
-
-</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsRemoveOption(
- const char * name,
- int num_options,
- <a href='#cups_option_t'>cups_option_t</a> ** options);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt></td><td>Option name</td></tr>
-<tr><td><tt>num_options</tt></td><td>Current number of options</td></tr>
-<tr><td><tt>options</tt></td><td>Options</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>New number of options</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsServer'>cupsServer()</a></h3>
-<h4>Description</h4>
-<p>Return the hostname/address of the default server.
-
-The returned value can be a fully-qualified hostname, a numeric
+<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3>
+<p class="description">Remove an option from an option array.</p>
+<p class="code">
+int cupsRemoveOption (<br>
+ const char *name,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> **options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Option name</dd>
+<dt>num_options</dt>
+<dd class="description">Current number of options</dd>
+<dt>options</dt>
+<dd class="description">Options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">New number of options</p>
+<h3 class="function"><a name="cupsServer">cupsServer</a></h3>
+<p class="description">Return the hostname/address of the default server.</p>
+<p class="code">
+const char *cupsServer (void);</p>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Server name</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned value can be a fully-qualified hostname, a numeric
IPv4 or IPv6 address, or a domain socket pathname.</p>
-<h4>Syntax</h4>
-<pre>
-const char *
-cupsServer(void);
-</pre>
-<h4>Arguments</h4>
-<p>None.</p>
-<h4>Returns</h4>
-<p>Server name</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsSetDests'>cupsSetDests()</a></h3>
-<h4>Description</h4>
-<p>Save the list of destinations for the default server.
-
-This function saves the destinations to /etc/cups/lpoptions when run
+<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
+<p class="description">Set the default destination.</p>
+<p class="code">
+void cupsSetDefaultDest (<br>
+ const char *name,<br>
+ const char *instance,<br>
+ int num_dests,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>instance</dt>
+<dd class="description">Instance name or <code>NULL</code></dd>
+<dt>num_dests</dt>
+<dd class="description">Number of destinations</dd>
+<dt>dests</dt>
+<dd class="description">Destinations</dd>
+</dl>
+<h3 class="function"><a name="cupsSetDests">cupsSetDests</a></h3>
+<p class="description">Save the list of destinations for the default server.</p>
+<p class="code">
+void cupsSetDests (<br>
+ int num_dests,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>num_dests</dt>
+<dd class="description">Number of destinations</dd>
+<dt>dests</dt>
+<dd class="description">Destinations</dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
as root and ~/.cups/lpoptions when run as a normal user.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsSetDests(
- int num_dests,
- <a href='#cups_dest_t'>cups_dest_t</a> * dests);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
-<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsSetDests2'>cupsSetDests2()</a></h3>
-<h4>Description</h4>
-<p>Save the list of destinations for the specified server.
-
-This function saves the destinations to /etc/cups/lpoptions when run
+<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsSetDests2">cupsSetDests2</a></h3>
+<p class="description">Save the list of destinations for the specified server.</p>
+<p class="code">
+int cupsSetDests2 (<br>
+ http_t *http,<br>
+ int num_dests,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>num_dests</dt>
+<dd class="description">Number of destinations</dd>
+<dt>dests</dt>
+<dd class="description">Destinations</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">0 on success, -1 on error</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
as root and ~/.cups/lpoptions when run as a normal user.
</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsSetDests2(
- http_t * http,
- int num_dests,
- <a href='#cups_dest_t'>cups_dest_t</a> * dests);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
-<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
-<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>0 on success, -1 on error</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsSetEncryption'>cupsSetEncryption()</a></h3>
-<h4>Description</h4>
-<p>Set the encryption preference.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsSetEncryption(
- http_encryption_t e);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>e</tt></td><td>New encryption preference</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsSetPasswordCB'>cupsSetPasswordCB()</a></h3>
-<h4>Description</h4>
-<p>Set the password callback for CUPS.
-
-Pass NULL to restore the default (console) password callback.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsSetPasswordCB(
- <a href='#cups_password_cb_t'>cups_password_cb_t</a> cb);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>cb</tt></td><td>Callback function</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsSetServer'>cupsSetServer()</a></h3>
-<h4>Description</h4>
-<p>Set the default server name.
-
-The "server" string can be a fully-qualified hostname, a numeric
-IPv4 or IPv6 address, or a domain socket pathname. Pass NULL to
+<h3 class="function"><a name="cupsSetEncryption">cupsSetEncryption</a></h3>
+<p class="description">Set the encryption preference.</p>
+<p class="code">
+void cupsSetEncryption (<br>
+ http_encryption_t e<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>e</dt>
+<dd class="description">New encryption preference</dd>
+</dl>
+<h3 class="function"><a name="cupsSetPasswordCB">cupsSetPasswordCB</a></h3>
+<p class="description">Set the password callback for CUPS.</p>
+<p class="code">
+void cupsSetPasswordCB (<br>
+ <a href="#cups_password_cb_t">cups_password_cb_t</a> cb<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>cb</dt>
+<dd class="description">Callback function</dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback.</p>
+<h3 class="function"><a name="cupsSetServer">cupsSetServer</a></h3>
+<p class="description">Set the default server name.</p>
+<p class="code">
+void cupsSetServer (<br>
+ const char *server<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>server</dt>
+<dd class="description">Server name</dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The "server" string can be a fully-qualified hostname, a numeric
+IPv4 or IPv6 address, or a domain socket pathname. Pass <code>NULL</code> to
restore the default server name.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsSetServer(
- const char * server);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>server</tt></td><td>Server name</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsSetUser'>cupsSetUser()</a></h3>
-<h4>Description</h4>
-<p>Set the default user name.
-
-Pass NULL to restore the default user name.</p>
-<h4>Syntax</h4>
-<pre>
-void
-cupsSetUser(
- const char * user);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>user</tt></td><td>User name</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Nothing.</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsTempFd'>cupsTempFd()</a></h3>
-<h4>Description</h4>
-<p>Create a temporary file.
-
-The temporary filename is stored in the filename buffer.</p>
-<h4>Syntax</h4>
-<pre>
-int
-cupsTempFd(
- char * filename,
- int len);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
-<tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>New file descriptor</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> DEPRECATED </span><a name='cupsTempFile'>cupsTempFile()</a></h3>
-<h4>Description</h4>
-<p>Generate a temporary filename.
-
-The temporary filename is stored in the filename buffer.
-This function is deprecated - use cupsTempFd() or cupsTempFile2()
-instead.
+<h3 class="function"><a name="cupsSetUser">cupsSetUser</a></h3>
+<p class="description">Set the default user name.</p>
+<p class="code">
+void cupsSetUser (<br>
+ const char *user<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>user</dt>
+<dd class="description">User name</dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Pass <code>NULL</code> to restore the default user name.</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsStartDocument">cupsStartDocument</a></h3>
+<p class="description">Add a document to a job created with cupsCreateJob().</p>
+<p class="code">
+http_status_t cupsStartDocument (<br>
+ http_t *http,<br>
+ const char *name,<br>
+ int job_id,<br>
+ const char *docname,<br>
+ const char *format,<br>
+ int last_document<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>name</dt>
+<dd class="description">Destination name</dd>
+<dt>job_id</dt>
+<dd class="description">Job ID from <a href="#cupsCreateJob"><code>cupsCreateJob</code></a></dd>
+<dt>docname</dt>
+<dd class="description">Name of document</dd>
+<dt>format</dt>
+<dd class="description">MIME type or <code>CUPS_FORMAT_foo</code></dd>
+<dt>last_document</dt>
+<dd class="description">1 for last document in job, 0 otherwise</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">HTTP status of request</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write data for the document and
+<a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> to finish the document and get the submission status.<br>
+<br>
+The MIME type constants <code>CUPS_FORMAT_AUTO</code>, <code>CUPS_FORMAT_PDF</code>,
+<code>CUPS_FORMAT_POSTSCRIPT</code>, <code>CUPS_FORMAT_RAW</code>, and
+<code>CUPS_FORMAT_TEXT</code> are provided for the "format" argument, although
+any supported MIME type string can be supplied.
</p>
-<h4>Syntax</h4>
-<pre>
-char *
-cupsTempFile(
- char * filename,
- int len);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
-<tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>Filename</p>
-<!-- NEW PAGE -->
-<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsTempFile2'>cupsTempFile2()</a></h3>
-<h4>Description</h4>
-<p>Create a temporary CUPS file.
-
-The temporary filename is stored in the filename buffer.
+<h3 class="function"><a name="cupsTempFd">cupsTempFd</a></h3>
+<p class="description">Creates a temporary file.</p>
+<p class="code">
+int cupsTempFd (<br>
+ char *filename,<br>
+ int len<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>filename</dt>
+<dd class="description">Pointer to buffer</dd>
+<dt>len</dt>
+<dd class="description">Size of buffer</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">New file descriptor or -1 on error</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The temporary filename is returned in the filename buffer.
+The temporary file is opened for reading and writing.</p>
+<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsTempFile">cupsTempFile</a></h3>
+<p class="description">Generates a temporary filename.</p>
+<p class="code">
+char *cupsTempFile (<br>
+ char *filename,<br>
+ int len<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>filename</dt>
+<dd class="description">Pointer to buffer</dd>
+<dt>len</dt>
+<dd class="description">Size of buffer</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Filename or <code>NULL</code> on error</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The temporary filename is returned in the filename buffer.
+This function is deprecated - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or
+<a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead.
</p>
-<h4>Syntax</h4>
-<pre>
-cups_file_t *
-cupsTempFile2(
- char * filename,
- int len);
-</pre>
-<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
-<tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
-</tbody></table></div>
-<h4>Returns</h4>
-<p>CUPS file or NULL on error</p>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cupsUser'>cupsUser()</a></h3>
-<h4>Description</h4>
-<p>Return the current user's name.</p>
-<h4>Syntax</h4>
-<pre>
-const char *
-cupsUser(void);
-</pre>
-<h4>Arguments</h4>
-<p>None.</p>
-<h4>Returns</h4>
-<p>User name</p>
-<!-- NEW PAGE -->
-<h2 class='title'><a name='STRUCTURES'>Structures</a></h2>
-<ul>
- <li><a href='#cups_dest_s'><tt>cups_dest_s</tt></a> </li>
- <li><a href='#cups_job_s'><tt>cups_job_s</tt></a> </li>
- <li><a href='#cups_option_s'><tt>cups_option_s</tt></a> </li>
-</ul>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cups_dest_s'>cups_dest_s</a></h3>
-<h4>Description</h4>
-<p>Destination</p>
-<h4>Definition</h4>
-<pre>
-struct cups_dest_s
-{
- char *name, * instance;
- int is_default;
- int num_options;
- <a href='#cups_option_t'>cups_option_t</a> * options;
-};
-</pre>
-<h4>Members</h4>
-<div class='table'><table align='center' border='1' width='80%'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>instance</tt> </td><td>Local instance name or NULL</td></tr>
-<tr><td><tt>is_default</tt> </td><td>Is this printer the default?</td></tr>
-<tr><td><tt>num_options</tt> </td><td>Number of options</td></tr>
-<tr><td><tt>options</tt> </td><td>Options</td></tr>
-</tbody></table></div>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cups_job_s'>cups_job_s</a></h3>
-<h4>Description</h4>
-<p>Job</p>
-<h4>Definition</h4>
-<pre>
-struct cups_job_s
-{
- time_t completed_time;
- time_t creation_time;
- char * dest;
- char * format;
- int id;
- int priority;
- time_t processing_time;
- int size;
- ipp_jstate_t state;
- char * title;
- char * user;
-};
-</pre>
-<h4>Members</h4>
-<div class='table'><table align='center' border='1' width='80%'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>completed_time</tt> </td><td>Time the job was completed</td></tr>
-<tr><td><tt>creation_time</tt> </td><td>Time the job was created</td></tr>
-<tr><td><tt>dest</tt> </td><td>Printer or class name</td></tr>
-<tr><td><tt>format</tt> </td><td>Document format</td></tr>
-<tr><td><tt>id</tt> </td><td>The job ID</td></tr>
-<tr><td><tt>priority</tt> </td><td>Priority (1-100)</td></tr>
-<tr><td><tt>processing_time</tt> </td><td>Time the job was processed</td></tr>
-<tr><td><tt>size</tt> </td><td>Size in kilobytes</td></tr>
-<tr><td><tt>state</tt> </td><td>Job state</td></tr>
-<tr><td><tt>title</tt> </td><td>Title/job name</td></tr>
-<tr><td><tt>user</tt> </td><td>User the submitted the job</td></tr>
-</tbody></table></div>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cups_option_s'>cups_option_s</a></h3>
-<h4>Description</h4>
-<p>Printer Options</p>
-<h4>Definition</h4>
-<pre>
-struct cups_option_s
-{
- char * name;
- char * value;
-};
-</pre>
-<h4>Members</h4>
-<div class='table'><table align='center' border='1' width='80%'>
-<thead><tr><th>Name</th><th>Description</th></tr></thead>
-<tbody>
-<tr><td><tt>name</tt> </td><td>Name of option</td></tr>
-<tr><td><tt>value</tt> </td><td>Value of option</td></tr>
-</tbody></table></div>
-<!-- NEW PAGE -->
-<h2 class='title'><a name='TYPES'>Types</a></h2>
-<ul>
- <li><a href='#cups_dest_t'><tt>cups_dest_t</tt></a> </li>
- <li><a href='#cups_job_t'><tt>cups_job_t</tt></a> </li>
- <li><a href='#cups_option_t'><tt>cups_option_t</tt></a> </li>
- <li><a href='#cups_password_cb_t'><tt>cups_password_cb_t</tt></a> </li>
- <li><a href='#cups_ptype_t'><tt>cups_ptype_t</tt></a> </li>
-</ul>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cups_dest_t'>cups_dest_t</a></h3>
-<h4>Description</h4>
-<p>Destination</p>
-<h4>Definition</h4>
-<pre>
-typedef struct <a href='#cups_dest_s'>cups_dest_s</a> cups_dest_t;
-</pre>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cups_job_t'>cups_job_t</a></h3>
-<h4>Description</h4>
-<p>Job</p>
-<h4>Definition</h4>
-<pre>
-typedef struct <a href='#cups_job_s'>cups_job_s</a> cups_job_t;
-</pre>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cups_option_t'>cups_option_t</a></h3>
-<h4>Description</h4>
-<p>Printer Options</p>
-<h4>Definition</h4>
-<pre>
-typedef struct <a href='#cups_option_s'>cups_option_s</a> cups_option_t;
-</pre>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cups_password_cb_t'>cups_password_cb_t</a></h3>
-<h4>Description</h4>
-<p>Password callback</p>
-<h4>Definition</h4>
-<pre>
-typedef const char * (*cups_password_cb_t)(const char *);
-</pre>
-<!-- NEW PAGE -->
-<h3 class='title'><a name='cups_ptype_t'>cups_ptype_t</a></h3>
-<h4>Description</h4>
-<p>Printer Type/Capability Bits</p>
-<h4>Definition</h4>
-<pre>
+<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsTempFile2">cupsTempFile2</a></h3>
+<p class="description">Creates a temporary CUPS file.</p>
+<p class="code">
+cups_file_t *cupsTempFile2 (<br>
+ char *filename,<br>
+ int len<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>filename</dt>
+<dd class="description">Pointer to buffer</dd>
+<dt>len</dt>
+<dd class="description">Size of buffer</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">CUPS file or <code>NULL</code> on error</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The temporary filename is returned in the filename buffer.
+The temporary file is opened for writing.
+
+</p>
+<h3 class="function"><a name="cupsUser">cupsUser</a></h3>
+<p class="description">Return the current user's name.</p>
+<p class="code">
+const char *cupsUser (void);</p>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">User name</p>
+<h2 class="title"><a name="TYPES">Data Types</a></h2>
+<h3 class="typedef"><a name="cups_dest_t">cups_dest_t</a></h3>
+<p class="description">Destination</p>
+<p class="code">
+typedef struct <a href="#cups_dest_s">cups_dest_s</a> cups_dest_t;
+</p>
+<h3 class="typedef"><a name="cups_job_t">cups_job_t</a></h3>
+<p class="description">Job</p>
+<p class="code">
+typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t;
+</p>
+<h3 class="typedef"><a name="cups_option_t">cups_option_t</a></h3>
+<p class="description">Printer Options</p>
+<p class="code">
+typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t;
+</p>
+<h3 class="typedef"><a name="cups_password_cb_t">cups_password_cb_t</a></h3>
+<p class="description">Password callback</p>
+<p class="code">
+typedef const char *(*cups_password_cb_t)(const char *);
+</p>
+<h3 class="typedef"><a name="cups_ptype_t">cups_ptype_t</a></h3>
+<p class="description">Printer type/capability bits</p>
+<p class="code">
typedef unsigned cups_ptype_t;
-</pre>
+</p>
+<h2 class="title"><a name="STRUCTURES">Structures</a></h2>
+<h3 class="struct"><a name="cups_dest_s">cups_dest_s</a></h3>
+<p class="description">Destination</p>
+<p class="code">struct cups_dest_s {<br>
+ char *name, *instance;<br>
+ int is_default;<br>
+ int num_options;<br>
+ <a href="#cups_option_t">cups_option_t</a> *options;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>instance </dt>
+<dd class="description">Local instance name or NULL</dd>
+<dt>is_default </dt>
+<dd class="description">Is this printer the default?</dd>
+<dt>num_options </dt>
+<dd class="description">Number of options</dd>
+<dt>options </dt>
+<dd class="description">Options</dd>
+</dl>
+<h3 class="struct"><a name="cups_job_s">cups_job_s</a></h3>
+<p class="description">Job</p>
+<p class="code">struct cups_job_s {<br>
+ time_t completed_time;<br>
+ time_t creation_time;<br>
+ char *dest;<br>
+ char *format;<br>
+ int id;<br>
+ int priority;<br>
+ time_t processing_time;<br>
+ int size;<br>
+ ipp_jstate_t state;<br>
+ char *title;<br>
+ char *user;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>completed_time </dt>
+<dd class="description">Time the job was completed</dd>
+<dt>creation_time </dt>
+<dd class="description">Time the job was created</dd>
+<dt>dest </dt>
+<dd class="description">Printer or class name</dd>
+<dt>format </dt>
+<dd class="description">Document format</dd>
+<dt>id </dt>
+<dd class="description">The job ID</dd>
+<dt>priority </dt>
+<dd class="description">Priority (1-100)</dd>
+<dt>processing_time </dt>
+<dd class="description">Time the job was processed</dd>
+<dt>size </dt>
+<dd class="description">Size in kilobytes</dd>
+<dt>state </dt>
+<dd class="description">Job state</dd>
+<dt>title </dt>
+<dd class="description">Title/job name</dd>
+<dt>user </dt>
+<dd class="description">User the submitted the job</dd>
+</dl>
+<h3 class="struct"><a name="cups_option_s">cups_option_s</a></h3>
+<p class="description">Printer Options</p>
+<p class="code">struct cups_option_s {<br>
+ char *name;<br>
+ char *value;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>name </dt>
+<dd class="description">Name of option</dd>
+<dt>value </dt>
+<dd class="description">Value of option</dd>
+</dl>
+<h2 class="title"><a name="ENUMERATIONS">Constants</a></h2>
+<h3 class="enumeration"><a name="cups_ptype_e">cups_ptype_e</a></h3>
+<p class="description">Printer type/capability bit constants</p>
+<h4 class="constants">Constants</h4>
+<dl>
+<dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2 </span></dt>
+<dd class="description">Printer requires authentication </dd>
+<dt>CUPS_PRINTER_BIND </dt>
+<dd class="description">Can bind output</dd>
+<dt>CUPS_PRINTER_BW </dt>
+<dd class="description">Can do B&W printing</dd>
+<dt>CUPS_PRINTER_CLASS </dt>
+<dd class="description">Printer class</dd>
+<dt>CUPS_PRINTER_COLLATE </dt>
+<dd class="description">Can collage copies</dd>
+<dt>CUPS_PRINTER_COLOR </dt>
+<dd class="description">Can do color printing</dd>
+<dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2 </span></dt>
+<dd class="description">Printer supports maintenance commands </dd>
+<dt>CUPS_PRINTER_COPIES </dt>
+<dd class="description">Can do copies</dd>
+<dt>CUPS_PRINTER_COVER </dt>
+<dd class="description">Can cover output</dd>
+<dt>CUPS_PRINTER_DEFAULT </dt>
+<dd class="description">Default printer on network</dd>
+<dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2 </span></dt>
+<dd class="description">Delete printer </dd>
+<dt>CUPS_PRINTER_DISCOVERED <span class="info"> CUPS 1.3 </span></dt>
+<dd class="description">Printer was automatically discovered and added </dd>
+<dt>CUPS_PRINTER_DUPLEX </dt>
+<dd class="description">Can do duplexing</dd>
+<dt>CUPS_PRINTER_FAX </dt>
+<dd class="description">Fax queue</dd>
+<dt>CUPS_PRINTER_IMPLICIT </dt>
+<dd class="description">Implicit class</dd>
+<dt>CUPS_PRINTER_LARGE </dt>
+<dd class="description">Can do D/E/A1/A0</dd>
+<dt>CUPS_PRINTER_LOCAL </dt>
+<dd class="description">Local printer or class</dd>
+<dt>CUPS_PRINTER_MEDIUM </dt>
+<dd class="description">Can do Tabloid/B/C/A3/A2</dd>
+<dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2 </span></dt>
+<dd class="description">Printer is not shared </dd>
+<dt>CUPS_PRINTER_PUNCH </dt>
+<dd class="description">Can punch output</dd>
+<dt>CUPS_PRINTER_REJECTING </dt>
+<dd class="description">Printer is rejecting jobs</dd>
+<dt>CUPS_PRINTER_REMOTE </dt>
+<dd class="description">Remote printer or class</dd>
+<dt>CUPS_PRINTER_SMALL </dt>
+<dd class="description">Can do Letter/Legal/A4</dd>
+<dt>CUPS_PRINTER_SORT </dt>
+<dd class="description">Can sort output</dd>
+<dt>CUPS_PRINTER_STAPLE </dt>
+<dd class="description">Can staple output</dd>
+<dt>CUPS_PRINTER_VARIABLE </dt>
+<dd class="description">Can do variable sizes</dd>
+</dl>
+</div>
</body>
</html>
projects / thirdparty / cups.git / blobdiff