font-style: italic;
margin-left: 36pt;
}
-
+
+DL.man DD {
+ margin-left: 5em;
+}
+
+DL.man DT {
+ margin-left: 0;
+}
+
+PRE.man {
+ margin: 0;
+}
+
PRE.example {
background: #eeeeee;
border: dotted thin #999999;
}
A:link, A:visited {
- font-weight: normal;
+ font-weight: inherit;
text-decoration: none;
}
<body>
<div class='body'>
<!--
- "$Id$"
+ "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
CUPS API header for CUPS.
<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="#appleGetPaperSize" title="Get the default paper size.">appleGetPaperSize</a></li>
<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="#cupsCancelDestJob" title="Include necessary headers...">cupsCancelDestJob</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="#cupsCheckDestSupported" title="Check that the option and value are supported
+by the destination.">cupsCheckDestSupported</a></li>
+ <li><a href="#cupsCloseDestJob" title="Close a job and start printing.">cupsCloseDestJob</a></li>
+ <li><a href="#cupsConnectDest" title="Connect to the server for a destination.">cupsConnectDest</a></li>
+ <li><a href="#cupsConnectDestBlock" title="Connect to the server for a destination.">cupsConnectDestBlock</a></li>
+ <li><a href="#cupsCopyDest" title="Callback block">cupsCopyDest</a></li>
+ <li><a href="#cupsCopyDestConflicts" title="Get conflicts and resolutions for a new
+option/value pair.">cupsCopyDestConflicts</a></li>
+ <li><a href="#cupsCopyDestInfo" title="Get the supported values/capabilities for the
+destination.">cupsCopyDestInfo</a></li>
+ <li><a href="#cupsCreateDestJob" title="Create a job on a destination.">cupsCreateDestJob</a></li>
<li><a href="#cupsCreateJob" title="Create an empty job for streaming.">cupsCreateJob</a></li>
<li><a href="#cupsEncryption" title="Get the current encryption settings.">cupsEncryption</a></li>
+ <li><a href="#cupsEnumDests" title="Enumerate available destinations with a callback function.">cupsEnumDests</a></li>
+ <li><a href="#cupsEnumDestsBlock" title="Enumerate available destinations with a block.">cupsEnumDestsBlock</a></li>
+ <li><a href="#cupsFindDestDefault" title="Find the default value(s) for the given option.">cupsFindDestDefault</a></li>
+ <li><a href="#cupsFindDestReady" title="Find the default value(s) for the given option.">cupsFindDestReady</a></li>
+ <li><a href="#cupsFindDestSupported" title="Find the default value(s) for the given option.">cupsFindDestSupported</a></li>
+ <li><a href="#cupsFinishDestDocument" title="Finish the current document.">cupsFinishDestDocument</a></li>
<li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li>
+ <li><a href="#cupsFreeDestInfo" title="Free destination information obtained using
+cupsCopyDestInfo.">cupsFreeDestInfo</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="#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="#cupsGetDestMediaByIndex" title="Get a media name, dimension, and margins for a
+specific size.">cupsGetDestMediaByIndex</a></li>
+ <li><a href="#cupsGetDestMediaByName" title="Get media names, dimensions, and margins.">cupsGetDestMediaByName</a></li>
+ <li><a href="#cupsGetDestMediaBySize" title="Get media names, dimensions, and margins.">cupsGetDestMediaBySize</a></li>
+ <li><a href="#cupsGetDestMediaCount" title="Get the number of sizes supported by a
+destination.">cupsGetDestMediaCount</a></li>
+ <li><a href="#cupsGetDestMediaDefault" title="Get the default size for a destination.">cupsGetDestMediaDefault</a></li>
+ <li><a href="#cupsGetDestWithURI" title="Get a destination associated with a URI.">cupsGetDestWithURI</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="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</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="#cupsLocalizeDestMedia" title="Get the localized string for a destination media
+size.">cupsLocalizeDestMedia</a></li>
+ <li><a href="#cupsLocalizeDestOption" title="Get the localized string for a destination
+option.">cupsLocalizeDestOption</a></li>
+ <li><a href="#cupsLocalizeDestValue" title="Get the localized string for a destination
+option+value pair.">cupsLocalizeDestValue</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="#cupsSetServer" title="Set the default server name and port.">cupsSetServer</a></li>
<li><a href="#cupsSetServerCertCB" title="Set the server certificate callback.">cupsSetServerCertCB</a></li>
<li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li>
+ <li><a href="#cupsSetUserAgent" title="Set the default HTTP User-Agent string.">cupsSetUserAgent</a></li>
+ <li><a href="#cupsStartDestDocument" title="Start a new document.">cupsStartDestDocument</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>
+ <li><a href="#cupsUserAgent" title="Return the default HTTP User-Agent string.">cupsUserAgent</a></li>
+ <li><a href="#pwgFormatSizeName" title="Generate a PWG self-describing media size name.">pwgFormatSizeName</a></li>
+ <li><a href="#pwgInitSize" title="Initialize a pwg_size_t structure using IPP Job Template
+attributes.">pwgInitSize</a></li>
+ <li><a href="#pwgMediaForLegacy" title="Find a PWG media size by ISO/IPP legacy name.">pwgMediaForLegacy</a></li>
+ <li><a href="#pwgMediaForPPD" title="Find a PWG media size by Adobe PPD name.">pwgMediaForPPD</a></li>
+ <li><a href="#pwgMediaForPWG" title="Find a PWG media size by 5101.1 self-describing name.">pwgMediaForPWG</a></li>
+ <li><a href="#pwgMediaForSize" title="Get the PWG media size for the given dimensions.">pwgMediaForSize</a></li>
</ul></li>
<li><a href="#TYPES">Data Types</a><ul class="code">
- <li><a href="#cups_client_cert_cb_t" title="Client credentials callback ">cups_client_cert_cb_t</a></li>
+ <li><a href="#cups_client_cert_cb_t" title="Client credentials callback
+">cups_client_cert_cb_t</a></li>
+ <li><a href="#cups_dest_block_t" title="Destination enumeration block
+">cups_dest_block_t</a></li>
+ <li><a href="#cups_dest_cb_t" title="Destination enumeration callback
+">cups_dest_cb_t</a></li>
<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_device_cb_t" title="Device callback
+">cups_device_cb_t</a></li>
+ <li><a href="#cups_dinfo_t" title="Destination capability and status
+information ">cups_dinfo_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_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>
- <li><a href="#cups_server_cert_cb_t" title="Server credentials callback ">cups_server_cert_cb_t</a></li>
+ <li><a href="#cups_server_cert_cb_t" title="Server credentials callback
+">cups_server_cert_cb_t</a></li>
+ <li><a href="#cups_size_t" title="Media Size ">cups_size_t</a></li>
+ <li><a href="#pwg_map_t" title="Map element - PPD to/from PWG">pwg_map_t</a></li>
+ <li><a href="#pwg_media_t" title="Common media size data">pwg_media_t</a></li>
+ <li><a href="#pwg_size_t" title="Size element - PPD to/from PWG">pwg_size_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>
+ <li><a href="#cups_size_s" title="Media Size ">cups_size_s</a></li>
+ <li><a href="#pollfd" title="User data (unused)">pollfd</a></li>
+ <li><a href="#pwg_map_s" title="Map element - PPD to/from PWG">pwg_map_s</a></li>
+ <li><a href="#pwg_media_s" title="Common media size data">pwg_media_s</a></li>
+ <li><a href="#pwg_size_s" title="Size element - PPD to/from PWG">pwg_size_s</a></li>
</ul></li>
<li><a href="#VARIABLES">Variables</a><ul class="code">
<li><a href="#CF_RETURNS_RETAINED" title="Get the Apple language identifier associated with a
locale ID.">CF_RETURNS_RETAINED</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>
+ <li><a href="#cups_ptype_e" title="Printer type/capability bit
+constants">cups_ptype_e</a></li>
</ul></li>
</ul>
<!--
- "$Id$"
+ "$Id: api-cups.shtml 7337 2008-02-22 04:44:04Z mike $"
API introduction for CUPS.
- Copyright 2007-2011 by Apple Inc.
+ Copyright 2007-2013 by Apple Inc.
Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
<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 ++)
+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>
<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='#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>
<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) */
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="appleGetPaperSize">appleGetPaperSize</a></h3>
-<p class="description">Get the default paper size.</p>
-<p class="code">
-char *appleGetPaperSize (<br>
- char *name,<br>
- int namesize<br>
-);</p>
-<h4 class="parameters">Parameters</h4>
-<dl>
-<dt>name</dt>
-<dd class="description">Paper size name buffer</dd>
-<dt>namesize</dt>
-<dd class="description">Size of buffer</dd>
-</dl>
-<h4 class="returnvalue">Return Value</h4>
-<p class="description">Default paper size</p>
<h3 class="function"><a name="cupsAddDest">cupsAddDest</a></h3>
<p class="description">Add a destination to the list of destinations.</p>
<p class="code">
<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>
+<h3 class="function"><span class="info">
DEPRECATED </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>
</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>
+<h3 class="function"><span class="info">
DEPRECATED </span><a name="cupsAdminExportSamba">cupsAdminExportSamba</a></h3>
<p class="description">Export a printer to Samba.</p>
<p class="code">
int cupsAdminExportSamba (<br>
</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>
+<h3 class="function"><span class="info"> CUPS 1.3/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>
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>
+<h3 class="function"><span class="info"> CUPS 1.3/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>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on success, 0 on failure</p>
+<h3 class="function"><a name="cupsCancelDestJob">cupsCancelDestJob</a></h3>
+<p class="description">Include necessary headers...</p>
+<p class="code">
+ipp_status_t cupsCancelDestJob (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ int job_id<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>job_id</dt>
+<dd class="description">Job ID</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Cancel a job on a destination.</p>
+<p class="discussion">The "job_id" is the number returned by cupsCreateDestJob.<br>
+<br>
+Returns IPP_STATUS_OK on success and IPP_NOT_AUTHORIZED or IPP_FORBIDDEN 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/
Mac OS X 10.6 </span><a name="cupsCancelJob2">cupsCancelJob2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4/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/Mac OS X 10.6 </span><a name="cupsCreateJob">cupsCreateJob</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCheckDestSupported">cupsCheckDestSupported</a></h3>
+<p class="description">Check that the option and value are supported
+by the destination.</p>
+<p class="code">
+int cupsCheckDestSupported (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ const char *option,<br>
+ const char *value<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>option</dt>
+<dd class="description">Option</dd>
+<dt>value</dt>
+<dd class="description">Value</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 if supported, 0 otherwise</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Returns 1 if supported, 0 otherwise.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCloseDestJob">cupsCloseDestJob</a></h3>
+<p class="description">Close a job and start printing.</p>
+<p class="code">
+ipp_status_t cupsCloseDestJob (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br>
+ int job_id<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>info</dt>
+<dd class="description">Destination information</dd>
+<dt>job_id</dt>
+<dd class="description">Job ID</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">IPP status code</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Use when the last call to cupsStartDocument passed 0 for "last_document".
+"job_id" is the job ID returned by cupsCreateDestJob. Returns <code>IPP_STATUS_OK</code>
+on success.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsConnectDest">cupsConnectDest</a></h3>
+<p class="description">Connect to the server for a destination.</p>
+<p class="code">
+http_t *cupsConnectDest (<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ unsigned flags,<br>
+ int msec,<br>
+ int *cancel,<br>
+ char *resource,<br>
+ size_t resourcesize,<br>
+ <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br>
+ void *user_data<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>flags</dt>
+<dd class="description">Connection flags</dd>
+<dt>msec</dt>
+<dd class="description">Timeout in milliseconds</dd>
+<dt>cancel</dt>
+<dd class="description">Pointer to "cancel" variable</dd>
+<dt>resource</dt>
+<dd class="description">Resource buffer</dd>
+<dt>resourcesize</dt>
+<dd class="description">Size of resource buffer</dd>
+<dt>cb</dt>
+<dd class="description">Callback function</dd>
+<dt>user_data</dt>
+<dd class="description">User data pointer</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Connection to server or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Connect to the destination, returning a new http_t connection object and
+optionally the resource path to use for the destination. These calls will
+block until a connection is made, the timeout expires, the integer pointed
+to by "cancel" is non-zero, or the callback function (or block) returns 0,
+The caller is responsible for calling httpClose() on the returned object.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsConnectDestBlock">cupsConnectDestBlock</a></h3>
+<p class="description">Connect to the server for a destination.</p>
+<p class="code">
+http_t *cupsConnectDestBlock (<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ unsigned flags,<br>
+ int msec,<br>
+ int *cancel,<br>
+ char *resource,<br>
+ size_t resourcesize,<br>
+ <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>flags</dt>
+<dd class="description">Connection flags</dd>
+<dt>msec</dt>
+<dd class="description">Timeout in milliseconds</dd>
+<dt>cancel</dt>
+<dd class="description">Pointer to "cancel" variable</dd>
+<dt>resource</dt>
+<dd class="description">Resource buffer</dd>
+<dt>resourcesize</dt>
+<dd class="description">Size of resource buffer</dd>
+<dt>block</dt>
+<dd class="description">Callback block</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Connection to server or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Connect to the destination, returning a new http_t connection object and
+optionally the resource path to use for the destination. These calls will
+block until a connection is made, the timeout expires, the integer pointed
+to by "cancel" is non-zero, or the callback function (or block) returns 0,
+The caller is responsible for calling httpClose() on the returned object.
+
+</p>
+<h3 class="function"><a name="cupsCopyDest">cupsCopyDest</a></h3>
+<p class="description">Callback block</p>
+<p class="code">
+int cupsCopyDest (<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ int num_dests,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> **dests<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>dest</dt>
+<dt>num_dests</dt>
+<dt>dests</dt>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Copy a destination.</p>
+<p class="discussion">Make a copy of the destination to an array of destinations (or just a single
+copy) - for use with the cupsEnumDests* functions. The caller is responsible
+for calling cupsFreeDests() on the returned object(s).
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCopyDestConflicts">cupsCopyDestConflicts</a></h3>
+<p class="description">Get conflicts and resolutions for a new
+option/value pair.</p>
+<p class="code">
+int cupsCopyDestConflicts (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options,<br>
+ const char *new_option,<br>
+ const char *new_value,<br>
+ int *num_conflicts,<br>
+ <a href="#cups_option_t">cups_option_t</a> **conflicts,<br>
+ int *num_resolved,<br>
+ <a href="#cups_option_t">cups_option_t</a> **resolved<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>num_options</dt>
+<dd class="description">Number of current options</dd>
+<dt>options</dt>
+<dd class="description">Current options</dd>
+<dt>new_option</dt>
+<dd class="description">New option</dd>
+<dt>new_value</dt>
+<dd class="description">New value</dd>
+<dt>num_conflicts</dt>
+<dd class="description">Number of conflicting options</dd>
+<dt>conflicts</dt>
+<dd class="description">Conflicting options</dd>
+<dt>num_resolved</dt>
+<dd class="description">Number of options to resolve</dd>
+<dt>resolved</dt>
+<dd class="description">Resolved options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 if there is a conflict, 0 if none, -1 on error</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">"num_options" and "options" represent the currently selected options by the
+user. "new_option" and "new_value" are the setting the user has just
+changed.<br>
+<br>
+Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if
+there was an unrecoverable error such as a resolver loop.<br>
+<br>
+If "num_conflicts" and "conflicts" are not <code>NULL</code>, they are set to
+contain the list of conflicting option/value pairs. Similarly, if
+"num_resolved" and "resolved" are not <code>NULL</code> they will be set to the
+list of changes needed to resolve the conflict.<br>
+<br>
+If cupsCopyDestConflicts returns 1 but "num_resolved" and "resolved" are set
+to 0 and <code>NULL</code>, respectively, then the conflict cannot be resolved.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCopyDestInfo">cupsCopyDestInfo</a></h3>
+<p class="description">Get the supported values/capabilities for the
+destination.</p>
+<p class="code">
+<a href="#cups_dinfo_t">cups_dinfo_t</a> *cupsCopyDestInfo (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Destination information</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The caller is responsible for calling <a href="#cupsFreeDestInfo"><code>cupsFreeDestInfo</code></a> on the return
+value. <code>NULL</code> is returned on error.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCreateDestJob">cupsCreateDestJob</a></h3>
+<p class="description">Create a job on a destination.</p>
+<p class="code">
+ipp_status_t cupsCreateDestJob (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br>
+ int *job_id,<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 destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>info</dt>
+<dd class="description">Destination information</dd>
+<dt>job_id</dt>
+<dd class="description">Job ID or 0 on error</dd>
+<dt>title</dt>
+<dd class="description">Job name</dd>
+<dt>num_options</dt>
+<dd class="description">Number of job options</dd>
+<dt>options</dt>
+<dd class="description">Job options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">IPP status code</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success, saving the job ID
+in the variable pointed to by "job_id".
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.4/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 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>
+<code>HTTP_ENCRYPTION_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>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsEnumDests">cupsEnumDests</a></h3>
+<p class="description">Enumerate available destinations with a callback function.</p>
+<p class="code">
+int cupsEnumDests (<br>
+ unsigned flags,<br>
+ int msec,<br>
+ int *cancel,<br>
+ <a href="#cups_ptype_t">cups_ptype_t</a> type,<br>
+ <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br>
+ <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br>
+ void *user_data<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>flags</dt>
+<dd class="description">Enumeration flags</dd>
+<dt>msec</dt>
+<dd class="description">Timeout in milliseconds,
+-1 for indefinite</dd>
+<dt>cancel</dt>
+<dd class="description">Pointer to "cancel" variable</dd>
+<dt>type</dt>
+<dd class="description">Printer type bits</dd>
+<dt>mask</dt>
+<dd class="description">Mask for printer type bits</dd>
+<dt>cb</dt>
+<dd class="description">Callback function</dd>
+<dt>user_data</dt>
+<dd class="description">User data</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">Destinations are enumerated from one or more sources. The callback function
+receives the <code>user_data</code> pointer, destination name, instance, number of
+options, and options which can be used as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a>
+function. The function must return 1 to continue enumeration or 0 to stop.<br>
+<br>
+Enumeration happens on the current thread and does not return until all
+destinations have been enumerated or the callback function returns 0.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsEnumDestsBlock">cupsEnumDestsBlock</a></h3>
+<p class="description">Enumerate available destinations with a block.</p>
+<p class="code">
+int cupsEnumDestsBlock (<br>
+ unsigned flags,<br>
+ int timeout,<br>
+ int *cancel,<br>
+ <a href="#cups_ptype_t">cups_ptype_t</a> type,<br>
+ <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br>
+ <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>flags</dt>
+<dd class="description">Enumeration flags</dd>
+<dt>timeout</dt>
+<dd class="description">Timeout in milliseconds, 0 for indefinite</dd>
+<dt>cancel</dt>
+<dd class="description">Pointer to "cancel" variable</dd>
+<dt>type</dt>
+<dd class="description">Printer type bits</dd>
+<dt>mask</dt>
+<dd class="description">Mask for printer type bits</dd>
+<dt>block</dt>
+<dd class="description">Block</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">Destinations are enumerated from one or more sources. The block receives the
+destination name, instance, number of options, and options which can be used
+as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> function. The block must return 1 to
+continue enumeration or 0 to stop.<br>
+<br>
+Enumeration happens on the current thread and does not return until all
+destinations have been enumerated or the block returns 0.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsFindDestDefault">cupsFindDestDefault</a></h3>
+<p class="description">Find the default value(s) for the given option.</p>
+<p class="code">
+ipp_attribute_t *cupsFindDestDefault (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ const char *option<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>option</dt>
+<dd class="description">Option/attribute name</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Default attribute or <code>NULL</code> for none</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
+<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
+<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
+<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
+functions to inspect the default value(s) as needed.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsFindDestReady">cupsFindDestReady</a></h3>
+<p class="description">Find the default value(s) for the given option.</p>
+<p class="code">
+ipp_attribute_t *cupsFindDestReady (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ const char *option<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>option</dt>
+<dd class="description">Option/attribute name</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Default attribute or <code>NULL</code> for none</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
+<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
+<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
+<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
+functions to inspect the default value(s) as needed.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsFindDestSupported">cupsFindDestSupported</a></h3>
+<p class="description">Find the default value(s) for the given option.</p>
+<p class="code">
+ipp_attribute_t *cupsFindDestSupported (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ const char *option<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>option</dt>
+<dd class="description">Option/attribute name</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Default attribute or <code>NULL</code> for none</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
+<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
+<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
+<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
+functions to inspect the default value(s) as needed.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsFinishDestDocument">cupsFinishDestDocument</a></h3>
+<p class="description">Finish the current document.</p>
+<p class="code">
+ipp_status_t cupsFinishDestDocument (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *info<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>info</dt>
+<dd class="description">Destination information</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Status of document submission</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.4/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>
<p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>.
</p>
+<h3 class="function"><a name="cupsFreeDestInfo">cupsFreeDestInfo</a></h3>
+<p class="description">Free destination information obtained using
+<a href="#cupsCopyDestInfo"><code>cupsCopyDestInfo</code></a>.</p>
+<p class="code">
+void cupsFreeDestInfo (<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+</dl>
<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">
<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 class="discussion">This function is deprecated and no longer returns a list of printer
+classes - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
</p>
<h3 class="function"><a name="cupsGetDefault">cupsGetDefault</a></h3>
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/
Mac OS X 10.4 </span><a name="cupsGetDefault2">cupsGetDefault2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21/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>
<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>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></h3>
+<p class="description">Get a media name, dimension, and margins for a
+specific size.</p>
+<p class="code">
+int cupsGetDestMediaByIndex (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ int n,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>n</dt>
+<dd class="description">Media size number (0-based)</dd>
+<dt>flags</dt>
+<dd class="description">Media flags</dd>
+<dt>size</dt>
+<dd class="description">Media size information</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 <code>flags</code> parameter determines which set of media are indexed. For
+example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will get the Nth
+borderless size supported by the printer.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsGetDestMediaByName">cupsGetDestMediaByName</a></h3>
+<p class="description">Get media names, dimensions, and margins.</p>
+<p class="code">
+int cupsGetDestMediaByName (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ const char *media,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>media</dt>
+<dd class="description">Media name</dd>
+<dt>flags</dt>
+<dd class="description">Media matching flags</dd>
+<dt>size</dt>
+<dd class="description">Media size information</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on match, 0 on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The "media" string is a PWG media name. "Flags" provides some matching
+guidance (multiple flags can be combined):<br>
+<br>
+CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
+CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
+CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
+CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
+CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
+size amongst the "ready" media.<br>
+<br>
+The matching result (if any) is returned in the "cups_size_t" structure.<br>
+<br>
+Returns 1 when there is a match and 0 if there is not a match.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></h3>
+<p class="description">Get media names, dimensions, and margins.</p>
+<p class="code">
+int cupsGetDestMediaBySize (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ int width,<br>
+ int length,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>width</dt>
+<dd class="description">Media width in hundredths of
+of millimeters</dd>
+<dt>length</dt>
+<dd class="description">Media length in hundredths of
+of millimeters</dd>
+<dt>flags</dt>
+<dd class="description">Media matching flags</dd>
+<dt>size</dt>
+<dd class="description">Media size information</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on match, 0 on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">"Width" and "length" are the dimensions in hundredths of millimeters.
+"Flags" provides some matching guidance (multiple flags can be combined):<br>
+<br>
+CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
+CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
+CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
+CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
+CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
+size amongst the "ready" media.<br>
+<br>
+The matching result (if any) is returned in the "cups_size_t" structure.<br>
+<br>
+Returns 1 when there is a match and 0 if there is not a match.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsGetDestMediaCount">cupsGetDestMediaCount</a></h3>
+<p class="description">Get the number of sizes supported by a
+destination.</p>
+<p class="code">
+int cupsGetDestMediaCount (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ unsigned flags<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>flags</dt>
+<dd class="description">Media flags</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of sizes</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The <code>flags</code> parameter determines the set of media sizes that are
+counted. For example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return
+the number of borderless sizes.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></h3>
+<p class="description">Get the default size for a destination.</p>
+<p class="code">
+int cupsGetDestMediaDefault (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>flags</dt>
+<dd class="description">Media flags</dd>
+<dt>size</dt>
+<dd class="description">Media size information</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 <code>flags</code> parameter determines which default size is returned. For
+example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return the default
+borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.0 </span><a name="cupsGetDestWithURI">cupsGetDestWithURI</a></h3>
+<p class="description">Get a destination associated with a URI.</p>
+<p class="code">
+<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDestWithURI (<br>
+ const char *name,<br>
+ const char *uri<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Desired printer name or <code>NULL</code></dd>
+<dt>uri</dt>
+<dd class="description">URI for the printer</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">"name" is the desired name for the printer. If <code>NULL</code>, a name will be
+created using the URI.<br>
+<br>
+"uri" is the "ipp" or "ipps" URI for the printer.
+
+</p>
<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">
<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/
Mac OS X 10.4 </span><a name="cupsGetDests2">cupsGetDests2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21/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>
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/
Mac OS X 10.4 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21/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/
Mac OS X 10.6 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4/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>
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>. 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>
+<h3 class="function"><span class="info"> CUPS 1.1.21/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>
file that is created and must <code>unlink</code> the returned filename.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4/
Mac OS X 10.6 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4/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">
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
+On success, <code>HTTP_STATUS_OK</code> is returned for a new PPD file and
+<code>HTTP_STATUS_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
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>
+<h3 class="function"><span class="info"> CUPS 1.4/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">
<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.
+<p class="discussion">This function is deprecated and no longer returns a list of printers - use
+<a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
</p>
-<h3 class="function"><span class="info"> CUPS 1.3/
Mac OS X 10.5 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.3/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>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Language data</p>
-<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3>
+<h3 class="function"><span class="info"> CUPS 2.0 </span><a name="cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></h3>
+<p class="description">Get the localized string for a destination media
+size.</p>
+<p class="code">
+const char *cupsLocalizeDestMedia (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>flags</dt>
+<dd class="description">Media flags</dd>
+<dt>size</dt>
+<dd class="description">Media size</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Localized string</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned string is stored in the destination information and will become
+invalid if the destination information is deleted.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsLocalizeDestOption">cupsLocalizeDestOption</a></h3>
+<p class="description">Get the localized string for a destination
+option.</p>
+<p class="code">
+const char *cupsLocalizeDestOption (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ const char *option<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>option</dt>
+<dd class="description">Option to localize</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Localized string</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned string is stored in the destination information and will become
+invalid if the destination information is deleted.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsLocalizeDestValue">cupsLocalizeDestValue</a></h3>
+<p class="description">Get the localized string for a destination
+option+value pair.</p>
+<p class="code">
+const char *cupsLocalizeDestValue (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ const char *option,<br>
+ const char *value<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>option</dt>
+<dd class="description">Option to localize</dd>
+<dt>value</dt>
+<dd class="description">Value to localize</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Localized string</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned string is stored in the destination information and will become
+invalid if the destination information is deleted.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/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/
Mac OS X 10.5 </span><a name="cupsNotifyText">cupsNotifyText</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2/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/
Mac OS X 10.4 </span><a name="cupsPrintFile2">cupsPrintFile2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21/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/
Mac OS X 10.4 </span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21/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.3/
Mac OS X 10.5 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.3/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/
Mac OS X 10.5 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2/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>
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.5/
Mac OS X 10.7 </span><a name="cupsSetClientCertCB">cupsSetClientCertCB</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.5/OS X 10.7 </span><a name="cupsSetClientCertCB">cupsSetClientCertCB</a></h3>
<p class="description">Set the client certificate callback.</p>
<p class="code">
void cupsSetClientCertCB (<br>
so in each thread for the same callback to be used.
</p>
-<h3 class="function"><span class="info"> CUPS 1.5/
Mac OS X 10.7 </span><a name="cupsSetCredentials">cupsSetCredentials</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.5/OS X 10.7 </span><a name="cupsSetCredentials">cupsSetCredentials</a></h3>
<p class="description">Set the default credentials to be used for SSL/TLS
connections.</p>
<p class="code">
each thread for the same setting 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>
+<h3 class="function"><span class="info"> CUPS 1.3/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/
Mac OS X 10.4 </span><a name="cupsSetDests2">cupsSetDests2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21/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>
<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>
+<code>HTTP_ENCRYPTION_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
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>
+<h3 class="function"><span class="info"> CUPS 1.4/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>
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"><span class="info"> CUPS 1.5/
Mac OS X 10.7 </span><a name="cupsSetServerCertCB">cupsSetServerCertCB</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.5/OS X 10.7 </span><a name="cupsSetServerCertCB">cupsSetServerCertCB</a></h3>
<p class="description">Set the server certificate callback.</p>
<p class="code">
void cupsSetServerCertCB (<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>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsSetUserAgent">cupsSetUserAgent</a></h3>
+<p class="description">Set the default HTTP User-Agent string.</p>
+<p class="code">
+void cupsSetUserAgent (<br>
+ const char *user_agent<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>user_agent</dt>
+<dd class="description">User-Agent string or <code>NULL</code></dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Setting the string to NULL forces the default value containing the CUPS
+version, IPP version, and operating system version and architecture.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsStartDestDocument">cupsStartDestDocument</a></h3>
+<p class="description">Start a new document.</p>
+<p class="code">
+http_status_t cupsStartDestDocument (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br>
+ int job_id,<br>
+ const char *docname,<br>
+ const char *format,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options,<br>
+ int last_document<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>info</dt>
+<dd class="description">Destination information</dd>
+<dt>job_id</dt>
+<dd class="description">Job ID</dd>
+<dt>docname</dt>
+<dd class="description">Document name</dd>
+<dt>format</dt>
+<dd class="description">Document format</dd>
+<dt>num_options</dt>
+<dd class="description">Number of document options</dd>
+<dt>options</dt>
+<dd class="description">Document options</dd>
+<dt>last_document</dt>
+<dd class="description">1 if this is the last document</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Status of document creation</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">"job_id" is the job ID returned by cupsCreateDestJob. "docname" is the name
+of the document/file being printed, "format" is the MIME media type for the
+document (see CUPS_FORMAT_xxx constants), and "num_options" and "options"
+are the options do be applied to the document. "last_document" should be 1
+if this is the last document to be submitted in the job. Returns
+<code>HTTP_CONTINUE</code> on success.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.4/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>
<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.
+This function is deprecated and will no longer generate a temporary
+
filename - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or <a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2/
Mac OS X 10.5 </span><a name="cupsTempFile2">cupsTempFile2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2/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>
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>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsUserAgent">cupsUserAgent</a></h3>
+<p class="description">Return the default HTTP User-Agent string.</p>
+<p class="code">
+const char *cupsUserAgent (void);</p>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">User-Agent string</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="pwgFormatSizeName">pwgFormatSizeName</a></h3>
+<p class="description">Generate a PWG self-describing media size name.</p>
+<p class="code">
+int pwgFormatSizeName (<br>
+ char *keyword,<br>
+ size_t keysize,<br>
+ const char *prefix,<br>
+ const char *name,<br>
+ int width,<br>
+ int length,<br>
+ const char *units<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>keyword</dt>
+<dd class="description">Keyword buffer</dd>
+<dt>keysize</dt>
+<dd class="description">Size of keyword buffer</dd>
+<dt>prefix</dt>
+<dd class="description">Prefix for PWG size or <code>NULL</code> for automatic</dd>
+<dt>name</dt>
+<dd class="description">Size name or <code>NULL</code></dd>
+<dt>width</dt>
+<dd class="description">Width of page in 2540ths</dd>
+<dt>length</dt>
+<dd class="description">Length of page in 2540ths</dd>
+<dt>units</dt>
+<dd class="description">Units - "in", "mm", or <code>NULL</code> for automatic</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">This function generates a PWG self-describing media size name of the form
+"prefix_name_WIDTHxLENGTHunits". The prefix is typically "custom" or "roll"
+for user-supplied sizes but can also be "disc", "iso", "jis", "jpn", "na",
+"oe", "om", "prc", or "roc". A value of <code>NULL</code> automatically chooses
+"oe" or "om" depending on the units.<br>
+<br>
+The size name may only contain lowercase letters, numbers, "-", and ".". If
+<code>NULL</code> is passed, the size name will contain the formatted dimensions.<br>
+<br>
+The width and length are specified in hundredths of millimeters, equivalent
+to 1/100000th of a meter or 1/2540th of an inch. The width, length, and
+units used for the generated size name are calculated automatically if the
+units string is <code>NULL</code>, otherwise inches ("in") or millimeters ("mm")
+are used.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="pwgInitSize">pwgInitSize</a></h3>
+<p class="description">Initialize a pwg_size_t structure using IPP Job Template
+attributes.</p>
+<p class="code">
+int pwgInitSize (<br>
+ <a href="#pwg_size_t">pwg_size_t</a> *size,<br>
+ ipp_t *job,<br>
+ int *margins_set<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>size</dt>
+<dd class="description">Size to initialize</dd>
+<dt>job</dt>
+<dd class="description">Job template attributes</dd>
+<dt>margins_set</dt>
+<dd class="description">1 if margins were set, 0 otherwise</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 if size was initialized, 0 otherwise</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function initializes a pwg_size_t structure from an IPP "media" or
+"media-col" attribute in the specified IPP message. 0 is returned if neither
+attribute is found in the message or the values are not valid.<br>
+<br>
+The "margins_set" variable is initialized to 1 if any "media-xxx-margin"
+member attribute was specified in the "media-col" Job Template attribute,
+otherwise it is initialized to 0.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="pwgMediaForLegacy">pwgMediaForLegacy</a></h3>
+<p class="description">Find a PWG media size by ISO/IPP legacy name.</p>
+<p class="code">
+<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForLegacy (<br>
+ const char *legacy<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>legacy</dt>
+<dd class="description">Legacy size name</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Matching size or NULL</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The "name" argument specifies the legacy ISO media size name, for example
+"iso-a4" or "na-letter".
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="pwgMediaForPPD">pwgMediaForPPD</a></h3>
+<p class="description">Find a PWG media size by Adobe PPD name.</p>
+<p class="code">
+<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPPD (<br>
+ const char *ppd<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>ppd</dt>
+<dd class="description">PPD size name</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Matching size or NULL</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The "ppd" argument specifies an Adobe page size name as defined in Table B.1
+of the Adobe PostScript Printer Description File Format Specification Version
+4.3.<br>
+<br>
+If the name is non-standard, the returned PWG media size is stored in
+thread-local storage and is overwritten by each call to the function in the
+thread. Custom names can be of the form "Custom.WIDTHxLENGTH[units]" or
+"WIDTHxLENGTH[units]".
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="pwgMediaForPWG">pwgMediaForPWG</a></h3>
+<p class="description">Find a PWG media size by 5101.1 self-describing name.</p>
+<p class="code">
+<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPWG (<br>
+ const char *pwg<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>pwg</dt>
+<dd class="description">PWG size name</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Matching size or NULL</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The "pwg" argument specifies a self-describing media size name of the form
+"prefix_name_WIDTHxLENGTHunits" as defined in PWG 5101.1.<br>
+<br>
+If the name is non-standard, the returned PWG media size is stored in
+thread-local storage and is overwritten by each call to the function in the
+thread.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="pwgMediaForSize">pwgMediaForSize</a></h3>
+<p class="description">Get the PWG media size for the given dimensions.</p>
+<p class="code">
+<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForSize (<br>
+ int width,<br>
+ int length<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>width</dt>
+<dd class="description">Width in hundredths of millimeters</dd>
+<dt>length</dt>
+<dd class="description">Length in hundredths of millimeters</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">PWG media name</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The "width" and "length" are in hundredths of millimeters, equivalent to
+1/100000th of a meter or 1/2540th of an inch.<br>
+<br>
+If the dimensions are non-standard, the returned PWG media size is stored in
+thread-local storage and is overwritten by each call to the function in the
+thread.
+
+</p>
<h2 class="title"><a name="TYPES">Data Types</a></h2>
-<h3 class="typedef"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cups_client_cert_cb_t">cups_client_cert_cb_t</a></h3>
-<p class="description">Client credentials callback </p>
+<h3 class="typedef"><span class="info"> CUPS 1.5/OS X 10.7 </span><a name="cups_client_cert_cb_t">cups_client_cert_cb_t</a></h3>
+<p class="description">Client credentials callback
+</p>
<p class="code">
typedef int (*cups_client_cert_cb_t)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data);
</p>
+<h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_dest_block_t">cups_dest_block_t</a></h3>
+<p class="description">Destination enumeration block
+</p>
+<p class="code">
+typedef int (*cups_dest_block_t(unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest);
+</p>
+<h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_dest_cb_t">cups_dest_cb_t</a></h3>
+<p class="description">Destination enumeration callback
+</p>
+<p class="code">
+typedef int (*cups_dest_cb_t)(void *user_data, unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest);
+</p>
<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>
+<h3 class="typedef"><span class="info"> CUPS 1.4/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"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_dinfo_t">cups_dinfo_t</a></h3>
+<p class="description">Destination capability and status
+information </p>
+<p class="code">
+typedef struct _cups_dinfo_s cups_dinfo_t;
+</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>
+<h3 class="typedef"><span class="info"> CUPS 1.4/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>
<p class="code">
typedef unsigned cups_ptype_t;
</p>
-<h3 class="typedef"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cups_server_cert_cb_t">cups_server_cert_cb_t</a></h3>
-<p class="description">Server credentials callback </p>
+<h3 class="typedef"><span class="info"> CUPS 1.5/OS X 10.7 </span><a name="cups_server_cert_cb_t">cups_server_cert_cb_t</a></h3>
+<p class="description">Server credentials callback
+</p>
<p class="code">
typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *certs, void *user_data);
</p>
+<h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_size_t">cups_size_t</a></h3>
+<p class="description">Media Size </p>
+<p class="code">
+typedef struct <a href="#cups_size_s">cups_size_s</a> cups_size_t;
+</p>
+<h3 class="typedef"><a name="pwg_map_t">pwg_map_t</a></h3>
+<p class="description">Map element - PPD to/from PWG</p>
+<p class="code">
+typedef struct <a href="#pwg_map_s">pwg_map_s</a> pwg_map_t;
+</p>
+<h3 class="typedef"><a name="pwg_media_t">pwg_media_t</a></h3>
+<p class="description">Common media size data</p>
+<p class="code">
+typedef struct <a href="#pwg_media_s">pwg_media_s</a> pwg_media_t;
+</p>
+<h3 class="typedef"><a name="pwg_size_t">pwg_size_t</a></h3>
+<p class="description">Size element - PPD to/from PWG</p>
+<p class="code">
+typedef struct <a href="#pwg_size_s">pwg_size_s</a> pwg_size_t;
+</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>
<dt>value </dt>
<dd class="description">Value of option</dd>
</dl>
+<h3 class="struct"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_size_s">cups_size_s</a></h3>
+<p class="description">Media Size </p>
+<p class="code">struct cups_size_s {<br>
+ char media[128];<br>
+ int width, length, bottom, left, right, top;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>media[128] </dt>
+<dd class="description">Media name to use</dd>
+<dt>top </dt>
+<dd class="description">Top margin in hundredths of
+millimeters</dd>
+</dl>
+<h3 class="struct"><a name="pollfd">pollfd</a></h3>
+<p class="description">User data (unused)</p>
+<p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br>
+ _cups_dnssd_data_t *data;<br>
+ else if(val 0) data - got_data;<br>
+ void) timeout;<br>
+ int val;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>data </dt>
+<dd class="description">Enumeration data</dd>
+<dt>got_data </dt>
+<dt>timeout </dt>
+<dt>val </dt>
+<dd class="description">Return value</dd>
+</dl>
+<h3 class="struct"><a name="pwg_map_s">pwg_map_s</a></h3>
+<p class="description">Map element - PPD to/from PWG</p>
+<p class="code">struct pwg_map_s {<br>
+ char *pwg, *ppd;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>ppd </dt>
+<dd class="description">PPD option keyword</dd>
+</dl>
+<h3 class="struct"><a name="pwg_media_s">pwg_media_s</a></h3>
+<p class="description">Common media size data</p>
+<p class="code">struct pwg_media_s {<br>
+ int width, length;<br>
+ const char *pwg, *legacy, *ppd;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>length </dt>
+<dd class="description">Length in 2540ths</dd>
+<dt>ppd </dt>
+<dd class="description">Standard Adobe PPD name</dd>
+</dl>
+<h3 class="struct"><a name="pwg_size_s">pwg_size_s</a></h3>
+<p class="description">Size element - PPD to/from PWG</p>
+<p class="code">struct pwg_size_s {<br>
+ <a href="#pwg_map_t">pwg_map_t</a> map;<br>
+ int width, length, left, bottom, right, top;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>map </dt>
+<dd class="description">Map element</dd>
+<dt>top </dt>
+<dd class="description">Top margin in 2540ths</dd>
+</dl>
<h2 class="title"><a name="VARIABLES">Variables</a></h2>
<h3 class="variable"><a name="CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></h3>
<p class="description">Get the Apple language identifier associated with a
<p class="code">const char *locale) CF_RETURNS_RETAINED;</p>
<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>
+<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/Mac OS X 10.5 </span></dt>
-<dd class="description">Printer requires authentication </dd>
+<dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/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>
<dt>CUPS_PRINTER_BW </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/Mac OS X 10.5 </span></dt>
-<dd class="description">Printer supports maintenance commands </dd>
+<dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/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>
<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/Mac OS X 10.5 </span></dt>
-<dd class="description">Delete printer </dd>
-<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_DELETE <span class="info"> CUPS 1.2/OS X 10.5 </span></dt>
+<dd class="description">Delete printer
+</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_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_MFP <span class="info"> CUPS 1.4/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/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>
<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_SCANNER <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt>
-<dd class="description">Scanner-only device </dd>
+<dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/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>
projects / thirdparty / cups.git / blobdiff