File: api-cups.html

package info (click to toggle)
cups 1.4.4-7%2Bsqueeze10
links: PTS, VCS
area: main
in suites: squeeze-lts
size: 25,548 kB
ctags: 9,583
sloc: ansic: 138,214; sh: 37,926; cpp: 25,469; makefile: 3,285; perl: 190; python: 127; php: 28
file content (2426 lines) | stat: -rw-r--r-- 94,365 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
<title>CUPS API</title>
<meta name="keywords" content="Programming">
<meta name="creator" content="Mini-XML v2.6">
<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 {
  margin-left: 36pt;
}

P.compact {
  margin: 0;
}

P.example {
  font-style: italic;
  margin-left: 36pt;
}
  
PRE.example {
  background: #eeeeee;
  border: dotted thin #999999;
  margin-left: 36pt;
  padding: 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 9121 2010-04-23 18:57:00Z mike $"

  CUPS API header for the Common UNIX Printing System (CUPS).

  Copyright 2008-2009 by Apple Inc.

  These coded instructions, statements, and computer programs are the
  property of Apple Inc. and are protected by Federal copyright
  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">
<ul class="subcontents">
<li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
<li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li>
<li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li>
<li><a href="#OPTIONS">Options</a></li>
<li><a href="#PRINT_JOBS">Print Jobs</a></li>
<li><a href="#ERROR_HANDLING">Error Handling</a></li>
<li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li>
</ul></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
<li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li>
<li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li>
<li><a href="#cupsAdminCreateWindowsPPD" title="Create the Windows PPD file for a printer.">cupsAdminCreateWindowsPPD</a></li>
<li><a href="#cupsAdminExportSamba" title="Export a printer to Samba.">cupsAdminExportSamba</a></li>
<li><a href="#cupsAdminGetServerSettings" title="Get settings from the server.">cupsAdminGetServerSettings</a></li>
<li><a href="#cupsAdminSetServerSettings" title="Set settings on the server.">cupsAdminSetServerSettings</a></li>
<li><a href="#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="#cupsLastError" title="Return the last IPP status code.">cupsLastError</a></li>
<li><a href="#cupsLastErrorString" title="Return the last IPP status-message.">cupsLastErrorString</a></li>
<li><a href="#cupsNotifySubject" title="Return the subject for the given notification message.">cupsNotifySubject</a></li>
<li><a href="#cupsNotifyText" title="Return the text for the given notification message.">cupsNotifyText</a></li>
<li><a href="#cupsParseOptions" title="Parse options from a command-line argument.">cupsParseOptions</a></li>
<li><a href="#cupsPrintFile" title="Print a file to a printer or class on the default server.">cupsPrintFile</a></li>
<li><a href="#cupsPrintFile2" title="Print a file to a printer or class on the specified
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="#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="#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_dest_t" title="Destination">cups_dest_t</a></li>
	<li><a href="#cups_device_cb_t" title="Device callback ">cups_device_cb_t</a></li>
	<li><a href="#cups_job_t" title="Job">cups_job_t</a></li>
	<li><a href="#cups_option_t" title="Printer Options">cups_option_t</a></li>
	<li><a href="#cups_password_cb2_t" title="New password callback ">cups_password_cb2_t</a></li>
	<li><a href="#cups_password_cb_t" title="Password callback">cups_password_cb_t</a></li>
	<li><a href="#cups_ptype_t" title="Printer type/capability bits">cups_ptype_t</a></li>
</ul></li>
<li><a href="#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="#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>
<!--
  "$Id: api-cups.html 9121 2010-04-23 18:57:00Z mike $"

  CUPS API introduction for the Common UNIX Printing System (CUPS).

  Copyright 2007-2010 by Apple Inc.
  Copyright 1997-2006 by Easy Software Products, all rights reserved.

  These coded instructions, statements, and computer programs are the
  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 &lt;cups/cups.h&gt;

<a href='#cups_dest_t'>cups_dest_t</a> *dests;
int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&amp;dests);
<a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests);

/* do something wiith dest */

<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 &lt;cups/cups.h&gt;

