-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
-<title>CUPS API</title>
-<meta name="keywords" content="Programming">
-<meta name="creator" content="Mini-XML v2.5">
+ <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;
}
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: 10px;
+ padding: 10pt;
}
PRE.command EM, PRE.example EM {
}
BLOCKQUOTE {
- background: #cccccc;
+ background: #eeeeee;
border: solid thin #999999;
padding: 10pt;
}
+A IMG {
+ border: none;
+}
+
+A:link:hover IMG {
+ background: #f0f0f0;
+ border-radius: 10px;
+ -moz-border-radius: 10px;
+}
+
A:link, A:visited {
- font-weight: normal;
+ font-weight: inherit;
text-decoration: none;
}
font-size: 50%;
}
+TR.data, TD.data, TR.data TD {
+ margin-top: 10pt;
+ padding: 5pt;
+ border-bottom: solid 1pt #999999;
+}
+
+TR.data TH {
+ border-bottom: solid 1pt #999999;
+ padding-top: 10pt;
+ padding-left: 5pt;
+ text-align: left;
+}
+
DIV.table TABLE {
border: solid thin #999999;
border-collapse: collapse;
}
TH.label {
- padding-top: 5pt;
text-align: right;
vertical-align: top;
}
+TH.sublabel {
+ text-align: right;
+ font-weight: normal;
+}
+
HR {
border: solid thin;
}
SPAN.info {
- background: #000000;
- border: thin solid #000000;
- color: #ffffff;
+ background: black;
+ border: thin solid black;
+ color: white;
font-size: 80%;
font-style: italic;
font-weight: bold;
font-size: 100%;
}
+H1.title {
+}
+
H2.title, H3.title {
border-bottom: solid 2pt #000000;
}
+DIV.indent, TABLE.indent {
+ margin-top: 2em;
+ margin-left: auto;
+ margin-right: auto;
+ width: 90%;
+}
+
+TABLE.indent {
+ border-collapse: collapse;
+}
+
+TABLE.indent TD, TABLE.indent TH {
+ padding: 0;
+}
+
+TABLE.list {
+ border-collapse: collapse;
+ margin-left: auto;
+ margin-right: auto;
+ width: 90%;
+}
+
+TABLE.list TH {
+ background: white;
+ border-bottom: solid thin #cccccc;
+ color: #444444;
+ padding-top: 10pt;
+ padding-left: 5pt;
+ text-align: left;
+ vertical-align: bottom;
+ white-space: nowrap;
+}
+
+TABLE.list TH A {
+ color: #4444cc;
+}
+
+TABLE.list TD {
+ border-bottom: solid thin #eeeeee;
+ padding-top: 5pt;
+ padding-left: 5pt;
+}
+
+TABLE.list TR:nth-child(even) {
+ background: #f8f8f8;
+}
+
+TABLE.list TR:nth-child(odd) {
+ background: #f4f4f4;
+}
+
DT {
margin-left: 36pt;
margin-top: 12pt;
font-family: monaco, courier, monospace;
}
-SPAN.message {
- font-style: italic;
- font-size: smaller;
-}
-
DIV.summary TABLE {
border: solid thin #999999;
border-collapse: collapse;
<!--
"$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
- CUPS API header for the Common UNIX Printing System (CUPS).
+ CUPS API header for CUPS.
- Copyright 2008 by Apple Inc.
+ 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
file is missing or damaged, see the license at "http://www.cups.org/".
-->
-<h1 class="title">CUPS API</h1>
+<h1 class='title'>CUPS API</h1>
<div class='summary'><table summary='General Information'>
<thead>
</table></div>
<h2 class="title">Contents</h2>
<ul class="contents">
-</li>
<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>
+
<li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li>
+
<li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li>
+
<li><a href="#OPTIONS">Options</a></li>
+
<li><a href="#PRINT_JOBS">Print Jobs</a></li>
+
<li><a href="#ERROR_HANDLING">Error Handling</a></li>
+
<li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li>
</ul></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
-<li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li>
-<li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li>
-<li><a href="#cupsCancelJob" title="Cancel a print job on the default server.">cupsCancelJob</a></li>
-<li><a href="#cupsCancelJob2" title="Cancel or purge a print job.">cupsCancelJob2</a></li>
-<li><a href="#cupsCreateJob" title="Create an empty job for streaming.">cupsCreateJob</a></li>
-<li><a href="#cupsEncryption" title="Get the default encryption settings.">cupsEncryption</a></li>
-<li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li>
-<li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li>
-<li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li>
-<li><a href="#cupsFreeOptions" title="Free all memory used by options.">cupsFreeOptions</a></li>
-<li><a href="#cupsGetClasses" title="Get a list of printer classes from the default server.">cupsGetClasses</a></li>
-<li><a href="#cupsGetDefault" title="Get the default printer or class for the default server.">cupsGetDefault</a></li>
-<li><a href="#cupsGetDefault2" title="Get the default printer or class for the specified server.">cupsGetDefault2</a></li>
-<li><a href="#cupsGetDest" title="Get the named destination from the list.">cupsGetDest</a></li>
-<li><a href="#cupsGetDests" title="Get the list of destinations from the default server.">cupsGetDests</a></li>
-<li><a href="#cupsGetDests2" title="Get the list of destinations from the specified server.">cupsGetDests2</a></li>
-<li><a href="#cupsGetFd" title="Get a file from the server.">cupsGetFd</a></li>
-<li><a href="#cupsGetFile" title="Get a file from the server.">cupsGetFile</a></li>
-<li><a href="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</a></li>
-<li><a href="#cupsGetJobs2" title="Get the jobs from the specified server.">cupsGetJobs2</a></li>
-<li><a href="#cupsGetNamedDest" title="Get options for the named destination.">cupsGetNamedDest</a></li>
-<li><a href="#cupsGetOption" title="Get an option value.">cupsGetOption</a></li>
-<li><a href="#cupsGetPPD" title="Get the PPD file for a printer on the default server.">cupsGetPPD</a></li>
-<li><a href="#cupsGetPPD2" title="Get the PPD file for a printer from the specified server.">cupsGetPPD2</a></li>
-<li><a href="#cupsGetPPD3" title="Get the PPD file for a printer on the specified
+ <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="#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.)
+ <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="#cupsLastError" title="Return the last IPP status code.">cupsLastError</a></li>
-<li><a href="#cupsLastErrorString" title="Return the last IPP status-message.">cupsLastErrorString</a></li>
-<li><a href="#cupsNotifySubject" title="Return the subject for the given notification message.">cupsNotifySubject</a></li>
-<li><a href="#cupsNotifyText" title="Return the text for the given notification message.">cupsNotifyText</a></li>
-<li><a href="#cupsParseOptions" title="Parse options from a command-line argument.">cupsParseOptions</a></li>
-<li><a href="#cupsPrintFile" title="Print a file to a printer or class on the default server.">cupsPrintFile</a></li>
-<li><a href="#cupsPrintFile2" title="Print a file to a printer or class on the specified
+ <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
+
<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
+
<li><a href="#cupsPrintFiles2" title="Print one or more files to a printer or class on the
specified server.">cupsPrintFiles2</a></li>
-<li><a href="#cupsPutFd" title="Put a file on the server.">cupsPutFd</a></li>
-<li><a href="#cupsPutFile" title="Put a file on the server.">cupsPutFile</a></li>
-<li><a href="#cupsRemoveDest" title="Remove a destination from the destination list.">cupsRemoveDest</a></li>
-<li><a href="#cupsRemoveOption" title="Remove an option from an option array.">cupsRemoveOption</a></li>
-<li><a href="#cupsServer" title="Return the hostname/address of the default server.">cupsServer</a></li>
-<li><a href="#cupsSetDefaultDest" title="Set the default destination.">cupsSetDefaultDest</a></li>
-<li><a href="#cupsSetDests" title="Save the list of destinations for the default server.">cupsSetDests</a></li>
-<li><a href="#cupsSetDests2" title="Save the list of destinations for the specified server.">cupsSetDests2</a></li>
-<li><a href="#cupsSetEncryption" title="Set the encryption preference.">cupsSetEncryption</a></li>
-<li><a href="#cupsSetPasswordCB" title="Set the password callback for CUPS.">cupsSetPasswordCB</a></li>
-<li><a href="#cupsSetServer" title="Set the default server name.">cupsSetServer</a></li>
-<li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li>
-<li><a href="#cupsStartDocument" title="Add a document to a job created with cupsCreateJob().">cupsStartDocument</a></li>
-<li><a href="#cupsTempFd" title="Creates a temporary file.">cupsTempFd</a></li>
-<li><a href="#cupsTempFile" title="Generates a temporary filename.">cupsTempFile</a></li>
-<li><a href="#cupsTempFile2" title="Creates a temporary CUPS file.">cupsTempFile2</a></li>
-<li><a href="#cupsUser" title="Return the current user's name.">cupsUser</a></li>
-</ul>
+ <li><a href="#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>
+ <li><a href="#cups_ptype_e" title="Printer type/capability bit
+constants">cups_ptype_e</a></li>
</ul></li>
</ul>
<!--
"$Id: api-cups.shtml 7337 2008-02-22 04:44:04Z mike $"
- CUPS API introduction for the Common UNIX Printing System (CUPS).
+ API introduction for CUPS.
- Copyright 2007-2008 by Apple Inc.
+ Copyright 2007-2013 by Apple Inc.
Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
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);
-/* do something wiith dest */
+/* do something with dest */
<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
</pre>
</tr>
<tr>
<td>"printer-is-accepting-jobs"</td>
- <td>"1" if the destination is accepting new jobs, "0" if not.</td>
+ <td>"true" if the destination is accepting new jobs, "false" if
+ not.</td>
</tr>
<tr>
<td>"printer-is-shared"</td>
- <td>"1" if the destination is being shared with other computers, "0" if
- not.</td>
+ <td>"true" if the destination is being shared with other computers,
+ "false" if not.</td>
</tr>
<tr>
<td>"printer-location"</td>
<a href='#cups_option_t'>cups_option_t</a> *options = NULL;
<a href='#cups_dest_t'>cups_dest_t</a> *dest;
-for (i = 0; i < dest->num_options; i ++)
+for (i = 0; i < dest->num_options; i ++)
num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value,
num_options, &options);
</pre>
<p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a>
function creates a new job with no files in it. Files are added using the
-<a href='#cupsStartDocument'><code>cupsStartDocument</code></a>,
+<a href='#cupsStartDocument'><code>cupsStartDocument</code></a>,
<a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>,
and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions.
The following example creates a job with 10 text files for printing:</p>
<a href='#cups_job_t'>cups_job_t</a> *jobs;
int i;
ipp_jstate_t job_state = IPP_JOB_PENDING;
-
+
while (job_state < IPP_JOB_STOPPED)
{
/* Get my jobs (1) with any state (-1) */
<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">
<br>
Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get
the cause of any failure.</p>
-<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsCancelJob2">cupsCancelJob2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4
/OS X 10.6 </span><a name="cupsCancelJob2">cupsCancelJob2</a></h3>
<p class="description">Cancel or purge a print job.</p>
<p class="code">
ipp_status_t cupsCancelJob2 (<br>
the cause of any failure.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsCreateJob">cupsCreateJob</a></h3>
-<p class="description">Create an empty job for streaming.</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 cupsCreateJob (<br>
+int cupsCheckDestSupported (<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>
+ <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 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>
+<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">Job ID or 0 on error</p>
+<p class="description">1 if supported, 0 otherwise</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 class="discussion">Returns 1 if supported, 0 otherwise.
</p>
-<h3 class="function"><a name="cupsEncryption">cupsEncryption</a></h3>
-<p class="description">Get the default encryption settings.</p>
-<p class="code">
-http_encryption_t cupsEncryption (void);</p>
-<h4 class="returnvalue">Return Value</h4>
-<p class="description">Encryption settings</p>
-<h4 class="discussion">Discussion</h4>
-<p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
-environment variable, then the ~/.cups/client.conf file, and finally the
-/etc/cups/client.conf file. If not set, the default is
-<code>HTTP_ENCRYPT_IF_REQUESTED</code>.</p>
-<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsFinishDocument">cupsFinishDocument</a></h3>
-<p class="description">Finish sending a document.</p>
+<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 cupsFinishDocument (<br>
+ipp_status_t cupsCloseDestJob (<br>
http_t *http,<br>
- const char *name<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 server or <code>CUPS_HTTP_DEFAULT</code></dd>
-<dt>name</dt>
-<dd class="description">Destination name</dd>
+<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">Status of document submission</p>
+<p class="description">IPP status code</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>.
+<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"><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>
+<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>num_dests</dt>
-<dd class="description">Number of destinations</dd>
-<dt>dests</dt>
-<dd class="description">Destinations</dd>
+<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>
-<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>
+<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>num_jobs</dt>
-<dd class="description">Number of jobs</dd>
-<dt>jobs</dt>
-<dd class="description">Jobs</dd>
+<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>
-<h3 class="function"><a name="cupsFreeOptions">cupsFreeOptions</a></h3>
-<p class="description">Free all memory used by options.</p>
+<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">
-void cupsFreeOptions (<br>
- int num_options,<br>
- <a href="#cups_option_t">cups_option_t</a> *options<br>
+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>num_options</dt>
-<dd class="description">Number of options</dd>
-<dt>options</dt>
-<dd class="description">Pointer to options</dd>
+<dt>dest</dt>
+<dt>num_dests</dt>
+<dt>dests</dt>
</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>
+<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 cupsGetClasses (<br>
- char ***classes<br>
+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>classes</dt>
-<dd class="description">Classes</dd>
+<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">Number of classes</p>
+<p class="description">1 if there is a conflict, 0 if none, -1 on error</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
+<p class="discussion">"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"><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 <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a>
-functions to get the user-defined default printer, as this function does
-not support the lpoptions-defined default printer.</p>
-<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsGetDefault2">cupsGetDefault2</a></h3>
-<p class="description">Get the default printer or class for the specified server.</p>
+<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">
-const char *cupsGetDefault2 (<br>
- http_t *http<br>
+<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 server or <code>CUPS_HTTP_DEFAULT</code></dd>
+<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">Default printer or <code>NULL</code></p>
+<p class="description">Destination information</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
+<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 <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
<h4 class="discussion">Discussion</h4>
<p class="discussion">Use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a
list of supported destinations for the current user.</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></h3>
+<p class="description">Get a media name, dimension, and margins for a
+specific size.</p>
+<p class="code">
+int cupsGetDestMediaByIndex (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ int n,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>n</dt>
+<dd class="description">Media size number (0-based)</dd>
+<dt>flags</dt>
+<dd class="description">Media flags</dd>
+<dt>size</dt>
+<dd class="description">Media size information</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on success, 0 on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The <code>flags</code> parameter determines which set of media are indexed. For
+example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will get the Nth
+borderless size supported by the printer.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsGetDestMediaByName">cupsGetDestMediaByName</a></h3>
+<p class="description">Get media names, dimensions, and margins.</p>
+<p class="code">
+int cupsGetDestMediaByName (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ const char *media,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>media</dt>
+<dd class="description">Media name</dd>
+<dt>flags</dt>
+<dd class="description">Media matching flags</dd>
+<dt>size</dt>
+<dd class="description">Media size information</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on match, 0 on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The "media" string is a PWG media name. "Flags" provides some matching
+guidance (multiple flags can be combined):<br>
+<br>
+CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
+CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
+CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
+CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
+CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
+size amongst the "ready" media.<br>
+<br>
+The matching result (if any) is returned in the "cups_size_t" structure.<br>
+<br>
+Returns 1 when there is a match and 0 if there is not a match.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></h3>
+<p class="description">Get media names, dimensions, and margins.</p>
+<p class="code">
+int cupsGetDestMediaBySize (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ int width,<br>
+ int length,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>width</dt>
+<dd class="description">Media width in hundredths of
+of millimeters</dd>
+<dt>length</dt>
+<dd class="description">Media length in hundredths of
+of millimeters</dd>
+<dt>flags</dt>
+<dd class="description">Media matching flags</dd>
+<dt>size</dt>
+<dd class="description">Media size information</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on match, 0 on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">"Width" and "length" are the dimensions in hundredths of millimeters.
+"Flags" provides some matching guidance (multiple flags can be combined):<br>
+<br>
+CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
+CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
+CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
+CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
+CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
+size amongst the "ready" media.<br>
+<br>
+The matching result (if any) is returned in the "cups_size_t" structure.<br>
+<br>
+Returns 1 when there is a match and 0 if there is not a match.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsGetDestMediaCount">cupsGetDestMediaCount</a></h3>
+<p class="description">Get the number of sizes supported by a
+destination.</p>
+<p class="code">
+int cupsGetDestMediaCount (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ unsigned flags<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>flags</dt>
+<dd class="description">Media flags</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of sizes</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The <code>flags</code> parameter determines the set of media sizes that are
+counted. For example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return
+the number of borderless sizes.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></h3>
+<p class="description">Get the default size for a destination.</p>
+<p class="code">
+int cupsGetDestMediaDefault (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>flags</dt>
+<dd class="description">Media flags</dd>
+<dt>size</dt>
+<dd class="description">Media size information</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on success, 0 on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The <code>flags</code> parameter determines which default size is returned. For
+example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return the default
+borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 2.0 </span><a name="cupsGetDestWithURI">cupsGetDestWithURI</a></h3>
+<p class="description">Get a destination associated with a URI.</p>
+<p class="code">
+<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDestWithURI (<br>
+ const char *name,<br>
+ const char *uri<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Desired printer name or <code>NULL</code></dd>
+<dt>uri</dt>
+<dd class="description">URI for the printer</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Destination or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">"name" is the desired name for the printer. If <code>NULL</code>, a name will be
+created using the URI.<br>
+<br>
+"uri" is the "ipp" or "ipps" URI for the printer.
+
+</p>
<h3 class="function"><a name="cupsGetDests">cupsGetDests</a></h3>
<p class="description">Get the list of destinations from the default server.</p>
<p class="code">
<p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
printer-info, printer-is-accepting-jobs, printer-is-shared,
printer-make-and-model, printer-state, printer-state-change-time,
-printer-state-reasons, and printer-type attributes as options.<br>
+printer-state-reasons, and printer-type attributes as options. CUPS 1.4
+adds the marker-change-time, marker-colors, marker-high-levels,
+marker-levels, marker-low-levels, marker-message, marker-names,
+marker-types, and printer-commands attributes as well.<br>
<br>
Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.</p>
-<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsGetDests2">cupsGetDests2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21
/OS X 10.4 </span><a name="cupsGetDests2">cupsGetDests2</a></h3>
<p class="description">Get the list of destinations from the specified server.</p>
<p class="code">
int cupsGetDests2 (<br>
<p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
printer-info, printer-is-accepting-jobs, printer-is-shared,
printer-make-and-model, printer-state, printer-state-change-time,
-printer-state-reasons, and printer-type attributes as options.<br>
+printer-state-reasons, and printer-type attributes as options. CUPS 1.4
+adds the marker-change-time, marker-colors, marker-high-levels,
+marker-levels, marker-low-levels, marker-message, marker-names,
+marker-types, and printer-commands attributes as well.<br>
<br>
Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.
-</p>
-<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsGetFd">cupsGetFd</a></h3>
-<p class="description">Get a file from the server.</p>
-<p class="code">
-http_status_t cupsGetFd (<br>
- http_t *http,<br>
- const char *resource,<br>
- int fd<br>
-);</p>
-<h4 class="parameters">Parameters</h4>
-<dl>
-<dt>http</dt>
-<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
-<dt>resource</dt>
-<dd class="description">Resource name</dd>
-<dt>fd</dt>
-<dd class="description">File descriptor</dd>
-</dl>
-<h4 class="returnvalue">Return Value</h4>
-<p class="description">HTTP status</p>
-<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved.
-
-</p>
-<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsGetFile">cupsGetFile</a></h3>
-<p class="description">Get a file from the server.</p>
-<p class="code">
-http_status_t cupsGetFile (<br>
- http_t *http,<br>
- const char *resource,<br>
- const char *filename<br>
-);</p>
-<h4 class="parameters">Parameters</h4>
-<dl>
-<dt>http</dt>
-<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
-<dt>resource</dt>
-<dd class="description">Resource name</dd>
-<dt>filename</dt>
-<dd class="description">Filename</dd>
-</dl>
-<h4 class="returnvalue">Return Value</h4>
-<p class="description">HTTP status</p>
-<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved.
-
</p>
<h3 class="function"><a name="cupsGetJobs">cupsGetJobs</a></h3>
<p class="description">Get the jobs from the default server.</p>
of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
jobs that are stopped, canceled, aborted, or completed.</p>
-<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21
/OS X 10.4 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3>
<p class="description">Get the jobs from the specified server.</p>
<p class="code">
int cupsGetJobs2 (<br>
jobs that are stopped, canceled, aborted, or completed.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4
/OS X 10.6 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3>
<p class="description">Get options for the named destination.</p>
<p class="code">
<a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br>
in the class.<br>
<br>
The returned filename is stored in a static buffer and is overwritten with
-each call to <code>cupsGetPPD</code> or <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>.</p>
-<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsGetPPD2">cupsGetPPD2</a></h3>
+each call to <code>cupsGetPPD</code> or <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>. The caller "owns" the
+file that is created and must <code>unlink</code> the returned filename.</p>
+<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsGetPPD2">cupsGetPPD2</a></h3>
<p class="description">Get the PPD file for a printer from the specified server.</p>
<p class="code">
const char *cupsGetPPD2 (<br>
in the class.<br>
<br>
The returned filename is stored in a static buffer and is overwritten with
-each call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a> or <code>cupsGetPPD2</code>.
+each call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a> or <code>cupsGetPPD2</code>. The caller "owns" the
+file that is created and must <code>unlink</code> the returned filename.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4
/OS X 10.6 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3>
<p class="description">Get the PPD file for a printer on the specified
server if it has changed.</p>
<p class="code">
<br>
The "buffer" parameter contains the local PPD filename. If it contains
the empty string, a new temporary file is created, otherwise the existing
-file will be overwritten as needed.<br>
+file will be overwritten as needed. The caller "owns" the file that is
+created and must <code>unlink</code> the returned filename.<br>
<br>
-On success, <code>HTTP_OK</code> is returned for a new PPD file and
-<code>HTTP_NOT_MODIFIED</code> if the existing PPD file is up-to-date. Any other
+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
<p class="description">Password</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
-user does not provide a password.</p>
+user does not provide a password.<br>
+<br>
+Note: The current password callback function is tracked separately for each
+thread in a program. Multi-threaded programs that override the setting via
+the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to
+do so in each thread for the same function to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.4/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">
<h4 class="returnvalue">Return Value</h4>
<p class="description">Number of printers</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
+<p class="discussion">This function is deprecated and no longer returns a list of printers - use
+<a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
</p>
-<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.3
/OS X 10.5 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3>
<p class="description">Get an available PPD file from the server.</p>
<p class="code">
char *cupsGetServerPPD (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Language data</p>
-<h3 class="function"><a name="cupsLastError">cupsLastError</a></h3>
-<p class="description">Return the last IPP status code.</p>
+<h3 class="function"><span class="info"> CUPS 2.0 </span><a name="cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></h3>
+<p class="description">Get the localized string for a destination media
+size.</p>
+<p class="code">
+const char *cupsLocalizeDestMedia (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br>
+ unsigned flags,<br>
+ <a href="#cups_size_t">cups_size_t</a> *size<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>dinfo</dt>
+<dd class="description">Destination information</dd>
+<dt>flags</dt>
+<dd class="description">Media flags</dd>
+<dt>size</dt>
+<dd class="description">Media size</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Localized string</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned string is stored in the destination information and will become
+invalid if the destination information is deleted.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsLocalizeDestOption">cupsLocalizeDestOption</a></h3>
+<p class="description">Get the localized string for a destination
+option.</p>
<p class="code">
-ipp_status_t cupsLastError (void);</p>
+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">IPP status code from last request</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsLastErrorString">cupsLastErrorString</a></h3>
-<p class="description">Return the last IPP status-message.</p>
+<p class="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 *cupsLastErrorString (void);</p>
+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">status-message text from last request</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3>
+<p class="description">Localized string</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The returned string is stored in the destination information and will become
+invalid if the destination information is deleted.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3>
<p class="description">Return the subject for the given notification message.</p>
<p class="code">
char *cupsNotifySubject (<br>
<p class="discussion">The returned string must be freed by the caller using <code>free</code>.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsNotifyText">cupsNotifyText</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsNotifyText">cupsNotifyText</a></h3>
<p class="description">Return the text for the given notification message.</p>
<p class="code">
char *cupsNotifyText (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Job ID or 0 on error</p>
-<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsPrintFile2">cupsPrintFile2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21
/OS X 10.4 </span><a name="cupsPrintFile2">cupsPrintFile2</a></h3>
<p class="description">Print a file to a printer or class on the specified
server.</p>
<p class="code">
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Job ID or 0 on error</p>
-<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21
/OS X 10.4 </span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3>
<p class="description">Print one or more files to a printer or class on the
specified server.</p>
<p class="code">
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Job ID or 0 on error</p>
-<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsPutFd">cupsPutFd</a></h3>
-<p class="description">Put a file on the server.</p>
-<p class="code">
-http_status_t cupsPutFd (<br>
- http_t *http,<br>
- const char *resource,<br>
- int fd<br>
-);</p>
-<h4 class="parameters">Parameters</h4>
-<dl>
-<dt>http</dt>
-<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
-<dt>resource</dt>
-<dd class="description">Resource name</dd>
-<dt>fd</dt>
-<dd class="description">File descriptor</dd>
-</dl>
-<h4 class="returnvalue">Return Value</h4>
-<p class="description">HTTP status</p>
-<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored
-successfully.
-
-</p>
-<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsPutFile">cupsPutFile</a></h3>
-<p class="description">Put a file on the server.</p>
-<p class="code">
-http_status_t cupsPutFile (<br>
- http_t *http,<br>
- const char *resource,<br>
- const char *filename<br>
-);</p>
-<h4 class="parameters">Parameters</h4>
-<dl>
-<dt>http</dt>
-<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
-<dt>resource</dt>
-<dd class="description">Resource name</dd>
-<dt>filename</dt>
-<dd class="description">Filename</dd>
-</dl>
-<h4 class="returnvalue">Return Value</h4>
-<p class="description">HTTP status</p>
-<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored
-successfully.
-
-</p>
-<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3>
<p class="description">Remove a destination from the destination list.</p>
<p class="code">
int cupsRemoveDest (<br>
options for the user.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3>
<p class="description">Remove an option from an option array.</p>
<p class="code">
int cupsRemoveOption (<br>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New number of options</p>
<h3 class="function"><a name="cupsServer">cupsServer</a></h3>
-<p class="description">Return the hostname/address of the default server.</p>
+<p class="description">Return the hostname/address of the current server.</p>
<p class="code">
const char *cupsServer (void);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Server name</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The returned value can be a fully-qualified hostname, a numeric
-IPv4 or IPv6 address, or a domain socket pathname.</p>
-<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
+<p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the
+~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not
+set, the default is the local system - either "localhost" or a domain socket
+path.<br>
+<br>
+The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
+address, or a domain socket pathname.<br>
+<br>
+Note: The current server is tracked separately for each thread in a program.
+Multi-threaded programs that override the server via the
+<a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same
+server to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.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>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
as root and ~/.cups/lpoptions when run as a normal user.</p>
-<h3 class="function"><span class="info"> CUPS 1.1.21 </span><a name="cupsSetDests2">cupsSetDests2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.1.21
/OS X 10.4 </span><a name="cupsSetDests2">cupsSetDests2</a></h3>
<p class="description">Save the list of destinations for the specified server.</p>
<p class="code">
int cupsSetDests2 (<br>
<dt>e</dt>
<dd class="description">New encryption preference</dd>
</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
+environment variable, then the ~/.cups/client.conf file, and finally the
+/etc/cups/client.conf file. If not set, the default is
+<code>HTTP_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">
<dd class="description">Callback function</dd>
</dl>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback.</p>
+<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
+reads the password from the console. Programs should call either this
+function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
+by a program per thread.<br>
+<br>
+Note: The current password callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3>
+<p class="description">Set the advanced password callback for CUPS.</p>
+<p class="code">
+void cupsSetPasswordCB2 (<br>
+ <a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb,<br>
+ void *user_data<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>cb</dt>
+<dd class="description">Callback function</dd>
+<dt>user_data</dt>
+<dd class="description">User data pointer</dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
+reads the password from the console. Programs should call either this
+function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
+by a program per thread.<br>
+<br>
+Note: The current password callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.
+
+</p>
<h3 class="function"><a name="cupsSetServer">cupsSetServer</a></h3>
-<p class="description">Set the default server name.</p>
+<p class="description">Set the default server name and port.</p>
<p class="code">
void cupsSetServer (<br>
const char *server<br>
</dl>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The "server" string can be a fully-qualified hostname, a numeric
-IPv4 or IPv6 address, or a domain socket pathname. Pass <code>NULL</code> to
-restore the default server name.</p>
+IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP
+addresses can be optionally followed by a colon and port number to override
+the default port 631, e.g. "hostname:8631". Pass <code>NULL</code> to restore the
+default server name and port.<br>
+<br>
+Note: The current server is tracked separately for each thread in a program.
+Multi-threaded programs that override the server need to do so in each
+thread for the same server to be used.</p>
+<h3 class="function"><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">
<dd class="description">User name</dd>
</dl>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Pass <code>NULL</code> to restore the default user name.</p>
-<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsStartDocument">cupsStartDocument</a></h3>
+<p class="discussion">Pass <code>NULL</code> to restore the default user name.<br>
+<br>
+Note: The current user name is tracked separately for each thread in a
+program. Multi-threaded programs that override the user name need to do so
+in each thread for the same user name to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.7/OS X 10.9 </span><a name="cupsSetUserAgent">cupsSetUserAgent</a></h3>
+<p class="description">Set the default HTTP User-Agent string.</p>
+<p class="code">
+void cupsSetUserAgent (<br>
+ const char *user_agent<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>user_agent</dt>
+<dd class="description">User-Agent string or <code>NULL</code></dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Setting the string to NULL forces the default value containing the CUPS
+version, IPP version, and operating system version and architecture.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsStartDestDocument">cupsStartDestDocument</a></h3>
+<p class="description">Start a new document.</p>
+<p class="code">
+http_status_t cupsStartDestDocument (<br>
+ http_t *http,<br>
+ <a href="#cups_dest_t">cups_dest_t</a> *dest,<br>
+ <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br>
+ int job_id,<br>
+ const char *docname,<br>
+ const char *format,<br>
+ int num_options,<br>
+ <a href="#cups_option_t">cups_option_t</a> *options,<br>
+ int last_document<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>http</dt>
+<dd class="description">Connection to destination</dd>
+<dt>dest</dt>
+<dd class="description">Destination</dd>
+<dt>info</dt>
+<dd class="description">Destination information</dd>
+<dt>job_id</dt>
+<dd class="description">Job ID</dd>
+<dt>docname</dt>
+<dd class="description">Document name</dd>
+<dt>format</dt>
+<dd class="description">Document format</dd>
+<dt>num_options</dt>
+<dd class="description">Number of document options</dd>
+<dt>options</dt>
+<dd class="description">Document options</dd>
+<dt>last_document</dt>
+<dd class="description">1 if this is the last document</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Status of document creation</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">"job_id" is the job ID returned by cupsCreateDestJob. "docname" is the name
+of the document/file being printed, "format" is the MIME media type for the
+document (see CUPS_FORMAT_xxx constants), and "num_options" and "options"
+are the options do be applied to the document. "last_document" should be 1
+if this is the last document to be submitted in the job. Returns
+<code>HTTP_CONTINUE</code> on success.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsStartDocument">cupsStartDocument</a></h3>
<p class="description">Add a document to a job created with cupsCreateJob().</p>
<p class="code">
http_status_t cupsStartDocument (<br>
<p class="description">Filename or <code>NULL</code> on error</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The temporary filename is returned in the filename buffer.
-This function is deprecated - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or
-<a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead.
+This function is deprecated and will no longer generate a temporary
+
filename - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or <a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsTempFile2">cupsTempFile2</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2
/OS X 10.5 </span><a name="cupsTempFile2">cupsTempFile2</a></h3>
<p class="description">Creates a temporary CUPS file.</p>
<p class="code">
cups_file_t *cupsTempFile2 (<br>
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">
<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 *);
+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;
</p>
+<h3 class="typedef"><span class="info"> CUPS 1.5/OS X 10.7 </span><a name="cups_server_cert_cb_t">cups_server_cert_cb_t</a></h3>
+<p class="description">Server credentials callback
+</p>
+<p class="code">
+typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *certs, void *user_data);
+</p>
+<h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_size_t">cups_size_t</a></h3>
+<p class="description">Media Size </p>
+<p class="code">
+typedef struct <a href="#cups_size_s">cups_size_s</a> cups_size_t;
+</p>
+<h3 class="typedef"><a name="pwg_map_t">pwg_map_t</a></h3>
+<p class="description">Map element - PPD to/from PWG</p>
+<p class="code">
+typedef struct <a href="#pwg_map_s">pwg_map_s</a> pwg_map_t;
+</p>
+<h3 class="typedef"><a name="pwg_media_t">pwg_media_t</a></h3>
+<p class="description">Common media size data</p>
+<p class="code">
+typedef struct <a href="#pwg_media_s">pwg_media_s</a> pwg_media_t;
+</p>
+<h3 class="typedef"><a name="pwg_size_t">pwg_size_t</a></h3>
+<p class="description">Size element - PPD to/from PWG</p>
+<p class="code">
+typedef struct <a href="#pwg_size_s">pwg_size_s</a> pwg_size_t;
+</p>
<h2 class="title"><a name="STRUCTURES">Structures</a></h2>
<h3 class="struct"><a name="cups_dest_s">cups_dest_s</a></h3>
<p class="description">Destination</p>
<dt>value </dt>
<dd class="description">Value of option</dd>
</dl>
+<h3 class="struct"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_size_s">cups_size_s</a></h3>
+<p class="description">Media Size </p>
+<p class="code">struct cups_size_s {<br>
+ char media[128];<br>
+ int width, length, bottom, left, right, top;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>media[128] </dt>
+<dd class="description">Media name to use</dd>
+<dt>top </dt>
+<dd class="description">Top margin in hundredths of
+millimeters</dd>
+</dl>
+<h3 class="struct"><a name="pollfd">pollfd</a></h3>
+<p class="description">User data (unused)</p>
+<p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br>
+ _cups_dnssd_data_t *data;<br>
+ else if(val 0) data - got_data;<br>
+ void) timeout;<br>
+ int val;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>data </dt>
+<dd class="description">Enumeration data</dd>
+<dt>got_data </dt>
+<dt>timeout </dt>
+<dt>val </dt>
+<dd class="description">Return value</dd>
+</dl>
+<h3 class="struct"><a name="pwg_map_s">pwg_map_s</a></h3>
+<p class="description">Map element - PPD to/from PWG</p>
+<p class="code">struct pwg_map_s {<br>
+ char *pwg, *ppd;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>ppd </dt>
+<dd class="description">PPD option keyword</dd>
+</dl>
+<h3 class="struct"><a name="pwg_media_s">pwg_media_s</a></h3>
+<p class="description">Common media size data</p>
+<p class="code">struct pwg_media_s {<br>
+ int width, length;<br>
+ const char *pwg, *legacy, *ppd;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>length </dt>
+<dd class="description">Length in 2540ths</dd>
+<dt>ppd </dt>
+<dd class="description">Standard Adobe PPD name</dd>
+</dl>
+<h3 class="struct"><a name="pwg_size_s">pwg_size_s</a></h3>
+<p class="description">Size element - PPD to/from PWG</p>
+<p class="code">struct pwg_size_s {<br>
+ <a href="#pwg_map_t">pwg_map_t</a> map;<br>
+ int width, length, left, bottom, right, top;<br>
+};</p>
+<h4 class="members">Members</h4>
+<dl>
+<dt>map </dt>
+<dd class="description">Map element</dd>
+<dt>top </dt>
+<dd class="description">Top margin in 2540ths</dd>
+</dl>
+<h2 class="title"><a name="VARIABLES">Variables</a></h2>
+<h3 class="variable"><a name="CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></h3>
+<p class="description">Get the Apple language identifier associated with a
+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>
+<p class="description">Printer type/capability bit
+constants</p>
<h4 class="constants">Constants</h4>
<dl>
-<dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2 </span></dt>
-<dd class="description">Printer requires authentication </dd>
+<dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/OS X 10.5 </span></dt>
+<dd class="description">Printer requires authentication
+</dd>
<dt>CUPS_PRINTER_BIND </dt>
<dd class="description">Can bind output</dd>
<dt>CUPS_PRINTER_BW </dt>
<dd class="description">Can collage copies</dd>
<dt>CUPS_PRINTER_COLOR </dt>
<dd class="description">Can do color printing</dd>
-<dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2 </span></dt>
-<dd class="description">Printer supports maintenance commands </dd>
+<dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/OS X 10.5 </span></dt>
+<dd class="description">Printer supports maintenance commands
+</dd>
<dt>CUPS_PRINTER_COPIES </dt>
<dd class="description">Can do copies</dd>
<dt>CUPS_PRINTER_COVER </dt>
<dd class="description">Can cover output</dd>
<dt>CUPS_PRINTER_DEFAULT </dt>
<dd class="description">Default printer on network</dd>
-<dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2 </span></dt>
-<dd class="description">Delete printer </dd>
-<dt>CUPS_PRINTER_DISCOVERED <span class="info"> CUPS 1.3 </span></dt>
-<dd class="description">Printer was automatically discovered and added </dd>
+<dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2/OS X 10.5 </span></dt>
+<dd class="description">Delete printer
+</dd>
<dt>CUPS_PRINTER_DUPLEX </dt>
<dd class="description">Can do duplexing</dd>
<dt>CUPS_PRINTER_FAX </dt>
<dd class="description">Fax queue</dd>
-<dt>CUPS_PRINTER_IMPLICIT </dt>
-<dd class="description">Implicit class</dd>
<dt>CUPS_PRINTER_LARGE </dt>
<dd class="description">Can do D/E/A1/A0</dd>
<dt>CUPS_PRINTER_LOCAL </dt>
<dd class="description">Local printer or class</dd>
<dt>CUPS_PRINTER_MEDIUM </dt>
<dd class="description">Can do Tabloid/B/C/A3/A2</dd>
-<dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2 </span></dt>
-<dd class="description">Printer is not shared </dd>
+<dt>CUPS_PRINTER_MFP <span class="info"> CUPS 1.4/OS X 10.6 </span></dt>
+<dd class="description">Printer with scanning capabilities
+</dd>
+<dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2/OS X 10.5 </span></dt>
+<dd class="description">Printer is not shared
+</dd>
<dt>CUPS_PRINTER_PUNCH </dt>
<dd class="description">Can punch output</dd>
<dt>CUPS_PRINTER_REJECTING </dt>
<dd class="description">Printer is rejecting jobs</dd>
<dt>CUPS_PRINTER_REMOTE </dt>
<dd class="description">Remote printer or class</dd>
+<dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/OS X 10.6 </span></dt>
+<dd class="description">Scanner-only device
+</dd>
<dt>CUPS_PRINTER_SMALL </dt>
<dd class="description">Can do Letter/Legal/A4</dd>
<dt>CUPS_PRINTER_SORT </dt>
projects / thirdparty / cups.git / blobdiff