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