-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
<title>CUPS API</title>
<meta name="keywords" content="Programming">
-<meta name="creator" content="Mini-XML v2.5">
+<meta name="creator" content="Mini-XML v2.6">
<style type="text/css"><!--
BODY {
font-family: lucida grande, geneva, helvetica, arial, sans-serif;
margin-left: 36pt;
}
+P.compact {
+ margin: 0;
+}
+
+P.example {
+ font-style: italic;
+ margin-left: 36pt;
+}
+
PRE.example {
background: #eeeeee;
border: dotted thin #999999;
margin-left: 36pt;
- padding: 10px;
+ padding: 10pt;
}
PRE.command EM, PRE.example EM {
}
BLOCKQUOTE {
- background: #cccccc;
+ background: #eeeeee;
border: solid thin #999999;
padding: 10pt;
}
+A IMG {
+ border: none;
+}
+
+A:link:hover IMG {
+ background: #f0f0f0;
+ border-radius: 10px;
+ -moz-border-radius: 10px;
+}
+
A:link, A:visited {
font-weight: normal;
text-decoration: none;
font-size: 50%;
}
+TR.data, TD.data, TR.data TD {
+ margin-top: 10pt;
+ padding: 5pt;
+ border-bottom: solid 1pt #999999;
+}
+
+TR.data TH {
+ border-bottom: solid 1pt #999999;
+ padding-top: 10pt;
+ padding-left: 5pt;
+ text-align: left;
+}
+
DIV.table TABLE {
border: solid thin #999999;
border-collapse: collapse;
}
TH.label {
- padding-top: 5pt;
text-align: right;
vertical-align: top;
}
+TH.sublabel {
+ text-align: right;
+ font-weight: normal;
+}
+
HR {
border: solid thin;
}
SPAN.info {
- background: #000000;
- border: thin solid #000000;
- color: #ffffff;
+ background: black;
+ border: thin solid black;
+ color: white;
font-size: 80%;
font-style: italic;
font-weight: bold;
font-size: 100%;
}
+H1.title {
+}
+
H2.title, H3.title {
border-bottom: solid 2pt #000000;
}
+DIV.indent, TABLE.indent {
+ margin-top: 2em;
+ margin-left: auto;
+ margin-right: auto;
+ width: 90%;
+}
+
+TABLE.indent {
+ border-collapse: collapse;
+}
+
+TABLE.indent TD, TABLE.indent TH {
+ padding: 0;
+}
+
+TABLE.list {
+ border-collapse: collapse;
+ margin-left: auto;
+ margin-right: auto;
+ width: 90%;
+}
+
+TABLE.list TH {
+ background: white;
+ border-bottom: solid thin #cccccc;
+ color: #444444;
+ padding-top: 10pt;
+ padding-left: 5pt;
+ text-align: left;
+ vertical-align: bottom;
+ white-space: nowrap;
+}
+
+TABLE.list TH A {
+ color: #4444cc;
+}
+
+TABLE.list TD {
+ border-bottom: solid thin #eeeeee;
+ padding-top: 5pt;
+ padding-left: 5pt;
+}
+
+TABLE.list TR:nth-child(even) {
+ background: #f8f8f8;
+}
+
+TABLE.list TR:nth-child(odd) {
+ background: #f4f4f4;
+}
+
DT {
margin-left: 36pt;
margin-top: 12pt;
font-family: monaco, courier, monospace;
}
-SPAN.message {
- font-style: italic;
- font-size: smaller;
-}
-
DIV.summary TABLE {
border: solid thin #999999;
border-collapse: collapse;
<body>
<div class='body'>
<!--
- "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
+ "$Id$"
CUPS API header for the Common UNIX Printing System (CUPS).
- Copyright 2008 by Apple Inc.
+ Copyright 2008-2009 by Apple Inc.
These coded instructions, statements, and computer programs are the
property of Apple Inc. and are protected by Federal copyright
file is missing or damaged, see the license at "http://www.cups.org/".
-->
-<h1 class="title">CUPS API</h1>
+<h1 class='title'>CUPS API</h1>
<div class='summary'><table summary='General Information'>
<thead>
</table></div>
<h2 class="title">Contents</h2>
<ul class="contents">
-</li>
+<ul class="subcontents">
<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="#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="#cupsAdminCreateWindowsPPD" title="Create the Windows PPD file for a printer.">cupsAdminCreateWindowsPPD</a></li>
+<li><a href="#cupsAdminExportSamba" title="Export a printer to Samba.">cupsAdminExportSamba</a></li>
+<li><a href="#cupsAdminGetServerSettings" title="Get settings from the server.">cupsAdminGetServerSettings</a></li>
+<li><a href="#cupsAdminSetServerSettings" title="Set settings on the server.">cupsAdminSetServerSettings</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="#cupsEncryption" title="Get the current 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="#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="#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="#cupsGetPassword2" title="Get a password from the user using the advanced
+password callback.">cupsGetPassword2</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>
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="#cupsServer" title="Return the hostname/address of the current 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="#cupsSetPasswordCB2" title="Set the advanced password callback for CUPS.">cupsSetPasswordCB2</a></li>
+<li><a href="#cupsSetServer" title="Set the default server name and port.">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>
+</ul></li>
<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_device_cb_t" title="Device callback ">cups_device_cb_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_cb2_t" title="New password callback ">cups_password_cb2_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="#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 $"
+ "$Id$"
CUPS API introduction for the Common UNIX Printing System (CUPS).
- Copyright 2007-2008 by Apple Inc.
+ Copyright 2007-2010 by Apple Inc.
Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
</tr>
<tr>
<td>"printer-is-accepting-jobs"</td>
- <td>"1" if the destination is accepting new jobs, "0" if not.</td>
+ <td>"true" if the destination is accepting new jobs, "false" 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>
+ <td>"true" if the destination is being shared with other computers,
+ "false" if not.</td>
</tr>
<tr>
<td>"printer-location"</td>
<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"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3>
+<p class="description">Create the Windows PPD file for a printer.</p>
+<p class="code">
+char *cupsAdminCreateWindowsPPD (<br>
+ http_t *http,<br>
+ const char *dest,<br>
+ char *buffer,<br>
+ int bufsize<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>dest</dt>
+<dd class="description">Printer or class</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">PPD file or NULL</p>
+<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsAdminExportSamba">cupsAdminExportSamba</a></h3>
+<p class="description">Export a printer to Samba.</p>
+<p class="code">
+int cupsAdminExportSamba (<br>
+ const char *dest,<br>
+ const char *ppd,<br>
+ const char *samba_server,<br>
+ const char *samba_user,<br>
+ const char *samba_password,<br>
+ FILE *logfile<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>dest</dt>
+<dd class="description">Destination to export</dd>
+<dt>ppd</dt>
+<dd class="description">PPD file</dd>
+<dt>samba_server</dt>
+<dd class="description">Samba server</dd>
+<dt>samba_user</dt>
+<dd class="description">Samba username</dd>
+<dt>samba_password</dt>
+<dd class="description">Samba password</dd>
+<dt>logfile</dt>
+<dd class="description">Log file, if any</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on success, 0 on failure</p>
+<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3>
+<p class="description">Get settings from the server.</p>
+<p class="code">
+int cupsAdminGetServerSettings (<br>
+ http_t *http,<br>
+ int *num_settings,<br>
+ <a href="#cups_option_t">cups_option_t</a> **settings<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_settings</dt>
+<dd class="description">Number of settings</dd>
+<dt>settings</dt>
+<dd class="description">Settings</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">The returned settings should be freed with cupsFreeOptions() when
+you are done with them.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3>
+<p class="description">Set settings on the server.</p>
+<p class="code">
+int cupsAdminSetServerSettings (<br>
+ http_t *http,<br>
+ int num_settings,<br>
+ <a href="#cups_option_t">cups_option_t</a> *settings<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_settings</dt>
+<dd class="description">Number of settings</dd>
+<dt>settings</dt>
+<dd class="description">Settings</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on success, 0 on failure</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">
<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>
+<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </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>
the cause of any failure.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsCreateJob">cupsCreateJob</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsCreateJob">cupsCreateJob</a></h3>
<p class="description">Create an empty job for streaming.</p>
<p class="code">
int cupsCreateJob (<br>
</p>
<h3 class="function"><a name="cupsEncryption">cupsEncryption</a></h3>
-<p class="description">Get the default encryption settings.</p>
+<p class="description">Get the current encryption settings.</p>
<p class="code">
http_encryption_t cupsEncryption (void);</p>
<h4 class="returnvalue">Return Value</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>
+<code>HTTP_ENCRYPT_IF_REQUESTED</code>.<br>
+<br>
+Note: The current encryption setting is tracked separately for each thread
+in a program. Multi-threaded programs that override the setting via the
+<a href="#cupsSetEncryption"><code>cupsSetEncryption</code></a> function need to do so in each thread for the same
+setting to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsFinishDocument">cupsFinishDocument</a></h3>
<p class="description">Finish sending a document.</p>
<p class="code">
ipp_status_t cupsFinishDocument (<br>
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>
+<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </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>
<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.<br>
+printer-state-reasons, and printer-type attributes as options. CUPS 1.4
+adds the marker-change-time, marker-colors, marker-high-levels,
+marker-levels, marker-low-levels, marker-message, marker-names,
+marker-types, and printer-commands attributes as well.<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>
+<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </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>
<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.<br>
+printer-state-reasons, and printer-type attributes as options. CUPS 1.4
+adds the marker-change-time, marker-colors, marker-high-levels,
+marker-levels, marker-low-levels, marker-message, marker-names,
+marker-types, and printer-commands attributes as well.<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.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>
-<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>
<h3 class="function"><a name="cupsGetJobs">cupsGetJobs</a></h3>
<p class="description">Get the jobs from the default server.</p>
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>
+<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3>
<p class="description">Get the jobs from the specified server.</p>
<p class="code">
int cupsGetJobs2 (<br>
jobs that are stopped, canceled, aborted, or completed.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </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>
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>
+each call to <code>cupsGetPPD</code> or <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>. The caller "owns" the
+file that is created and must <code>unlink</code> the returned filename.</p>
+<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </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>
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>.
+each call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a> or <code>cupsGetPPD2</code>. The caller "owns" the
+file that is created and must <code>unlink</code> the returned filename.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </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">
<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>
+file will be overwritten as needed. The caller "owns" the file that is
+created and must <code>unlink</code> the returned filename.<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
<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>
+user does not provide a password.<br>
+<br>
+Note: The current password callback function is tracked separately for each
+thread in a program. Multi-threaded programs that override the setting via
+the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to
+do so in each thread for the same function to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetPassword2">cupsGetPassword2</a></h3>
+<p class="description">Get a password from the user using the advanced
+password callback.</p>
+<p class="code">
+const char *cupsGetPassword2 (<br>
+ const char *prompt,<br>
+ http_t *http,<br>
+ const char *method,<br>
+ const char *resource<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>prompt</dt>
+<dd class="description">Prompt string</dd>
+<dt>http</dt>
+<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<dt>method</dt>
+<dd class="description">Request method ("GET", "POST", "PUT")</dd>
+<dt>resource</dt>
+<dd class="description">Resource path</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.<br>
+<br>
+Note: The current password callback function is tracked separately for each
+thread in a program. Multi-threaded programs that override the setting via
+the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to
+do so in each thread for the same function to be used.
+
+</p>
<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">
<p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
</p>
-<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </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>
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>
+<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </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>
+<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </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>
<p class="discussion">The returned string must be freed by the caller using <code>free</code>.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsNotifyText">cupsNotifyText</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </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>
</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>
+<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </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">
</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>
+<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </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">
</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>
-<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>
-<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3>
<p class="description">Remove a destination from the destination list.</p>
<p class="code">
int cupsRemoveDest (<br>
options for the user.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3>
<p class="description">Remove an option from an option array.</p>
<p class="code">
int cupsRemoveOption (<br>
<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="description">Return the hostname/address of the current 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>
-<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
+<p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the
+~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not
+set, the default is the local system - either "localhost" or a domain socket
+path.<br>
+<br>
+The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
+address, or a domain socket pathname.<br>
+<br>
+Note: The current server is tracked separately for each thread in a program.
+Multi-threaded programs that override the server via the
+<a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same
+server to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
<p class="description">Set the default destination.</p>
<p class="code">
void cupsSetDefaultDest (<br>
<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>
-<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsSetDests2">cupsSetDests2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </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>
<dt>e</dt>
<dd class="description">New encryption preference</dd>
</dl>
+<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>.<br>
+<br>
+Note: The current encryption setting is tracked separately for each thread
+in a program. Multi-threaded programs that override the setting need to do
+so in each thread for the same setting to be used.</p>
<h3 class="function"><a name="cupsSetPasswordCB">cupsSetPasswordCB</a></h3>
<p class="description">Set the password callback for CUPS.</p>
<p class="code">
<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>
+<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
+reads the password from the console. Programs should call either this
+function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
+by a program per thread.<br>
+<br>
+Note: The current password callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3>
+<p class="description">Set the advanced password callback for CUPS.</p>
+<p class="code">
+void cupsSetPasswordCB2 (<br>
+ <a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb,<br>
+ void *user_data<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>cb</dt>
+<dd class="description">Callback function</dd>
+<dt>user_data</dt>
+<dd class="description">User data pointer</dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
+reads the password from the console. Programs should call either this
+function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
+by a program per thread.<br>
+<br>
+Note: The current password callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.
+
+</p>
<h3 class="function"><a name="cupsSetServer">cupsSetServer</a></h3>
-<p class="description">Set the default server name.</p>
+<p class="description">Set the default server name and port.</p>
<p class="code">
void cupsSetServer (<br>
const char *server<br>
</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>
+IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP
+addresses can be optionally followed by a colon and port number to override
+the default port 631, e.g. "hostname:8631". Pass <code>NULL</code> to restore the
+default server name and port.<br>
+<br>
+Note: The current server is tracked separately for each thread in a program.
+Multi-threaded programs that override the server need to do so in each
+thread for the same server to be used.</p>
<h3 class="function"><a name="cupsSetUser">cupsSetUser</a></h3>
<p class="description">Set the default user name.</p>
<p class="code">
<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="discussion">Pass <code>NULL</code> to restore the default user name.<br>
+<br>
+Note: The current user name is tracked separately for each thread in a
+program. Multi-threaded programs that override the user name need to do so
+in each thread for the same user name to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </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>
<a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsTempFile2">cupsTempFile2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsTempFile2">cupsTempFile2</a></h3>
<p class="description">Creates a temporary CUPS file.</p>
<p class="code">
cups_file_t *cupsTempFile2 (<br>
const char *cupsUser (void);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">User name</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Note: The current user name is tracked separately for each thread in a
+program. Multi-threaded programs that override the user name with the
+<a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user
+name to be used.</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"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cups_device_cb_t">cups_device_cb_t</a></h3>
+<p class="description">Device callback </p>
+<p class="code">
+typedef void (*cups_device_cb_t)(const char *device_class, const char *device_id, const char *device_info, const char *device_make_and_model, const char *device_uri, const char *device_location, void *user_data);
+</p>
<h3 class="typedef"><a name="cups_job_t">cups_job_t</a></h3>
<p class="description">Job</p>
<p class="code">
<p class="code">
typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t;
</p>
+<h3 class="typedef"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cups_password_cb2_t">cups_password_cb2_t</a></h3>
+<p class="description">New password callback </p>
+<p class="code">
+typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data);
+</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 *);
+typedef const char *(*cups_password_cb_t)(const char *prompt);
</p>
<h3 class="typedef"><a name="cups_ptype_t">cups_ptype_t</a></h3>
<p class="description">Printer type/capability bits</p>
<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>
+<dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">Printer requires authentication </dd>
<dt>CUPS_PRINTER_BIND </dt>
<dd class="description">Can bind output</dd>
<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>
+<dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">Printer supports maintenance commands </dd>
<dt>CUPS_PRINTER_COPIES </dt>
<dd class="description">Can do copies</dd>
<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>
+<dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">Delete printer </dd>
-<dt>CUPS_PRINTER_DISCOVERED <span class="info"> CUPS 1.3 </span></dt>
+<dt>CUPS_PRINTER_DISCOVERED <span class="info"> CUPS 1.3/Mac OS X 10.5 </span></dt>
<dd class="description">Printer was automatically discovered and added </dd>
<dt>CUPS_PRINTER_DUPLEX </dt>
<dd class="description">Can do duplexing</dd>
<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>
+<dt>CUPS_PRINTER_MFP <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt>
+<dd class="description">Printer with scanning capabilities </dd>
+<dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">Printer is not shared </dd>
<dt>CUPS_PRINTER_PUNCH </dt>
<dd class="description">Can punch output</dd>
<dd class="description">Printer is rejecting jobs</dd>
<dt>CUPS_PRINTER_REMOTE </dt>
<dd class="description">Remote printer or class</dd>
+<dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt>
+<dd class="description">Scanner-only device </dd>
<dt>CUPS_PRINTER_SMALL </dt>
<dd class="description">Can do Letter/Legal/A4</dd>
<dt>CUPS_PRINTER_SORT </dt>