<a href='#cups_dest_t'>cups_dest_t</a> *dests;
int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&amp;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 &lt;cups/cups.h&gt;

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, &amp;options);

/* This adds a second option value */
num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &amp;options);

/* This replaces the first option we added */
num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &amp;options);
</pre>

<p>Use a <code>for</code> loop to copy the options from a destination:</p>

<pre class='example'>
#include &lt;cups/cups.h&gt;

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, &amp;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 &lt;cups/cups.h&gt;

<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 &lt;cups/cups.h&gt;

<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 &lt;cups/cups.h&gt;

<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 &lt;= 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 &lt;cups/cups.h&gt;

<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 &lt; IPP_JOB_STOPPED)
{
  /* Get my jobs (1) with any state (-1) */
  num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&amp;jobs, dest->name, 1, -1);

  /* Loop to find my job */
  job_state = IPP_JOB_COMPLETED;

  for (i = 0; i &lt; 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 &lt; 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 &lt;cups/cups.h&gt;

<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 &lt;cups/cups.h&gt;

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 &lt;cups/cups.h&gt;

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="cupsAddDest">cupsAddDest</a></h3>
<p class="description">Add a destination to the list of destinations.</p>
<p class="code">
int cupsAddDest (<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *instance,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *value,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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
&quot;num_options&quot; parameter.</p>
<h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *dest,<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsAdminExportSamba">cupsAdminExportSamba</a></h3>
<p class="description">Export a printer to Samba.</p>
<p class="code">
int cupsAdminExportSamba (<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *dest,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *ppd,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *samba_server,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *samba_user,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *samba_password,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.3/Mac OS X 10.5&nbsp;</span><a name="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3>
<p class="description">Get settings from the server.</p>
<p class="code">
int cupsAdminGetServerSettings (<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int *num_settings,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.3/Mac OS X 10.5&nbsp;</span><a name="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3>
<p class="description">Set settings on the server.</p>
<p class="code">
int cupsAdminSetServerSettings (<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_settings,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int job_id,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</span><a name="cupsCreateJob">cupsCreateJob</a></h3>
<p class="description">Create an empty job for streaming.</p>
<p class="code">
int cupsCreateJob (<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</span><a name="cupsFinishDocument">cupsFinishDocument</a></h3>
<p class="description">Finish sending a document.</p>
<p class="code">
ipp_status_t cupsFinishDocument (<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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>
&nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;int num_jobs,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;DEPRECATED&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.1.21/Mac OS X 10.4&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *instance,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.1.21/Mac OS X 10.4&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_job_t">cups_job_t</a> **jobs,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int myjobs,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;whichjobs&quot; 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">&nbsp;CUPS 1.1.21/Mac OS X 10.4&nbsp;</span><a name="cupsGetJobs2">cupsGetJobs2</a></h3>
<p class="description">Get the jobs from the specified server.</p>
<p class="code">
int cupsGetJobs2 (<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_job_t">cups_job_t</a> **jobs,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int myjobs,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;whichjobs&quot; 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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;http&quot; is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print
server will be used.<br>
<br>
If &quot;name&quot; 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
&quot;num_dests&quot; 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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;owns&quot; the
file that is created and must <code>unlink</code> the returned filename.</p>
<h3 class="function"><span class="info">&nbsp;CUPS 1.1.21/Mac OS X 10.4&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;owns&quot; the
file that is created and must <code>unlink</code> the returned filename.

</p>
<h3 class="function"><span class="info">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;time_t *modtime,<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;modtime&quot; 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 &quot;buffer&quot; 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 &quot;owns&quot; 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>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *prompt,<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *method,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 (&quot;GET&quot;, &quot;POST&quot;, &quot;PUT&quot;)</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">&nbsp;DEPRECATED&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.3/Mac OS X 10.5&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 (&quot;ppd-name&quot;)</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>
&nbsp;&nbsp;&nbsp;&nbsp;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>
&nbsp;&nbsp;&nbsp;&nbsp;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>
&nbsp;&nbsp;&nbsp;&nbsp;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"><a name="cupsLastError">cupsLastError</a></h3>
<p class="description">Return the last IPP status code.</p>
<p class="code">
ipp_status_t cupsLastError (void);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">IPP status code from last request</p>
<h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsLastErrorString">cupsLastErrorString</a></h3>
<p class="description">Return the last IPP status-message.</p>
<p class="code">
const char *cupsLastErrorString (void);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">status-message text from last request</p>
<h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;cups_lang_t *lang,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;cups_lang_t *lang,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *arg,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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
(&quot;name={a=... b=... c=...}&quot;) 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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *filename,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.1.21/Mac OS X 10.4&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *filename,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_files,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char **files,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.1.21/Mac OS X 10.4&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_files,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char **files,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.3/Mac OS X 10.5&nbsp;</span><a name="cupsRemoveDest">cupsRemoveDest</a></h3>
<p class="description">Remove a destination from the destination list.</p>
<p class="code">
int cupsRemoveDest (<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *instance,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsRemoveOption">cupsRemoveOption</a></h3>
<p class="description">Remove an option from an option array.</p>
<p class="code">
int cupsRemoveOption (<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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 &quot;localhost&quot; 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">&nbsp;CUPS 1.3/Mac OS X 10.5&nbsp;</span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
<p class="description">Set the default destination.</p>
<p class="code">
void cupsSetDefaultDest (<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *instance,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.1.21/Mac OS X 10.4&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;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>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</span><a name="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3>
<p class="description">Set the advanced password callback for CUPS.</p>
<p class="code">
void cupsSetPasswordCB2 (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;server&quot; 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. &quot;hostname:8631&quot;. Pass <code>NULL</code> to restore the
default server name and port.<br>
<br>
Note: The current server is tracked separately for each thread in a program.
Multi-threaded programs that override the server need to do so in each
thread for the same server to be used.</p>
<h3 class="function"><a name="cupsSetUser">cupsSetUser</a></h3>
<p class="description">Set the default user name.</p>
<p class="code">
void cupsSetUser (<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int job_id,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *docname,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;format&quot; 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>
&nbsp;&nbsp;&nbsp;&nbsp;char *filename,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;DEPRECATED&nbsp;</span><a name="cupsTempFile">cupsTempFile</a></h3>
<p class="description">Generates a temporary filename.</p>
<p class="code">
char *cupsTempFile (<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *filename,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsTempFile2">cupsTempFile2</a></h3>
<p class="description">Creates a temporary CUPS file.</p>
<p class="code">
cups_file_t *cupsTempFile2 (<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *filename,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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"><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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</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>
<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>
&nbsp;&nbsp;&nbsp;&nbsp;char *name, *instance;<br>
&nbsp;&nbsp;&nbsp;&nbsp;int is_default;<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_options;<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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>
&nbsp;&nbsp;&nbsp;&nbsp;time_t completed_time;<br>
&nbsp;&nbsp;&nbsp;&nbsp;time_t creation_time;<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *dest;<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *format;<br>
&nbsp;&nbsp;&nbsp;&nbsp;int id;<br>
&nbsp;&nbsp;&nbsp;&nbsp;int priority;<br>
&nbsp;&nbsp;&nbsp;&nbsp;time_t processing_time;<br>
&nbsp;&nbsp;&nbsp;&nbsp;int size;<br>
&nbsp;&nbsp;&nbsp;&nbsp;ipp_jstate_t state;<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *title;<br>
&nbsp;&nbsp;&nbsp;&nbsp;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>
&nbsp;&nbsp;&nbsp;&nbsp;char *name;<br>
&nbsp;&nbsp;&nbsp;&nbsp;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="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">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</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&amp;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">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</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">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span></dt>
<dd class="description">Delete printer </dd>
<dt>CUPS_PRINTER_DISCOVERED <span class="info">&nbsp;CUPS 1.3/Mac OS X 10.5&nbsp;</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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</span></dt>
<dd class="description">Printer with scanning capabilities </dd>
<dt>CUPS_PRINTER_NOT_SHARED <span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</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">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</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>