diff options
Diffstat (limited to 'doc/help/api-cups.html')
| -rw-r--r-- | doc/help/api-cups.html | 2521 |
1 files changed, 2521 insertions, 0 deletions
diff --git a/doc/help/api-cups.html b/doc/help/api-cups.html new file mode 100644 index 0000000..2dd4083 --- /dev/null +++ b/doc/help/api-cups.html @@ -0,0 +1,2521 @@ +<!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 http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> +<style type="text/css"><!-- +BODY { + font-family: lucida grande, geneva, helvetica, arial, sans-serif; +} + +H1, H2, H3, H4, H5, H6, P, TD, TH { + font-family: lucida grande, geneva, helvetica, arial, sans-serif; +} + +KBD { + font-family: monaco, courier, monospace; + font-weight: bold; +} + +PRE { + font-family: monaco, courier, monospace; +} + +PRE.command { + border: dotted thin #7f7f7f; + margin-left: 36pt; + padding: 10px; +} + +P.compact { + margin: 0; +} + +P.example { + font-style: italic; + margin-left: 36pt; +} + +PRE.example { + background: #eeeeee; + border: dotted thin #999999; + margin-left: 36pt; + padding: 10pt; +} + +PRE.command EM, PRE.example EM { + font-family: lucida grande, geneva, helvetica, arial, sans-serif; +} + +P.command { + font-family: monaco, courier, monospace; + margin-left: 36pt; +} + +P.formula { + font-style: italic; + margin-left: 36pt; +} + +BLOCKQUOTE { + background: #eeeeee; + border: solid thin #999999; + padding: 10pt; +} + +A IMG { + border: none; +} + +A:link:hover IMG { + background: #f0f0f0; + border-radius: 10px; + -moz-border-radius: 10px; +} + +A:link, A:visited { + font-weight: normal; + text-decoration: none; +} + +A:link:hover, A:visited:hover, A:active { + text-decoration: underline; +} + +SUB, SUP { + font-size: 50%; +} + +TR.data, TD.data, TR.data TD { + margin-top: 10pt; + padding: 5pt; + border-bottom: solid 1pt #999999; +} + +TR.data TH { + border-bottom: solid 1pt #999999; + padding-top: 10pt; + padding-left: 5pt; + text-align: left; +} + +DIV.table TABLE { + border: solid thin #999999; + border-collapse: collapse; + border-spacing: 0; + margin-left: auto; + margin-right: auto; +} + +DIV.table CAPTION { + caption-side: top; + font-size: 120%; + font-style: italic; + font-weight: bold; + margin-left: auto; + margin-right: auto; +} + +DIV.table TABLE TD { + border: solid thin #cccccc; + padding-top: 5pt; +} + +DIV.table TABLE TH { + background: #cccccc; + border: none; + border-bottom: solid thin #999999; +} + +DIV.figure TABLE { + margin-left: auto; + margin-right: auto; +} + +DIV.figure CAPTION { + caption-side: bottom; + font-size: 120%; + font-style: italic; + font-weight: bold; + margin-left: auto; + margin-right: auto; +} + +TH.label { + text-align: right; + vertical-align: top; +} + +TH.sublabel { + text-align: right; + font-weight: normal; +} + +HR { + border: solid thin; +} + +SPAN.info { + background: black; + border: thin solid black; + color: white; + font-size: 80%; + font-style: italic; + font-weight: bold; + white-space: nowrap; +} + +H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { + float: right; + font-size: 100%; +} + +H1.title { +} + +H2.title, H3.title { + border-bottom: solid 2pt #000000; +} + +DIV.indent, TABLE.indent { + margin-top: 2em; + margin-left: auto; + margin-right: auto; + width: 90%; +} + +TABLE.indent { + border-collapse: collapse; +} + +TABLE.indent TD, TABLE.indent TH { + padding: 0; +} + +TABLE.list { + border-collapse: collapse; + margin-left: auto; + margin-right: auto; + width: 90%; +} + +TABLE.list TH { + background: white; + border-bottom: solid thin #cccccc; + color: #444444; + padding-top: 10pt; + padding-left: 5pt; + text-align: left; + vertical-align: bottom; + white-space: nowrap; +} + +TABLE.list TH A { + color: #4444cc; +} + +TABLE.list TD { + border-bottom: solid thin #eeeeee; + padding-top: 5pt; + padding-left: 5pt; +} + +TABLE.list TR:nth-child(even) { + background: #f8f8f8; +} + +TABLE.list TR:nth-child(odd) { + background: #f4f4f4; +} + +DT { + margin-left: 36pt; + margin-top: 12pt; +} + +DD { + margin-left: 54pt; +} + +DL.category DT { + font-weight: bold; +} + +P.summary { + margin-left: 36pt; + font-family: monaco, courier, monospace; +} + +DIV.summary TABLE { + border: solid thin #999999; + border-collapse: collapse; + border-spacing: 0; + margin: 10px; +} + +DIV.summary TABLE TD, DIV.summary TABLE TH { + border: solid thin #999999; + padding: 5px; + text-align: left; + vertical-align: top; +} + +DIV.summary TABLE THEAD TH { + background: #eeeeee; +} + +/* API documentation styles... */ +div.body h1 { + margin: 0; +} +div.body h2 { + margin-top: 1.5em; +} +div.body h3, div.body h4, div.body h5 { + margin-bottom: 0.5em; + margin-top: 1.5em; +} +.class, .enumeration, .function, .struct, .typedef, .union { + border-bottom: solid thin #999999; + margin-bottom: 0; + margin-top: 2em; +} +.description { + margin-top: 0.5em; +} +code, p.code, pre, ul.code li { + font-family: monaco, courier, monospace; + font-size: 90%; +} +ul.code, ul.contents, ul.subcontents { + list-style-type: none; + margin: 0; + padding-left: 0; +} +ul.code li { + margin: 0; +} +ul.contents > li { + margin-top: 1em; +} +ul.contents li ul.code, ul.contents li ul.subcontents { + padding-left: 2em; +} +div.body dl { + margin-left: 0; + margin-top: 0; +} +div.body dt { + font-style: italic; + margin-left: 0; + margin-top: 0; +} +div.body dd { + margin-bottom: 0.5em; +} + +/* This is just for the HTML files generated with the framedhelp target */ +div.contents { + background: #e8e8e8; + border: solid thin black; + padding: 10px; +} +div.contents h1 { + font-size: 110%; +} +div.contents h2 { + font-size: 100%; +} +div.contents ul.contents { + font-size: 80%; +} +div.contents ul.subcontents li { + margin-left: 1em; + text-indent: -1em; +} +--></style> +</head> +<body> +<div class='body'> +<!-- + "$Id: api-cups.html 9772 2011-05-12 05:46:30Z mike $" + + CUPS API header for CUPS. + + Copyright 2008-2011 by Apple Inc. + + These coded instructions, statements, and computer programs are the + property of Apple Inc. and are protected by Federal copyright + law. Distribution and use rights are outlined in the file "LICENSE.txt" + which should have been included with this file. If this file is + file is missing or damaged, see the license at "http://www.cups.org/". +--> + +<h1 class='title'>CUPS API</h1> + +<div class='summary'><table summary='General Information'> +<thead> +<tr> + <th>Header</th> + <th>cups/cups.h</th> +</tr> +</thead> +<tbody> +<tr> + <th>Library</th> + <td>-lcups</td> +</tr> +<tr> + <th>See Also</th> + <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br> + Programming: <a href='api-array.html' target='_top'>Array API</a><br> + Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br> + Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br> + Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br> + Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br> + Programming: <a href='api-raster.html' target='_top'>Raster API</a></td> +</tr> +</tbody> +</table></div> +<h2 class="title">Contents</h2> +<ul class="contents"> +<li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> + <li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li> + <li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li> + <li><a href="#OPTIONS">Options</a></li> + <li><a href="#PRINT_JOBS">Print Jobs</a></li> + <li><a href="#ERROR_HANDLING">Error Handling</a></li> + <li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li> +</ul></li> +<li><a href="#FUNCTIONS">Functions</a><ul class="code"> + <li><a href="#appleGetPaperSize" title="Get the default paper size.">appleGetPaperSize</a></li> + <li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li> + <li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li> + <li><a href="#cupsAdminCreateWindowsPPD" title="Create the Windows PPD file for a printer.">cupsAdminCreateWindowsPPD</a></li> + <li><a href="#cupsAdminExportSamba" title="Export a printer to Samba.">cupsAdminExportSamba</a></li> + <li><a href="#cupsAdminGetServerSettings" title="Get settings from the server.">cupsAdminGetServerSettings</a></li> + <li><a href="#cupsAdminSetServerSettings" title="Set settings on the server.">cupsAdminSetServerSettings</a></li> + <li><a href="#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 current encryption settings.">cupsEncryption</a></li> + <li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li> + <li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li> + <li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li> + <li><a href="#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="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</a></li> + <li><a href="#cupsGetJobs2" title="Get the jobs from the specified server.">cupsGetJobs2</a></li> + <li><a href="#cupsGetNamedDest" title="Get options for the named destination.">cupsGetNamedDest</a></li> + <li><a href="#cupsGetOption" title="Get an option value.">cupsGetOption</a></li> + <li><a href="#cupsGetPPD" title="Get the PPD file for a printer on the default server.">cupsGetPPD</a></li> + <li><a href="#cupsGetPPD2" title="Get the PPD file for a printer from the specified server.">cupsGetPPD2</a></li> + <li><a href="#cupsGetPPD3" title="Get the PPD file for a printer on the specified +server if it has changed.">cupsGetPPD3</a></li> + <li><a href="#cupsGetPassword" title="Get a password from the user.">cupsGetPassword</a></li> + <li><a href="#cupsGetPassword2" title="Get a password from the user using the advanced +password callback.">cupsGetPassword2</a></li> + <li><a href="#cupsGetPrinters" title="Get a list of printers from the default server.">cupsGetPrinters</a></li> + <li><a href="#cupsGetServerPPD" title="Get an available PPD file from the server.">cupsGetServerPPD</a></li> + <li><a href="#cupsLangDefault" title="Return the default language.">cupsLangDefault</a></li> + <li><a href="#cupsLangEncoding" title="Return the character encoding (us-ascii, etc.) +for the given language.">cupsLangEncoding</a></li> + <li><a href="#cupsLangFlush" title="Flush all language data out of the cache.">cupsLangFlush</a></li> + <li><a href="#cupsLangFree" title="Free language data.">cupsLangFree</a></li> + <li><a href="#cupsLangGet" title="Get a language.">cupsLangGet</a></li> + <li><a href="#cupsNotifySubject" title="Return the subject for the given notification message.">cupsNotifySubject</a></li> + <li><a href="#cupsNotifyText" title="Return the text for the given notification message.">cupsNotifyText</a></li> + <li><a href="#cupsParseOptions" title="Parse options from a command-line argument.">cupsParseOptions</a></li> + <li><a href="#cupsPrintFile" title="Print a file to a printer or class on the default server.">cupsPrintFile</a></li> + <li><a href="#cupsPrintFile2" title="Print a file to a printer or class on the specified +server.">cupsPrintFile2</a></li> + <li><a href="#cupsPrintFiles" title="Print one or more files to a printer or class on the +default server.">cupsPrintFiles</a></li> + <li><a href="#cupsPrintFiles2" title="Print one or more files to a printer or class on the +specified server.">cupsPrintFiles2</a></li> + <li><a href="#cupsRemoveDest" title="Remove a destination from the destination list.">cupsRemoveDest</a></li> + <li><a href="#cupsRemoveOption" title="Remove an option from an option array.">cupsRemoveOption</a></li> + <li><a href="#cupsServer" title="Return the hostname/address of the current server.">cupsServer</a></li> + <li><a href="#cupsSetClientCertCB" title="Set the client certificate callback.">cupsSetClientCertCB</a></li> + <li><a href="#cupsSetCredentials" title="Set the default credentials to be used for SSL/TLS +connections.">cupsSetCredentials</a></li> + <li><a href="#cupsSetDefaultDest" title="Set the default destination.">cupsSetDefaultDest</a></li> + <li><a href="#cupsSetDests" title="Save the list of destinations for the default server.">cupsSetDests</a></li> + <li><a href="#cupsSetDests2" title="Save the list of destinations for the specified server.">cupsSetDests2</a></li> + <li><a href="#cupsSetEncryption" title="Set the encryption preference.">cupsSetEncryption</a></li> + <li><a href="#cupsSetPasswordCB" title="Set the password callback for CUPS.">cupsSetPasswordCB</a></li> + <li><a href="#cupsSetPasswordCB2" title="Set the advanced password callback for CUPS.">cupsSetPasswordCB2</a></li> + <li><a href="#cupsSetServer" title="Set the default server name and port.">cupsSetServer</a></li> + <li><a href="#cupsSetServerCertCB" title="Set the server certificate callback.">cupsSetServerCertCB</a></li> + <li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li> + <li><a href="#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> +<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_t" title="Destination">cups_dest_t</a></li> + <li><a href="#cups_device_cb_t" title="Device callback ">cups_device_cb_t</a></li> + <li><a href="#cups_job_t" title="Job">cups_job_t</a></li> + <li><a href="#cups_option_t" title="Printer Options">cups_option_t</a></li> + <li><a href="#cups_password_cb2_t" title="New password callback ">cups_password_cb2_t</a></li> + <li><a href="#cups_password_cb_t" title="Password callback">cups_password_cb_t</a></li> + <li><a href="#cups_ptype_t" title="Printer type/capability bits">cups_ptype_t</a></li> + <li><a href="#cups_server_cert_cb_t" title="Server credentials callback ">cups_server_cert_cb_t</a></li> +</ul></li> +<li><a href="#STRUCTURES">Structures</a><ul class="code"> + <li><a href="#cups_dest_s" title="Destination">cups_dest_s</a></li> + <li><a href="#cups_job_s" title="Job">cups_job_s</a></li> + <li><a href="#cups_option_s" title="Printer Options">cups_option_s</a></li> +</ul></li> +<li><a href="#VARIABLES">Variables</a><ul class="code"> + <li><a href="#CF_RETURNS_RETAINED" title="Get the Apple language identifier associated with a +locale ID.">CF_RETURNS_RETAINED</a></li> +</ul></li> +<li><a href="#ENUMERATIONS">Constants</a><ul class="code"> + <li><a href="#cups_ptype_e" title="Printer type/capability bit constants">cups_ptype_e</a></li> +</ul></li> +</ul> +<!-- + "$Id: api-cups.html 9772 2011-05-12 05:46:30Z mike $" + + API introduction for CUPS. + + Copyright 2007-2011 by Apple Inc. + Copyright 1997-2006 by Easy Software Products, all rights reserved. + + These coded instructions, statements, and computer programs are the + property of Apple Inc. and are protected by Federal copyright + law. Distribution and use rights are outlined in the file "LICENSE.txt" + which should have been included with this file. If this file is + file is missing or damaged, see the license at "http://www.cups.org/". +--> + +<h2 class='title'><a name='OVERVIEW'>Overview</a></h2> + +<p>The CUPS API provides the convenience functions needed to support +applications, filters, printer drivers, and backends that need to interface +with the CUPS scheduler.</p> + +<h3><a name='CLIENTS_AND_SERVERS'>Clients and Servers</a></h3> + +<p>CUPS is based on the Internet Printing Protocol ("IPP"), which allows +clients (applications) to communicate with a server (the scheduler) to get a +list of printers, send print jobs, and so forth. You identify which server +you want to communicate with using a pointer to the opaque structure +<code>http_t</code>. All of the examples in this document use the +<code>CUPS_HTTP_DEFAULT</code> constant, referring to the default connection +to the scheduler. The <a href='api-httpipp.html' target='_top'>HTTP and IPP +APIs</a> document provides more information on server connections.</p> + +<h3><a name='PRINTERS_AND_CLASSES'>Printers and Classes</a></h3> + +<p>Printers and classes (collections of printers) are accessed through +the <a href="#cups_dest_t"><code>cups_dest_t</code></a> structure which +includes the name (<code>name</code>), instance (<code>instance</code> - +a way of selecting certain saved options/settings), and the options and +attributes associated with that destination (<code>num_options</code> and +<code>options</code>). Destinations are created using the +<a href="#cupsGetDests"><code>cupsGetDests</code></a> function and freed +using the <a href='#cupsFreeDests'><code>cupsFreeDests</code></a> function. +The <a href='#cupsGetDest'><code>cupsGetDest</code></a> function finds a +specific destination for printing:</p> + +<pre class='example'> +#include <cups/cups.h> + +<a href='#cups_dest_t'>cups_dest_t</a> *dests; +int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests); +<a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests); + +/* do something with dest */ + +<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests); +</pre> + +<p>Passing <code>NULL</code> to +<a href='#cupsGetDest'><code>cupsGetDest</code></a> for the destination name +will return the default destination. Similarly, passing a <code>NULL</code> +instance will return the default instance for that destination.</p> + +<div class='table'><table summary='Table 1: Printer Attributes' width='80%'> +<caption>Table 1: <a name='TABLE1'>Printer Attributes</a></caption> +<thead> +<tr> + <th>Attribute Name</th> + <th>Description</th> +</tr> +</thead> +<tbody> +<tr> + <td>"auth-info-required"</td> + <td>The type of authentication required for printing to this + destination: "none", "username,password", "domain,username,password", + or "negotiate" (Kerberos)</td> +</tr> +<tr> + <td>"printer-info"</td> + <td>The human-readable description of the destination such as "My + Laser Printer".</td> +</tr> +<tr> + <td>"printer-is-accepting-jobs"</td> + <td>"true" if the destination is accepting new jobs, "false" if + not.</td> +</tr> +<tr> + <td>"printer-is-shared"</td> + <td>"true" if the destination is being shared with other computers, + "false" if not.</td> +</tr> +<tr> + <td>"printer-location"</td> + <td>The human-readable location of the destination such as "Lab 4".</td> +</tr> +<tr> + <td>"printer-make-and-model"</td> + <td>The human-readable make and model of the destination such as "HP + LaserJet 4000 Series".</td> +</tr> +<tr> + <td>"printer-state"</td> + <td>"3" if the destination is idle, "4" if the destination is printing + a job, and "5" if the destination is stopped.</td> +</tr> +<tr> + <td>"printer-state-change-time"</td> + <td>The UNIX time when the destination entered the current state.</td> +</tr> +<tr> + <td>"printer-state-reasons"</td> + <td>Additional comma-delimited state keywords for the destination + such as "media-tray-empty-error" and "toner-low-warning".</td> +</tr> +<tr> + <td>"printer-type"</td> + <td>The <a href='#cups_printer_t'><code>cups_printer_t</code></a> + value associated with the destination.</td> +</tr> +</tbody> +</table></div> + +<h3><a name='OPTIONS'>Options</a></h3> + +<p>Options are stored in arrays of +<a href='#cups_option_t'><code>cups_option_t</code></a> structures. Each +option has a name (<code>name</code>) and value (<code>value</code>) +associated with it. The <a href='#cups_dest_t'><code>cups_dest_t</code></a> +<code>num_options</code> and <code>options</code> members contain the +default options for a particular destination, along with several informational +attributes about the destination as shown in <a href='#TABLE1'>Table 1</a>. +The <a href='#cupsGetOption'><code>cupsGetOption</code></a> function gets +the value for the named option. For example, the following code lists the +available destinations and their human-readable descriptions:</p> + +<pre class='example'> +#include <cups/cups.h> + +<a href='#cups_dest_t'>cups_dest_t</a> *dests; +int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests); +<a href='#cups_dest_t'>cups_dest_t</a> *dest; +int i; +const char *value; + +for (i = num_dests, dest = dests; i > 0; i --, dest ++) + if (dest->instance == NULL) + { + value = <a href='#cupsGetOption'>cupsGetOption</a>("printer-info", dest->num_options, dest->options); + printf("%s (%s)\n", dest->name, value ? value : "no description"); + } + +<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests); +</pre> + +<p>You can create your own option arrays using the +<a href='#cupsAddOption'><code>cupsAddOption</code></a> function, which +adds a single named option to an array:</p> + +<pre class='example'> +#include <cups/cups.h> + +int num_options = 0; +<a href='#cups_option_t'>cups_option_t</a> *options = NULL; + +/* The returned num_options value is updated as needed */ +num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "value", num_options, &options); + +/* This adds a second option value */ +num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &options); + +/* This replaces the first option we added */ +num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &options); +</pre> + +<p>Use a <code>for</code> loop to copy the options from a destination:</p> + +<pre class='example'> +#include <cups/cups.h> + +int i; +int num_options = 0; +<a href='#cups_option_t'>cups_option_t</a> *options = NULL; +<a href='#cups_dest_t'>cups_dest_t</a> *dest; + +for (i = 0; i < dest->num_options; i ++) + num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value, + num_options, &options); +</pre> + +<p>Use the <a href='#cupsFreeOptions'><code>cupsFreeOptions</code></a> +function to free the options array when you are done using it:</p> + +<pre class='example'> +<a href='#cupsFreeOptions'>cupsFreeOptions</a>(num_options, options); +</pre> + +<h3><a name='PRINT_JOBS'>Print Jobs</a></h3> + +<p>Print jobs are identified by a locally-unique job ID number from 1 to +2<sup>31</sup>-1 and have options and one or more files for printing to a +single destination. The <a href='#cupsPrintFile'><code>cupsPrintFile</code></a> +function creates a new job with one file. The following code prints the CUPS +test page file:</p> + +<pre class='example'> +#include <cups/cups.h> + +<a href='#cups_dest_t'>cups_dest_t</a> *dest; +int num_options; +<a href='#cups_option_t'>cups_option_t</a> *options; +int job_id; + +/* Print a single file */ +job_id = <a href='#cupsPrintFile'>cupsPrintFile</a>(dest->name, "/usr/share/cups/data/testprint.ps", + "Test Print", num_options, options); +</pre> + +<p>The <a href='#cupsPrintFiles'><code>cupsPrintFiles</code></a> function +creates a job with multiple files. The files are provided in a +<code>char *</code> array:</p> + +<pre class='example'> +#include <cups/cups.h> + +<a href='#cups_dest_t'>cups_dest_t</a> *dest; +int num_options; +<a href='#cups_option_t'>cups_option_t</a> *options; +int job_id; +char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" }; + +/* Print three files */ +job_id = <a href='#cupsPrintFiles'>cupsPrintFiles</a>(dest->name, 3, files, "Test Print", num_options, options); +</pre> + +<p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a> +function creates a new job with no files in it. Files are added using the +<a href='#cupsStartDocument'><code>cupsStartDocument</code></a>, +<a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>, +and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions. +The following example creates a job with 10 text files for printing:</p> + +<pre class='example'> +#include <cups/cups.h> + +<a href='#cups_dest_t'>cups_dest_t</a> *dest; +int num_options; +<a href='#cups_option_t'>cups_option_t</a> *options; +int job_id; +int i; +char buffer[1024]; + +/* Create the job */ +job_id = <a href='#cupsCreateJob'>cupsCreateJob</a>(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files", + num_options, options); + +/* If the job is created, add 10 files */ +if (job_id > 0) +{ + for (i = 1; i <= 10; i ++) + { + snprintf(buffer, sizeof(buffer), "file%d.txt", i); + + <a href='#cupsStartDocument'>cupsStartDocument</a>(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer, + CUPS_FORMAT_TEXT, i == 10); + + snprintf(buffer, sizeof(buffer), + "File %d\n" + "\n" + "One fish,\n" + "Two fish,\n + "Red fish,\n + "Blue fish\n", i); + + /* cupsWriteRequestData can be called as many times as needed */ + <a href='#cupsWriteRequestData'>cupsWriteRequestData</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer)); + + <a href='#cupsFinishDocument'>cupsFinishDocument</a>(CUPS_HTTP_DEFAULT, dest->name); + } +} +</pre> + +<p>Once you have created a job, you can monitor its status using the +<a href='#cupsGetJobs'><code>cupsGetJobs</code></a> function, which returns +an array of <a href='#cups_job_t'><code>cups_job_t</code></a> structures. +Each contains the job ID (<code>id</code>), destination name +(<code>dest</code>), title (<code>title</code>), and other information +associated with the job. The job array is freed using the +<a href='#cupsFreeJobs'><code>cupsFreeJobs</code></a> function. The following +example monitors a specific job ID, showing the current job state once every +5 seconds until the job is completed:</p> + +<pre class='example'> +#include <cups/cups.h> + +<a href='#cups_dest_t'>cups_dest_t</a> *dest; +int job_id; +int num_jobs; +<a href='#cups_job_t'>cups_job_t</a> *jobs; +int i; +ipp_jstate_t job_state = IPP_JOB_PENDING; + +while (job_state < IPP_JOB_STOPPED) +{ + /* Get my jobs (1) with any state (-1) */ + num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&jobs, dest->name, 1, -1); + + /* Loop to find my job */ + job_state = IPP_JOB_COMPLETED; + + for (i = 0; i < num_jobs; i ++) + if (jobs[i].id == job_id) + { + job_state = jobs[i].state; + break; + } + + /* Free the job array */ + <a href='#cupsFreeJobs'>cupsFreeJobs</a>(num_jobs, jobs); + + /* Show the current state */ + switch (job_state) + { + case IPP_JOB_PENDING : + printf("Job %d is pending.\n", job_id); + break; + case IPP_JOB_HELD : + printf("Job %d is held.\n", job_id); + break; + case IPP_JOB_PROCESSING : + printf("Job %d is processing.\n", job_id); + break; + case IPP_JOB_STOPPED : + printf("Job %d is stopped.\n", job_id); + break; + case IPP_JOB_CANCELED : + printf("Job %d is canceled.\n", job_id); + break; + case IPP_JOB_ABORTED : + printf("Job %d is aborted.\n", job_id); + break; + case IPP_JOB_COMPLETED : + printf("Job %d is completed.\n", job_id); + break; + } + + /* Sleep if the job is not finished */ + if (job_state < IPP_JOB_STOPPED) + sleep(5); +} +</pre> + +<p>To cancel a job, use the +<a href='#cupsCancelJob'><code>cupsCancelJob</code></a> function with the +job ID:</p> + +<pre class='example'> +#include <cups/cups.h> + +<a href='#cups_dest_t'>cups_dest_t</a> *dest; +int job_id; + +<a href='#cupsCancelJob'>cupsCancelJob</a>(dest->name, job_id); +</pre> + +<h3><a name='ERROR_HANDLING'>Error Handling</a></h3> + +<p>If any of the CUPS API printing functions returns an error, the reason for +that error can be found by calling the +<a href='#cupsLastError'><code>cupsLastError</code></a> and +<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> functions. +<a href='#cupsLastError'><code>cupsLastError</code></a> returns the last IPP +error code +(<a href='api-httpipp.html#ipp_status_t'><code>ipp_status_t</code></a>) +that was encountered, while +<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> returns +a (localized) human-readable string that can be shown to the user. For example, +if any of the job creation functions returns a job ID of 0, you can use +<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> to show +the reason why the job could not be created:</p> + +<pre class='example'> +#include <cups/cups.h> + +int job_id; + +if (job_id == 0) + puts(cupsLastErrorString()); +</pre> + +<h3><a name='PASSWORDS_AND_AUTHENTICATION'>Passwords and Authentication</a></h3> + +<p>CUPS supports authentication of any request, including submission of print +jobs. The default mechanism for getting the username and password is to use the +login user and a password from the console.</p> + +<p>To support other types of applications, in particular Graphical User +Interfaces ("GUIs"), the CUPS API provides functions to set the default +username and to register a callback function that returns a password string.</p> + +<p>The <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> +function is used to set a password callback in your program. Only one +function can be used at any time.</p> + +<p>The <a href="#cupsSetUser"><code>cupsSetUser</code></a> function sets the +current username for authentication. This function can be called by your +password callback function to change the current username as needed.</p> + +<p>The following example shows a simple password callback that gets a +username and password from the user:</p> + +<pre class='example'> +#include <cups/cups.h> + +const char * +my_password_cb(const char *prompt) +{ + char user[65]; + + + puts(prompt); + + /* Get a username from the user */ + printf("Username: "); + if (fgets(user, sizeof(user), stdin) == NULL) + return (NULL); + + /* Strip the newline from the string and set the user */ + user[strlen(user) - 1] = '\0'; + + <a href='#cupsSetUser'>cupsSetUser</a>(user); + + /* Use getpass() to ask for the password... */ + return (getpass("Password: ")); +} + +<a href='#cupsSetPasswordCB'>cupsSetPasswordCB</a>(my_password_cb); +</pre> + +<p>Similarly, a GUI could display the prompt string in a window with input +fields for the username and password. The username should default to the +string returned by the <a href="#cupsUser"><code>cupsUser</code></a> +function.</p> +<h2 class="title"><a name="FUNCTIONS">Functions</a></h2> +<h3 class="function"><a name="appleGetPaperSize">appleGetPaperSize</a></h3> +<p class="description">Get the default paper size.</p> +<p class="code"> +char *appleGetPaperSize (<br> + char *name,<br> + int namesize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Paper size name buffer</dd> +<dt>namesize</dt> +<dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Default paper size</p> +<h3 class="function"><a name="cupsAddDest">cupsAddDest</a></h3> +<p class="description">Add a destination to the list of destinations.</p> +<p class="code"> +int cupsAddDest (<br> + const char *name,<br> + const char *instance,<br> + int num_dests,<br> + <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Destination name</dd> +<dt>instance</dt> +<dd class="description">Instance name or <code>NULL</code> for none/primary</dd> +<dt>num_dests</dt> +<dd class="description">Number of destinations</dd> +<dt>dests</dt> +<dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">New number of destinations</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function cannot be used to add a new class or printer queue, +it only adds a new container of saved options for the named +destination or instance.<br> +<br> +If the named destination already exists, the destination list is +returned unchanged. Adding a new instance of a destination creates +a copy of that destination's options.<br> +<br> +Use the <a href="#cupsSaveDests"><code>cupsSaveDests</code></a> function to save the updated list of +destinations to the user's lpoptions file.</p> +<h3 class="function"><a name="cupsAddOption">cupsAddOption</a></h3> +<p class="description">Add an option to an option array.</p> +<p class="code"> +int cupsAddOption (<br> + const char *name,<br> + const char *value,<br> + int num_options,<br> + <a href="#cups_option_t">cups_option_t</a> **options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Name of option</dd> +<dt>value</dt> +<dd class="description">Value of option</dd> +<dt>num_options</dt> +<dd class="description">Number of options</dd> +<dt>options</dt> +<dd class="description">Pointer to options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of options</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">New option arrays can be initialized simply by passing 0 for the +"num_options" parameter.</p> +<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3> +<p class="description">Create the Windows PPD file for a printer.</p> +<p class="code"> +char *cupsAdminCreateWindowsPPD (<br> + http_t *http,<br> + const char *dest,<br> + char *buffer,<br> + int bufsize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>dest</dt> +<dd class="description">Printer or class</dd> +<dt>buffer</dt> +<dd class="description">Filename buffer</dd> +<dt>bufsize</dt> +<dd class="description">Size of filename buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">PPD file or NULL</p> +<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsAdminExportSamba">cupsAdminExportSamba</a></h3> +<p class="description">Export a printer to Samba.</p> +<p class="code"> +int cupsAdminExportSamba (<br> + const char *dest,<br> + const char *ppd,<br> + const char *samba_server,<br> + const char *samba_user,<br> + const char *samba_password,<br> + FILE *logfile<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dest</dt> +<dd class="description">Destination to export</dd> +<dt>ppd</dt> +<dd class="description">PPD file</dd> +<dt>samba_server</dt> +<dd class="description">Samba server</dd> +<dt>samba_user</dt> +<dd class="description">Samba username</dd> +<dt>samba_password</dt> +<dd class="description">Samba password</dd> +<dt>logfile</dt> +<dd class="description">Log file, if any</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3> +<p class="description">Get settings from the server.</p> +<p class="code"> +int cupsAdminGetServerSettings (<br> + http_t *http,<br> + int *num_settings,<br> + <a href="#cups_option_t">cups_option_t</a> **settings<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>num_settings</dt> +<dd class="description">Number of settings</dd> +<dt>settings</dt> +<dd class="description">Settings</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The returned settings should be freed with cupsFreeOptions() when +you are done with them. + +</p> +<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3> +<p class="description">Set settings on the server.</p> +<p class="code"> +int cupsAdminSetServerSettings (<br> + http_t *http,<br> + int num_settings,<br> + <a href="#cups_option_t">cups_option_t</a> *settings<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>num_settings</dt> +<dd class="description">Number of settings</dd> +<dt>settings</dt> +<dd class="description">Settings</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h3 class="function"><a name="cupsCancelJob">cupsCancelJob</a></h3> +<p class="description">Cancel a print job on the default server.</p> +<p class="code"> +int cupsCancelJob (<br> + const char *name,<br> + int job_id<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Name of printer or class</dd> +<dt>job_id</dt> +<dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code> +to cancel the current job on the named destination.<br> +<br> +Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get +the cause of any failure.</p> +<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsCancelJob2">cupsCancelJob2</a></h3> +<p class="description">Cancel or purge a print job.</p> +<p class="code"> +ipp_status_t cupsCancelJob2 (<br> + http_t *http,<br> + const char *name,<br> + int job_id,<br> + int purge<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> +<dd class="description">Name of printer or class</dd> +<dt>job_id</dt> +<dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd> +<dt>purge</dt> +<dd class="description">1 to purge, 0 to cancel</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">IPP status</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Canceled jobs remain in the job history while purged jobs are removed +from the job history.<br> +<br> +Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code> +to cancel the current job on the named destination.<br> +<br> +Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get +the cause of any failure. + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsCreateJob">cupsCreateJob</a></h3> +<p class="description">Create an empty job for streaming.</p> +<p class="code"> +int cupsCreateJob (<br> + 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_ENCRYPT_IF_REQUESTED</code>.<br> +<br> +Note: The current encryption setting is tracked separately for each thread +in a program. Multi-threaded programs that override the setting via the +<a href="#cupsSetEncryption"><code>cupsSetEncryption</code></a> function need to do so in each thread for the same +setting to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsFinishDocument">cupsFinishDocument</a></h3> +<p class="description">Finish sending a document.</p> +<p class="code"> +ipp_status_t cupsFinishDocument (<br> + http_t *http,<br> + const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> +<dd class="description">Destination name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Status of document submission</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>. + +</p> +<h3 class="function"><a name="cupsFreeDests">cupsFreeDests</a></h3> +<p class="description">Free the memory used by the list of destinations.</p> +<p class="code"> +void cupsFreeDests (<br> + int num_dests,<br> + <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>num_dests</dt> +<dd class="description">Number of destinations</dd> +<dt>dests</dt> +<dd class="description">Destinations</dd> +</dl> +<h3 class="function"><a name="cupsFreeJobs">cupsFreeJobs</a></h3> +<p class="description">Free memory used by job data.</p> +<p class="code"> +void cupsFreeJobs (<br> + int num_jobs,<br> + <a href="#cups_job_t">cups_job_t</a> *jobs<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>num_jobs</dt> +<dd class="description">Number of jobs</dd> +<dt>jobs</dt> +<dd class="description">Jobs</dd> +</dl> +<h3 class="function"><a name="cupsFreeOptions">cupsFreeOptions</a></h3> +<p class="description">Free all memory used by options.</p> +<p class="code"> +void cupsFreeOptions (<br> + int num_options,<br> + <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>num_options</dt> +<dd class="description">Number of options</dd> +<dt>options</dt> +<dd class="description">Pointer to options</dd> +</dl> +<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsGetClasses">cupsGetClasses</a></h3> +<p class="description">Get a list of printer classes from the default server.</p> +<p class="code"> +int cupsGetClasses (<br> + char ***classes<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>classes</dt> +<dd class="description">Classes</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of classes</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead. + +</p> +<h3 class="function"><a name="cupsGetDefault">cupsGetDefault</a></h3> +<p class="description">Get the default printer or class for the default server.</p> +<p class="code"> +const char *cupsGetDefault (void);</p> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Default printer or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function returns the default printer or class as defined by +the LPDEST or PRINTER environment variables. If these environment +variables are not set, the server default destination is returned. +Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> +functions to get the user-defined default printer, as this function does +not support the lpoptions-defined default printer.</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetDefault2">cupsGetDefault2</a></h3> +<p class="description">Get the default printer or class for the specified server.</p> +<p class="code"> +const char *cupsGetDefault2 (<br> + http_t *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Default printer or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function returns the default printer or class as defined by +the LPDEST or PRINTER environment variables. If these environment +variables are not set, the server default destination is returned. +Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> +functions to get the user-defined default printer, as this function does +not support the lpoptions-defined default printer. + +</p> +<h3 class="function"><a name="cupsGetDest">cupsGetDest</a></h3> +<p class="description">Get the named destination from the list.</p> +<p class="code"> +<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest (<br> + const char *name,<br> + const char *instance,<br> + int num_dests,<br> + <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Destination name or <code>NULL</code> for the default destination</dd> +<dt>instance</dt> +<dd class="description">Instance name or <code>NULL</code></dd> +<dt>num_dests</dt> +<dd class="description">Number of destinations</dd> +<dt>dests</dt> +<dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Destination pointer or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a +list of supported destinations for the current user.</p> +<h3 class="function"><a name="cupsGetDests">cupsGetDests</a></h3> +<p class="description">Get the list of destinations from the default server.</p> +<p class="code"> +int cupsGetDests (<br> + <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dests</dt> +<dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of destinations</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the +printer-info, printer-is-accepting-jobs, printer-is-shared, +printer-make-and-model, printer-state, printer-state-change-time, +printer-state-reasons, and printer-type attributes as options. 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/Mac OS X 10.4 </span><a name="cupsGetDests2">cupsGetDests2</a></h3> +<p class="description">Get the list of destinations from the specified server.</p> +<p class="code"> +int cupsGetDests2 (<br> + http_t *http,<br> + <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>dests</dt> +<dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of destinations</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the +printer-info, printer-is-accepting-jobs, printer-is-shared, +printer-make-and-model, printer-state, printer-state-change-time, +printer-state-reasons, and printer-type attributes as options. 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"><a name="cupsGetJobs">cupsGetJobs</a></h3> +<p class="description">Get the jobs from the default server.</p> +<p class="code"> +int cupsGetJobs (<br> + <a href="#cups_job_t">cups_job_t</a> **jobs,<br> + const char *name,<br> + int myjobs,<br> + int whichjobs<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>jobs</dt> +<dd class="description">Job data</dd> +<dt>name</dt> +<dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd> +<dt>myjobs</dt> +<dd class="description">0 = all users, 1 = mine</dd> +<dt>whichjobs</dt> +<dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of jobs</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless +of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are +pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns +jobs that are stopped, canceled, aborted, or completed.</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3> +<p class="description">Get the jobs from the specified server.</p> +<p class="code"> +int cupsGetJobs2 (<br> + http_t *http,<br> + <a href="#cups_job_t">cups_job_t</a> **jobs,<br> + const char *name,<br> + int myjobs,<br> + int whichjobs<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>jobs</dt> +<dd class="description">Job data</dd> +<dt>name</dt> +<dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd> +<dt>myjobs</dt> +<dd class="description">0 = all users, 1 = mine</dd> +<dt>whichjobs</dt> +<dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of jobs</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless +of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are +pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns +jobs that are stopped, canceled, aborted, or completed. + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3> +<p class="description">Get options for the named destination.</p> +<p class="code"> +<a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br> + http_t *http,<br> + const char *name,<br> + const char *instance<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> +<dd class="description">Destination name or <code>NULL</code> for the default destination</dd> +<dt>instance</dt> +<dd class="description">Instance name or <code>NULL</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Destination or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function is optimized for retrieving a single destination and should +be used instead of <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you either +know the name of the destination or want to print to the default destination. +If <code>NULL</code> is returned, the destination does not exist or there is no +default destination.<br> +<br> +If "http" is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print +server will be used.<br> +<br> +If "name" is <code>NULL</code>, the default printer for the current user will be +returned.<br> +<br> +The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a +"num_dests" value of 1. + +</p> +<h3 class="function"><a name="cupsGetOption">cupsGetOption</a></h3> +<p class="description">Get an option value.</p> +<p class="code"> +const char *cupsGetOption (<br> + const char *name,<br> + int num_options,<br> + <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Name of option</dd> +<dt>num_options</dt> +<dd class="description">Number of options</dd> +<dt>options</dt> +<dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Option value or <code>NULL</code></p> +<h3 class="function"><a name="cupsGetPPD">cupsGetPPD</a></h3> +<p class="description">Get the PPD file for a printer on the default server.</p> +<p class="code"> +const char *cupsGetPPD (<br> + const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Destination name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Filename for PPD file</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">For classes, <code>cupsGetPPD</code> returns the PPD file for the first printer +in the class.<br> +<br> +The returned filename is stored in a static buffer and is overwritten with +each call to <code>cupsGetPPD</code> or <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>. The caller "owns" the +file that is created and must <code>unlink</code> the returned filename.</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetPPD2">cupsGetPPD2</a></h3> +<p class="description">Get the PPD file for a printer from the specified server.</p> +<p class="code"> +const char *cupsGetPPD2 (<br> + http_t *http,<br> + const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> +<dd class="description">Destination name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Filename for PPD file</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">For classes, <code>cupsGetPPD2</code> returns the PPD file for the first printer +in the class.<br> +<br> +The returned filename is stored in a static buffer and is overwritten with +each call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a> or <code>cupsGetPPD2</code>. The caller "owns" the +file that is created and must <code>unlink</code> the returned filename. + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3> +<p class="description">Get the PPD file for a printer on the specified +server if it has changed.</p> +<p class="code"> +http_status_t cupsGetPPD3 (<br> + http_t *http,<br> + const char *name,<br> + time_t *modtime,<br> + char *buffer,<br> + size_t bufsize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> +<dd class="description">Destination name</dd> +<dt>modtime</dt> +<dd class="description">Modification time</dd> +<dt>buffer</dt> +<dd class="description">Filename buffer</dd> +<dt>bufsize</dt> +<dd class="description">Size of filename buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">HTTP status</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The "modtime" parameter contains the modification time of any +locally-cached content and is updated with the time from the PPD file on +the server.<br> +<br> +The "buffer" parameter contains the local PPD filename. If it contains +the empty string, a new temporary file is created, otherwise the existing +file will be overwritten as needed. The caller "owns" the file that is +created and must <code>unlink</code> the returned filename.<br> +<br> +On success, <code>HTTP_OK</code> is returned for a new PPD file and +<code>HTTP_NOT_MODIFIED</code> if the existing PPD file is up-to-date. Any other +status is an error.<br> +<br> +For classes, <code>cupsGetPPD3</code> returns the PPD file for the first printer +in the class. + +</p> +<h3 class="function"><a name="cupsGetPassword">cupsGetPassword</a></h3> +<p class="description">Get a password from the user.</p> +<p class="code"> +const char *cupsGetPassword (<br> + const char *prompt<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>prompt</dt> +<dd class="description">Prompt string</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Password</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the +user does not provide a password.<br> +<br> +Note: The current password callback function is tracked separately for each +thread in a program. Multi-threaded programs that override the setting via +the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to +do so in each thread for the same function to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetPassword2">cupsGetPassword2</a></h3> +<p class="description">Get a password from the user using the advanced +password callback.</p> +<p class="code"> +const char *cupsGetPassword2 (<br> + const char *prompt,<br> + http_t *http,<br> + const char *method,<br> + const char *resource<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>prompt</dt> +<dd class="description">Prompt string</dd> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>method</dt> +<dd class="description">Request method ("GET", "POST", "PUT")</dd> +<dt>resource</dt> +<dd class="description">Resource path</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Password</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the +user does not provide a password.<br> +<br> +Note: The current password callback function is tracked separately for each +thread in a program. Multi-threaded programs that override the setting via +the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to +do so in each thread for the same function to be used. + +</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsGetPrinters">cupsGetPrinters</a></h3> +<p class="description">Get a list of printers from the default server.</p> +<p class="code"> +int cupsGetPrinters (<br> + char ***printers<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>printers</dt> +<dd class="description">Printers</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of printers</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead. + +</p> +<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3> +<p class="description">Get an available PPD file from the server.</p> +<p class="code"> +char *cupsGetServerPPD (<br> + http_t *http,<br> + const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> +<dd class="description">Name of PPD file ("ppd-name")</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Name of PPD file or <code>NULL</code> on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function returns the named PPD file from the server. The +list of available PPDs is provided by the IPP <code>CUPS_GET_PPDS</code> +operation.<br> +<br> +You must remove (unlink) the PPD file when you are finished with +it. The PPD filename is stored in a static location that will be +overwritten on the next call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a>, <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>, +or <a href="#cupsGetServerPPD"><code>cupsGetServerPPD</code></a>. + +</p> +<h3 class="function"><a name="cupsLangDefault">cupsLangDefault</a></h3> +<p class="description">Return the default language.</p> +<p class="code"> +cups_lang_t *cupsLangDefault (void);</p> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Language data</p> +<h3 class="function"><a name="cupsLangEncoding">cupsLangEncoding</a></h3> +<p class="description">Return the character encoding (us-ascii, etc.) +for the given language.</p> +<p class="code"> +const char *cupsLangEncoding (<br> + cups_lang_t *lang<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>lang</dt> +<dd class="description">Language data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Character encoding</p> +<h3 class="function"><a name="cupsLangFlush">cupsLangFlush</a></h3> +<p class="description">Flush all language data out of the cache.</p> +<p class="code"> +void cupsLangFlush (void);</p> +<h3 class="function"><a name="cupsLangFree">cupsLangFree</a></h3> +<p class="description">Free language data.</p> +<p class="code"> +void cupsLangFree (<br> + cups_lang_t *lang<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>lang</dt> +<dd class="description">Language to free</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This does not actually free anything; use <a href="#cupsLangFlush"><code>cupsLangFlush</code></a> for that.</p> +<h3 class="function"><a name="cupsLangGet">cupsLangGet</a></h3> +<p class="description">Get a language.</p> +<p class="code"> +cups_lang_t *cupsLangGet (<br> + const char *language<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>language</dt> +<dd class="description">Language or locale</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Language data</p> +<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3> +<p class="description">Return the subject for the given notification message.</p> +<p class="code"> +char *cupsNotifySubject (<br> + cups_lang_t *lang,<br> + ipp_t *event<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>lang</dt> +<dd class="description">Language data</dd> +<dt>event</dt> +<dd class="description">Event data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Subject string or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The returned string must be freed by the caller using <code>free</code>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsNotifyText">cupsNotifyText</a></h3> +<p class="description">Return the text for the given notification message.</p> +<p class="code"> +char *cupsNotifyText (<br> + cups_lang_t *lang,<br> + ipp_t *event<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>lang</dt> +<dd class="description">Language data</dd> +<dt>event</dt> +<dd class="description">Event data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Message text or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The returned string must be freed by the caller using <code>free</code>. + +</p> +<h3 class="function"><a name="cupsParseOptions">cupsParseOptions</a></h3> +<p class="description">Parse options from a command-line argument.</p> +<p class="code"> +int cupsParseOptions (<br> + const char *arg,<br> + int num_options,<br> + <a href="#cups_option_t">cups_option_t</a> **options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>arg</dt> +<dd class="description">Argument to parse</dd> +<dt>num_options</dt> +<dd class="description">Number of options</dd> +<dt>options</dt> +<dd class="description">Options found</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of options found</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function converts space-delimited name/value pairs according +to the PAPI text option ABNF specification. Collection values +("name={a=... b=... c=...}") are stored with the curley brackets +intact - use <code>cupsParseOptions</code> on the value to extract the +collection attributes.</p> +<h3 class="function"><a name="cupsPrintFile">cupsPrintFile</a></h3> +<p class="description">Print a file to a printer or class on the default server.</p> +<p class="code"> +int cupsPrintFile (<br> + const char *name,<br> + const char *filename,<br> + const char *title,<br> + int num_options,<br> + <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Destination name</dd> +<dt>filename</dt> +<dd class="description">File to print</dd> +<dt>title</dt> +<dd class="description">Title of job</dd> +<dt>num_options</dt> +<dd class="description">Number of options</dd> +<dt>options</dt> +<dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Job ID or 0 on error</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsPrintFile2">cupsPrintFile2</a></h3> +<p class="description">Print a file to a printer or class on the specified +server.</p> +<p class="code"> +int cupsPrintFile2 (<br> + http_t *http,<br> + const char *name,<br> + const char *filename,<br> + const char *title,<br> + int num_options,<br> + <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server</dd> +<dt>name</dt> +<dd class="description">Destination name</dd> +<dt>filename</dt> +<dd class="description">File to print</dd> +<dt>title</dt> +<dd class="description">Title of job</dd> +<dt>num_options</dt> +<dd class="description">Number of options</dd> +<dt>options</dt> +<dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Job ID or 0 on error</p> +<h3 class="function"><a name="cupsPrintFiles">cupsPrintFiles</a></h3> +<p class="description">Print one or more files to a printer or class on the +default server.</p> +<p class="code"> +int cupsPrintFiles (<br> + const char *name,<br> + int num_files,<br> + const char **files,<br> + const char *title,<br> + int num_options,<br> + <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Destination name</dd> +<dt>num_files</dt> +<dd class="description">Number of files</dd> +<dt>files</dt> +<dd class="description">File(s) to print</dd> +<dt>title</dt> +<dd class="description">Title of job</dd> +<dt>num_options</dt> +<dd class="description">Number of options</dd> +<dt>options</dt> +<dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Job ID or 0 on error</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3> +<p class="description">Print one or more files to a printer or class on the +specified server.</p> +<p class="code"> +int cupsPrintFiles2 (<br> + http_t *http,<br> + const char *name,<br> + int num_files,<br> + const char **files,<br> + const char *title,<br> + int num_options,<br> + <a href="#cups_option_t">cups_option_t</a> *options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> +<dd class="description">Destination name</dd> +<dt>num_files</dt> +<dd class="description">Number of files</dd> +<dt>files</dt> +<dd class="description">File(s) to print</dd> +<dt>title</dt> +<dd class="description">Title of job</dd> +<dt>num_options</dt> +<dd class="description">Number of options</dd> +<dt>options</dt> +<dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Job ID or 0 on error</p> +<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3> +<p class="description">Remove a destination from the destination list.</p> +<p class="code"> +int cupsRemoveDest (<br> + const char *name,<br> + const char *instance,<br> + int num_dests,<br> + <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Destination name</dd> +<dt>instance</dt> +<dd class="description">Instance name or <code>NULL</code></dd> +<dt>num_dests</dt> +<dd class="description">Number of destinations</dd> +<dt>dests</dt> +<dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">New number of destinations</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Removing a destination/instance does not delete the class or printer +queue, merely the lpoptions for that destination/instance. Use the +<a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new +options for the user. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3> +<p class="description">Remove an option from an option array.</p> +<p class="code"> +int cupsRemoveOption (<br> + const char *name,<br> + int num_options,<br> + <a href="#cups_option_t">cups_option_t</a> **options<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Option name</dd> +<dt>num_options</dt> +<dd class="description">Current number of options</dd> +<dt>options</dt> +<dd class="description">Options</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">New number of options</p> +<h3 class="function"><a name="cupsServer">cupsServer</a></h3> +<p class="description">Return the hostname/address of the current server.</p> +<p class="code"> +const char *cupsServer (void);</p> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Server name</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the +~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not +set, the default is the local system - either "localhost" or a domain socket +path.<br> +<br> +The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6 +address, or a domain socket pathname.<br> +<br> +Note: The current server is tracked separately for each thread in a program. +Multi-threaded programs that override the server via the +<a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same +server to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.5/Mac 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/Mac 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/Mac OS X 10.5 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3> +<p class="description">Set the default destination.</p> +<p class="code"> +void cupsSetDefaultDest (<br> + const char *name,<br> + const char *instance,<br> + int num_dests,<br> + <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Destination name</dd> +<dt>instance</dt> +<dd class="description">Instance name or <code>NULL</code></dd> +<dt>num_dests</dt> +<dd class="description">Number of destinations</dd> +<dt>dests</dt> +<dd class="description">Destinations</dd> +</dl> +<h3 class="function"><a name="cupsSetDests">cupsSetDests</a></h3> +<p class="description">Save the list of destinations for the default server.</p> +<p class="code"> +void cupsSetDests (<br> + int num_dests,<br> + <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>num_dests</dt> +<dd class="description">Number of destinations</dd> +<dt>dests</dt> +<dd class="description">Destinations</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run +as root and ~/.cups/lpoptions when run as a normal user.</p> +<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsSetDests2">cupsSetDests2</a></h3> +<p class="description">Save the list of destinations for the specified server.</p> +<p class="code"> +int cupsSetDests2 (<br> + http_t *http,<br> + int num_dests,<br> + <a href="#cups_dest_t">cups_dest_t</a> *dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>num_dests</dt> +<dd class="description">Number of destinations</dd> +<dt>dests</dt> +<dd class="description">Destinations</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">0 on success, -1 on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run +as root and ~/.cups/lpoptions when run as a normal user. + +</p> +<h3 class="function"><a name="cupsSetEncryption">cupsSetEncryption</a></h3> +<p class="description">Set the encryption preference.</p> +<p class="code"> +void cupsSetEncryption (<br> + http_encryption_t e<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>e</dt> +<dd class="description">New encryption preference</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION +environment variable, then the ~/.cups/client.conf file, and finally the +/etc/cups/client.conf file. If not set, the default is +<code>HTTP_ENCRYPT_IF_REQUESTED</code>.<br> +<br> +Note: The current encryption setting is tracked separately for each thread +in a program. Multi-threaded programs that override the setting need to do +so in each thread for the same setting to be used.</p> +<h3 class="function"><a name="cupsSetPasswordCB">cupsSetPasswordCB</a></h3> +<p class="description">Set the password callback for CUPS.</p> +<p class="code"> +void cupsSetPasswordCB (<br> + <a href="#cups_password_cb_t">cups_password_cb_t</a> cb<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cb</dt> +<dd class="description">Callback function</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which +reads the password from the console. Programs should call either this +function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered +by a program per thread.<br> +<br> +Note: The current password callback is tracked separately for each thread +in a program. Multi-threaded programs that override the callback need to do +so in each thread for the same callback to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3> +<p class="description">Set the advanced password callback for CUPS.</p> +<p class="code"> +void cupsSetPasswordCB2 (<br> + <a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb,<br> + void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cb</dt> +<dd class="description">Callback function</dd> +<dt>user_data</dt> +<dd class="description">User data pointer</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which +reads the password from the console. Programs should call either this +function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered +by a program per thread.<br> +<br> +Note: The current password callback is tracked separately for each thread +in a program. Multi-threaded programs that override the callback need to do +so in each thread for the same callback to be used. + +</p> +<h3 class="function"><a name="cupsSetServer">cupsSetServer</a></h3> +<p class="description">Set the default server name and port.</p> +<p class="code"> +void cupsSetServer (<br> + const char *server<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>server</dt> +<dd class="description">Server name</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The "server" string can be a fully-qualified hostname, a numeric +IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP +addresses can be optionally followed by a colon and port number to override +the default port 631, e.g. "hostname:8631". Pass <code>NULL</code> to restore the +default server name and port.<br> +<br> +Note: The current server is tracked separately for each thread in a program. +Multi-threaded programs that override the server need to do so in each +thread for the same server to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cupsSetServerCertCB">cupsSetServerCertCB</a></h3> +<p class="description">Set the server certificate callback.</p> +<p class="code"> +void cupsSetServerCertCB (<br> + <a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a> cb,<br> + void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cb</dt> +<dd class="description">Callback function</dd> +<dt>user_data</dt> +<dd class="description">User data pointer</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Pass <code>NULL</code> to restore the default callback.<br> +<br> +Note: The current credentials callback is tracked separately for each thread +in a program. Multi-threaded programs that override the callback need to do +so in each thread for the same callback to be used. + +</p> +<h3 class="function"><a name="cupsSetUser">cupsSetUser</a></h3> +<p class="description">Set the default user name.</p> +<p class="code"> +void cupsSetUser (<br> + const char *user<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>user</dt> +<dd class="description">User name</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Pass <code>NULL</code> to restore the default user name.<br> +<br> +Note: The current user name is tracked separately for each thread in a +program. Multi-threaded programs that override the user name need to do so +in each thread for the same user name to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsStartDocument">cupsStartDocument</a></h3> +<p class="description">Add a document to a job created with cupsCreateJob().</p> +<p class="code"> +http_status_t cupsStartDocument (<br> + http_t *http,<br> + const char *name,<br> + int job_id,<br> + const char *docname,<br> + const char *format,<br> + int last_document<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> +<dt>name</dt> +<dd class="description">Destination name</dd> +<dt>job_id</dt> +<dd class="description">Job ID from <a href="#cupsCreateJob"><code>cupsCreateJob</code></a></dd> +<dt>docname</dt> +<dd class="description">Name of document</dd> +<dt>format</dt> +<dd class="description">MIME type or <code>CUPS_FORMAT_foo</code></dd> +<dt>last_document</dt> +<dd class="description">1 for last document in job, 0 otherwise</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">HTTP status of request</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write data for the document and +<a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> to finish the document and get the submission status.<br> +<br> +The MIME type constants <code>CUPS_FORMAT_AUTO</code>, <code>CUPS_FORMAT_PDF</code>, +<code>CUPS_FORMAT_POSTSCRIPT</code>, <code>CUPS_FORMAT_RAW</code>, and +<code>CUPS_FORMAT_TEXT</code> are provided for the "format" argument, although +any supported MIME type string can be supplied. + +</p> +<h3 class="function"><a name="cupsTempFd">cupsTempFd</a></h3> +<p class="description">Creates a temporary file.</p> +<p class="code"> +int cupsTempFd (<br> + char *filename,<br> + int len<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>filename</dt> +<dd class="description">Pointer to buffer</dd> +<dt>len</dt> +<dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">New file descriptor or -1 on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The temporary filename is returned in the filename buffer. +The temporary file is opened for reading and writing.</p> +<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsTempFile">cupsTempFile</a></h3> +<p class="description">Generates a temporary filename.</p> +<p class="code"> +char *cupsTempFile (<br> + char *filename,<br> + int len<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>filename</dt> +<dd class="description">Pointer to buffer</dd> +<dt>len</dt> +<dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Filename or <code>NULL</code> on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The temporary filename is returned in the filename buffer. +This function is deprecated - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or +<a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead. + +</p> +<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsTempFile2">cupsTempFile2</a></h3> +<p class="description">Creates a temporary CUPS file.</p> +<p class="code"> +cups_file_t *cupsTempFile2 (<br> + char *filename,<br> + int len<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>filename</dt> +<dd class="description">Pointer to buffer</dd> +<dt>len</dt> +<dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">CUPS file or <code>NULL</code> on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The temporary filename is returned in the filename buffer. +The temporary file is opened for writing. + +</p> +<h3 class="function"><a name="cupsUser">cupsUser</a></h3> +<p class="description">Return the current user's name.</p> +<p class="code"> +const char *cupsUser (void);</p> +<h4 class="returnvalue">Return Value</h4> +<p class="description">User name</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Note: The current user name is tracked separately for each thread in a +program. Multi-threaded programs that override the user name with the +<a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user +name to be used.</p> +<h2 class="title"><a name="TYPES">Data Types</a></h2> +<h3 class="typedef"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cups_client_cert_cb_t">cups_client_cert_cb_t</a></h3> +<p class="description">Client credentials callback </p> +<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"><a name="cups_dest_t">cups_dest_t</a></h3> +<p class="description">Destination</p> +<p class="code"> +typedef struct <a href="#cups_dest_s">cups_dest_s</a> cups_dest_t; +</p> +<h3 class="typedef"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cups_device_cb_t">cups_device_cb_t</a></h3> +<p class="description">Device callback </p> +<p class="code"> +typedef void (*cups_device_cb_t)(const char *device_class, const char *device_id, const char *device_info, const char *device_make_and_model, const char *device_uri, const char *device_location, void *user_data); +</p> +<h3 class="typedef"><a name="cups_job_t">cups_job_t</a></h3> +<p class="description">Job</p> +<p class="code"> +typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t; +</p> +<h3 class="typedef"><a name="cups_option_t">cups_option_t</a></h3> +<p class="description">Printer Options</p> +<p class="code"> +typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t; +</p> +<h3 class="typedef"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cups_password_cb2_t">cups_password_cb2_t</a></h3> +<p class="description">New password callback </p> +<p class="code"> +typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data); +</p> +<h3 class="typedef"><a name="cups_password_cb_t">cups_password_cb_t</a></h3> +<p class="description">Password callback</p> +<p class="code"> +typedef const char *(*cups_password_cb_t)(const char *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/Mac OS X 10.7 </span><a name="cups_server_cert_cb_t">cups_server_cert_cb_t</a></h3> +<p class="description">Server credentials callback </p> +<p class="code"> +typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *certs, void *user_data); +</p> +<h2 class="title"><a name="STRUCTURES">Structures</a></h2> +<h3 class="struct"><a name="cups_dest_s">cups_dest_s</a></h3> +<p class="description">Destination</p> +<p class="code">struct cups_dest_s {<br> + char *name, *instance;<br> + int is_default;<br> + int num_options;<br> + <a href="#cups_option_t">cups_option_t</a> *options;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>instance </dt> +<dd class="description">Local instance name or NULL</dd> +<dt>is_default </dt> +<dd class="description">Is this printer the default?</dd> +<dt>num_options </dt> +<dd class="description">Number of options</dd> +<dt>options </dt> +<dd class="description">Options</dd> +</dl> +<h3 class="struct"><a name="cups_job_s">cups_job_s</a></h3> +<p class="description">Job</p> +<p class="code">struct cups_job_s {<br> + time_t completed_time;<br> + time_t creation_time;<br> + char *dest;<br> + char *format;<br> + int id;<br> + int priority;<br> + time_t processing_time;<br> + int size;<br> + ipp_jstate_t state;<br> + char *title;<br> + char *user;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>completed_time </dt> +<dd class="description">Time the job was completed</dd> +<dt>creation_time </dt> +<dd class="description">Time the job was created</dd> +<dt>dest </dt> +<dd class="description">Printer or class name</dd> +<dt>format </dt> +<dd class="description">Document format</dd> +<dt>id </dt> +<dd class="description">The job ID</dd> +<dt>priority </dt> +<dd class="description">Priority (1-100)</dd> +<dt>processing_time </dt> +<dd class="description">Time the job was processed</dd> +<dt>size </dt> +<dd class="description">Size in kilobytes</dd> +<dt>state </dt> +<dd class="description">Job state</dd> +<dt>title </dt> +<dd class="description">Title/job name</dd> +<dt>user </dt> +<dd class="description">User the submitted the job</dd> +</dl> +<h3 class="struct"><a name="cups_option_s">cups_option_s</a></h3> +<p class="description">Printer Options</p> +<p class="code">struct cups_option_s {<br> + char *name;<br> + char *value;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>name </dt> +<dd class="description">Name of option</dd> +<dt>value </dt> +<dd class="description">Value of option</dd> +</dl> +<h2 class="title"><a name="VARIABLES">Variables</a></h2> +<h3 class="variable"><a name="CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></h3> +<p class="description">Get the Apple language identifier associated with a +locale ID.</p> +<p class="code">const char *locale) CF_RETURNS_RETAINED;</p> +<h2 class="title"><a name="ENUMERATIONS">Constants</a></h2> +<h3 class="enumeration"><a name="cups_ptype_e">cups_ptype_e</a></h3> +<p class="description">Printer type/capability bit constants</p> +<h4 class="constants">Constants</h4> +<dl> +<dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dd class="description">Printer requires authentication </dd> +<dt>CUPS_PRINTER_BIND </dt> +<dd class="description">Can bind output</dd> +<dt>CUPS_PRINTER_BW </dt> +<dd class="description">Can do B&W printing</dd> +<dt>CUPS_PRINTER_CLASS </dt> +<dd class="description">Printer class</dd> +<dt>CUPS_PRINTER_COLLATE </dt> +<dd class="description">Can collage copies</dd> +<dt>CUPS_PRINTER_COLOR </dt> +<dd class="description">Can do color printing</dd> +<dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dd class="description">Printer supports maintenance commands </dd> +<dt>CUPS_PRINTER_COPIES </dt> +<dd class="description">Can do copies</dd> +<dt>CUPS_PRINTER_COVER </dt> +<dd class="description">Can cover output</dd> +<dt>CUPS_PRINTER_DEFAULT </dt> +<dd class="description">Default printer on network</dd> +<dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dd class="description">Delete printer </dd> +<dt>CUPS_PRINTER_DISCOVERED <span class="info"> CUPS 1.3/Mac OS X 10.5 </span></dt> +<dd class="description">Printer was automatically discovered and added </dd> +<dt>CUPS_PRINTER_DUPLEX </dt> +<dd class="description">Can do duplexing</dd> +<dt>CUPS_PRINTER_FAX </dt> +<dd class="description">Fax queue</dd> +<dt>CUPS_PRINTER_IMPLICIT </dt> +<dd class="description">Implicit class</dd> +<dt>CUPS_PRINTER_LARGE </dt> +<dd class="description">Can do D/E/A1/A0</dd> +<dt>CUPS_PRINTER_LOCAL </dt> +<dd class="description">Local printer or class</dd> +<dt>CUPS_PRINTER_MEDIUM </dt> +<dd class="description">Can do Tabloid/B/C/A3/A2</dd> +<dt>CUPS_PRINTER_MFP <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt> +<dd class="description">Printer with scanning capabilities </dd> +<dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dd class="description">Printer is not shared </dd> +<dt>CUPS_PRINTER_PUNCH </dt> +<dd class="description">Can punch output</dd> +<dt>CUPS_PRINTER_REJECTING </dt> +<dd class="description">Printer is rejecting jobs</dd> +<dt>CUPS_PRINTER_REMOTE </dt> +<dd class="description">Remote printer or class</dd> +<dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt> +<dd class="description">Scanner-only device </dd> +<dt>CUPS_PRINTER_SMALL </dt> +<dd class="description">Can do Letter/Legal/A4</dd> +<dt>CUPS_PRINTER_SORT </dt> +<dd class="description">Can sort output</dd> +<dt>CUPS_PRINTER_STAPLE </dt> +<dd class="description">Can staple output</dd> +<dt>CUPS_PRINTER_VARIABLE </dt> +<dd class="description">Can do variable sizes</dd> +</dl> +</div> +</body> +</html> |