msweet
1f219e5ca3
git-svn-id: svn+ssh://src.apple.com/svn/cups/cups.org/tags/release-1.4b3@4306 a1ca3aef-8c08-0410-bb20-df032aa958be
2360 linhas
88 KiB
HTML
2360 linhas
88 KiB
HTML
<!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 8653 2009-05-16 23:53:28Z 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 default encryption settings.">cupsEncryption</a></li>
|
|
<li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li>
|
|
<li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li>
|
|
<li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li>
|
|
<li><a href="#cupsFreeOptions" title="Free all memory used by options.">cupsFreeOptions</a></li>
|
|
<li><a href="#cupsGetClasses" title="Get a list of printer classes from the default server.">cupsGetClasses</a></li>
|
|
<li><a href="#cupsGetDefault" title="Get the default printer or class for the default server.">cupsGetDefault</a></li>
|
|
<li><a href="#cupsGetDefault2" title="Get the default printer or class for the specified server.">cupsGetDefault2</a></li>
|
|
<li><a href="#cupsGetDest" title="Get the named destination from the list.">cupsGetDest</a></li>
|
|
<li><a href="#cupsGetDests" title="Get the list of destinations from the default server.">cupsGetDests</a></li>
|
|
<li><a href="#cupsGetDests2" title="Get the list of destinations from the specified server.">cupsGetDests2</a></li>
|
|
<li><a href="#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
|
|
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 default server.">cupsServer</a></li>
|
|
<li><a href="#cupsSetDefaultDest" title="Set the default destination.">cupsSetDefaultDest</a></li>
|
|
<li><a href="#cupsSetDests" title="Save the list of destinations for the default server.">cupsSetDests</a></li>
|
|
<li><a href="#cupsSetDests2" title="Save the list of destinations for the specified server.">cupsSetDests2</a></li>
|
|
<li><a href="#cupsSetEncryption" title="Set the encryption preference.">cupsSetEncryption</a></li>
|
|
<li><a href="#cupsSetPasswordCB" title="Set the password callback for CUPS.">cupsSetPasswordCB</a></li>
|
|
<li><a href="#cupsSetPasswordCB2" title="Set the advanced password callback for CUPS.">cupsSetPasswordCB2</a></li>
|
|
<li><a href="#cupsSetServer" title="Set the default server name.">cupsSetServer</a></li>
|
|
<li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li>
|
|
<li><a href="#cupsStartDocument" title="Add a document to a job created with cupsCreateJob().">cupsStartDocument</a></li>
|
|
<li><a href="#cupsTempFd" title="Creates a temporary file.">cupsTempFd</a></li>
|
|
<li><a href="#cupsTempFile" title="Generates a temporary filename.">cupsTempFile</a></li>
|
|
<li><a href="#cupsTempFile2" title="Creates a temporary CUPS file.">cupsTempFile2</a></li>
|
|
<li><a href="#cupsUser" title="Return the current user's name.">cupsUser</a></li>
|
|
</ul></li>
|
|
<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 8653 2009-05-16 23:53:28Z mike $"
|
|
|
|
CUPS API introduction for the Common UNIX Printing System (CUPS).
|
|
|
|
Copyright 2007-2008 by Apple Inc.
|
|
Copyright 1997-2006 by Easy Software Products, all rights reserved.
|
|
|
|
These coded instructions, statements, and computer programs are the
|
|
property of Apple Inc. and are protected by Federal copyright
|
|
law. Distribution and use rights are outlined in the file "LICENSE.txt"
|
|
which should have been included with this file. If this file is
|
|
file is missing or damaged, see the license at "http://www.cups.org/".
|
|
-->
|
|
|
|
<h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
|
|
|
|
<p>The CUPS API provides the convenience functions needed to support
|
|
applications, filters, printer drivers, and backends that need to interface
|
|
with the CUPS scheduler.</p>
|
|
|
|
<h3><a name='CLIENTS_AND_SERVERS'>Clients and Servers</a></h3>
|
|
|
|
<p>CUPS is based on the Internet Printing Protocol ("IPP"), which allows
|
|
clients (applications) to communicate with a server (the scheduler) to get a
|
|
list of printers, send print jobs, and so forth. You identify which server
|
|
you want to communicate with using a pointer to the opaque structure
|
|
<code>http_t</code>. All of the examples in this document use the
|
|
<code>CUPS_HTTP_DEFAULT</code> constant, referring to the default connection
|
|
to the scheduler. The <a href='api-httpipp.html' target='_top'>HTTP and IPP
|
|
APIs</a> document provides more information on server connections.</p>
|
|
|
|
<h3><a name='PRINTERS_AND_CLASSES'>Printers and Classes</a></h3>
|
|
|
|
<p>Printers and classes (collections of printers) are accessed through
|
|
the <a href="#cups_dest_t"><code>cups_dest_t</code></a> structure which
|
|
includes the name (<code>name</code>), instance (<code>instance</code> -
|
|
a way of selecting certain saved options/settings), and the options and
|
|
attributes associated with that destination (<code>num_options</code> and
|
|
<code>options</code>). Destinations are created using the
|
|
<a href="#cupsGetDests"><code>cupsGetDests</code></a> function and freed
|
|
using the <a href='#cupsFreeDests'><code>cupsFreeDests</code></a> function.
|
|
The <a href='#cupsGetDest'><code>cupsGetDest</code></a> function finds a
|
|
specific destination for printing:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dests;
|
|
int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests);
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests);
|
|
|
|
/* do something 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>"1" if the destination is accepting new jobs, "0" if not.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>"printer-is-shared"</td>
|
|
<td>"1" if the destination is being shared with other computers, "0" if
|
|
not.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>"printer-location"</td>
|
|
<td>The human-readable location of the destination such as "Lab 4".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>"printer-make-and-model"</td>
|
|
<td>The human-readable make and model of the destination such as "HP
|
|
LaserJet 4000 Series".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>"printer-state"</td>
|
|
<td>"3" if the destination is idle, "4" if the destination is printing
|
|
a job, and "5" if the destination is stopped.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>"printer-state-change-time"</td>
|
|
<td>The UNIX time when the destination entered the current state.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>"printer-state-reasons"</td>
|
|
<td>Additional comma-delimited state keywords for the destination
|
|
such as "media-tray-empty-error" and "toner-low-warning".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>"printer-type"</td>
|
|
<td>The <a href='#cups_printer_t'><code>cups_printer_t</code></a>
|
|
value associated with the destination.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table></div>
|
|
|
|
<h3><a name='OPTIONS'>Options</a></h3>
|
|
|
|
<p>Options are stored in arrays of
|
|
<a href='#cups_option_t'><code>cups_option_t</code></a> structures. Each
|
|
option has a name (<code>name</code>) and value (<code>value</code>)
|
|
associated with it. The <a href='#cups_dest_t'><code>cups_dest_t</code></a>
|
|
<code>num_options</code> and <code>options</code> members contain the
|
|
default options for a particular destination, along with several informational
|
|
attributes about the destination as shown in <a href='#TABLE1'>Table 1</a>.
|
|
The <a href='#cupsGetOption'><code>cupsGetOption</code></a> function gets
|
|
the value for the named option. For example, the following code lists the
|
|
available destinations and their human-readable descriptions:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dests;
|
|
int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests);
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dest;
|
|
int i;
|
|
const char *value;
|
|
|
|
for (i = num_dests, dest = dests; i > 0; i --, dest ++)
|
|
if (dest->instance == NULL)
|
|
{
|
|
value = <a href='#cupsGetOption'>cupsGetOption</a>("printer-info", dest->num_options, dest->options);
|
|
printf("%s (%s)\n", dest->name, value ? value : "no description");
|
|
}
|
|
|
|
<a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
|
|
</pre>
|
|
|
|
<p>You can create your own option arrays using the
|
|
<a href='#cupsAddOption'><code>cupsAddOption</code></a> function, which
|
|
adds a single named option to an array:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
int num_options = 0;
|
|
<a href='#cups_option_t'>cups_option_t</a> *options = NULL;
|
|
|
|
/* The returned num_options value is updated as needed */
|
|
num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "value", num_options, &options);
|
|
|
|
/* This adds a second option value */
|
|
num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &options);
|
|
|
|
/* This replaces the first option we added */
|
|
num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &options);
|
|
</pre>
|
|
|
|
<p>Use a <code>for</code> loop to copy the options from a destination:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
int i;
|
|
int num_options = 0;
|
|
<a href='#cups_option_t'>cups_option_t</a> *options = NULL;
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dest;
|
|
|
|
for (i = 0; i < dest->num_options; i ++)
|
|
num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value,
|
|
num_options, &options);
|
|
</pre>
|
|
|
|
<p>Use the <a href='#cupsFreeOptions'><code>cupsFreeOptions</code></a>
|
|
function to free the options array when you are done using it:</p>
|
|
|
|
<pre class='example'>
|
|
<a href='#cupsFreeOptions'>cupsFreeOptions</a>(num_options, options);
|
|
</pre>
|
|
|
|
<h3><a name='PRINT_JOBS'>Print Jobs</a></h3>
|
|
|
|
<p>Print jobs are identified by a locally-unique job ID number from 1 to
|
|
2<sup>31</sup>-1 and have options and one or more files for printing to a
|
|
single destination. The <a href='#cupsPrintFile'><code>cupsPrintFile</code></a>
|
|
function creates a new job with one file. The following code prints the CUPS
|
|
test page file:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dest;
|
|
int num_options;
|
|
<a href='#cups_option_t'>cups_option_t</a> *options;
|
|
int job_id;
|
|
|
|
/* Print a single file */
|
|
job_id = <a href='#cupsPrintFile'>cupsPrintFile</a>(dest->name, "/usr/share/cups/data/testprint.ps",
|
|
"Test Print", num_options, options);
|
|
</pre>
|
|
|
|
<p>The <a href='#cupsPrintFiles'><code>cupsPrintFiles</code></a> function
|
|
creates a job with multiple files. The files are provided in a
|
|
<code>char *</code> array:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dest;
|
|
int num_options;
|
|
<a href='#cups_option_t'>cups_option_t</a> *options;
|
|
int job_id;
|
|
char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" };
|
|
|
|
/* Print three files */
|
|
job_id = <a href='#cupsPrintFiles'>cupsPrintFiles</a>(dest->name, 3, files, "Test Print", num_options, options);
|
|
</pre>
|
|
|
|
<p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a>
|
|
function creates a new job with no files in it. Files are added using the
|
|
<a href='#cupsStartDocument'><code>cupsStartDocument</code></a>,
|
|
<a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>,
|
|
and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions.
|
|
The following example creates a job with 10 text files for printing:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dest;
|
|
int num_options;
|
|
<a href='#cups_option_t'>cups_option_t</a> *options;
|
|
int job_id;
|
|
int i;
|
|
char buffer[1024];
|
|
|
|
/* Create the job */
|
|
job_id = <a href='#cupsCreateJob'>cupsCreateJob</a>(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files",
|
|
num_options, options);
|
|
|
|
/* If the job is created, add 10 files */
|
|
if (job_id > 0)
|
|
{
|
|
for (i = 1; i <= 10; i ++)
|
|
{
|
|
snprintf(buffer, sizeof(buffer), "file%d.txt", i);
|
|
|
|
<a href='#cupsStartDocument'>cupsStartDocument</a>(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer,
|
|
CUPS_FORMAT_TEXT, i == 10);
|
|
|
|
snprintf(buffer, sizeof(buffer),
|
|
"File %d\n"
|
|
"\n"
|
|
"One fish,\n"
|
|
"Two fish,\n
|
|
"Red fish,\n
|
|
"Blue fish\n", i);
|
|
|
|
/* cupsWriteRequestData can be called as many times as needed */
|
|
<a href='#cupsWriteRequestData'>cupsWriteRequestData</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));
|
|
|
|
<a href='#cupsFinishDocument'>cupsFinishDocument</a>(CUPS_HTTP_DEFAULT, dest->name);
|
|
}
|
|
}
|
|
</pre>
|
|
|
|
<p>Once you have created a job, you can monitor its status using the
|
|
<a href='#cupsGetJobs'><code>cupsGetJobs</code></a> function, which returns
|
|
an array of <a href='#cups_job_t'><code>cups_job_t</code></a> structures.
|
|
Each contains the job ID (<code>id</code>), destination name
|
|
(<code>dest</code>), title (<code>title</code>), and other information
|
|
associated with the job. The job array is freed using the
|
|
<a href='#cupsFreeJobs'><code>cupsFreeJobs</code></a> function. The following
|
|
example monitors a specific job ID, showing the current job state once every
|
|
5 seconds until the job is completed:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dest;
|
|
int job_id;
|
|
int num_jobs;
|
|
<a href='#cups_job_t'>cups_job_t</a> *jobs;
|
|
int i;
|
|
ipp_jstate_t job_state = IPP_JOB_PENDING;
|
|
|
|
while (job_state < IPP_JOB_STOPPED)
|
|
{
|
|
/* Get my jobs (1) with any state (-1) */
|
|
num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&jobs, dest->name, 1, -1);
|
|
|
|
/* Loop to find my job */
|
|
job_state = IPP_JOB_COMPLETED;
|
|
|
|
for (i = 0; i < num_jobs; i ++)
|
|
if (jobs[i].id == job_id)
|
|
{
|
|
job_state = jobs[i].state;
|
|
break;
|
|
}
|
|
|
|
/* Free the job array */
|
|
<a href='#cupsFreeJobs'>cupsFreeJobs</a>(num_jobs, jobs);
|
|
|
|
/* Show the current state */
|
|
switch (job_state)
|
|
{
|
|
case IPP_JOB_PENDING :
|
|
printf("Job %d is pending.\n", job_id);
|
|
break;
|
|
case IPP_JOB_HELD :
|
|
printf("Job %d is held.\n", job_id);
|
|
break;
|
|
case IPP_JOB_PROCESSING :
|
|
printf("Job %d is processing.\n", job_id);
|
|
break;
|
|
case IPP_JOB_STOPPED :
|
|
printf("Job %d is stopped.\n", job_id);
|
|
break;
|
|
case IPP_JOB_CANCELED :
|
|
printf("Job %d is canceled.\n", job_id);
|
|
break;
|
|
case IPP_JOB_ABORTED :
|
|
printf("Job %d is aborted.\n", job_id);
|
|
break;
|
|
case IPP_JOB_COMPLETED :
|
|
printf("Job %d is completed.\n", job_id);
|
|
break;
|
|
}
|
|
|
|
/* Sleep if the job is not finished */
|
|
if (job_state < IPP_JOB_STOPPED)
|
|
sleep(5);
|
|
}
|
|
</pre>
|
|
|
|
<p>To cancel a job, use the
|
|
<a href='#cupsCancelJob'><code>cupsCancelJob</code></a> function with the
|
|
job ID:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
<a href='#cups_dest_t'>cups_dest_t</a> *dest;
|
|
int job_id;
|
|
|
|
<a href='#cupsCancelJob'>cupsCancelJob</a>(dest->name, job_id);
|
|
</pre>
|
|
|
|
<h3><a name='ERROR_HANDLING'>Error Handling</a></h3>
|
|
|
|
<p>If any of the CUPS API printing functions returns an error, the reason for
|
|
that error can be found by calling the
|
|
<a href='#cupsLastError'><code>cupsLastError</code></a> and
|
|
<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> functions.
|
|
<a href='#cupsLastError'><code>cupsLastError</code></a> returns the last IPP
|
|
error code
|
|
(<a href='api-httpipp.html#ipp_status_t'><code>ipp_status_t</code></a>)
|
|
that was encountered, while
|
|
<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> returns
|
|
a (localized) human-readable string that can be shown to the user. For example,
|
|
if any of the job creation functions returns a job ID of 0, you can use
|
|
<a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> to show
|
|
the reason why the job could not be created:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
int job_id;
|
|
|
|
if (job_id == 0)
|
|
puts(cupsLastErrorString());
|
|
</pre>
|
|
|
|
<h3><a name='PASSWORDS_AND_AUTHENTICATION'>Passwords and Authentication</a></h3>
|
|
|
|
<p>CUPS supports authentication of any request, including submission of print
|
|
jobs. The default mechanism for getting the username and password is to use the
|
|
login user and a password from the console.</p>
|
|
|
|
<p>To support other types of applications, in particular Graphical User
|
|
Interfaces ("GUIs"), the CUPS API provides functions to set the default
|
|
username and to register a callback function that returns a password string.</p>
|
|
|
|
<p>The <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a>
|
|
function is used to set a password callback in your program. Only one
|
|
function can be used at any time.</p>
|
|
|
|
<p>The <a href="#cupsSetUser"><code>cupsSetUser</code></a> function sets the
|
|
current username for authentication. This function can be called by your
|
|
password callback function to change the current username as needed.</p>
|
|
|
|
<p>The following example shows a simple password callback that gets a
|
|
username and password from the user:</p>
|
|
|
|
<pre class='example'>
|
|
#include <cups/cups.h>
|
|
|
|
const char *
|
|
my_password_cb(const char *prompt)
|
|
{
|
|
char user[65];
|
|
|
|
|
|
puts(prompt);
|
|
|
|
/* Get a username from the user */
|
|
printf("Username: ");
|
|
if (fgets(user, sizeof(user), stdin) == NULL)
|
|
return (NULL);
|
|
|
|
/* Strip the newline from the string and set the user */
|
|
user[strlen(user) - 1] = '\0';
|
|
|
|
<a href='#cupsSetUser'>cupsSetUser</a>(user);
|
|
|
|
/* Use getpass() to ask for the password... */
|
|
return (getpass("Password: "));
|
|
}
|
|
|
|
<a href='#cupsSetPasswordCB'>cupsSetPasswordCB</a>(my_password_cb);
|
|
</pre>
|
|
|
|
<p>Similarly, a GUI could display the prompt string in a window with input
|
|
fields for the username and password. The username should default to the
|
|
string returned by the <a href="#cupsUser"><code>cupsUser</code></a>
|
|
function.</p>
|
|
<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
|
|
<h3 class="function"><a name="cupsAddDest">cupsAddDest</a></h3>
|
|
<p class="description">Add a destination to the list of destinations.</p>
|
|
<p class="code">
|
|
int cupsAddDest (<br>
|
|
const char *name,<br>
|
|
const char *instance,<br>
|
|
int num_dests,<br>
|
|
<a href="#cups_dest_t">cups_dest_t</a> **dests<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>instance</dt>
|
|
<dd class="description">Instance name or <code>NULL</code> for none/primary</dd>
|
|
<dt>num_dests</dt>
|
|
<dd class="description">Number of destinations</dd>
|
|
<dt>dests</dt>
|
|
<dd class="description">Destinations</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">New number of destinations</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function cannot be used to add a new class or printer queue,
|
|
it only adds a new container of saved options for the named
|
|
destination or instance.<br>
|
|
<br>
|
|
If the named destination already exists, the destination list is
|
|
returned unchanged. Adding a new instance of a destination creates
|
|
a copy of that destination's options.<br>
|
|
<br>
|
|
Use the <a href="#cupsSaveDests"><code>cupsSaveDests</code></a> function to save the updated list of
|
|
destinations to the user's lpoptions file.</p>
|
|
<h3 class="function"><a name="cupsAddOption">cupsAddOption</a></h3>
|
|
<p class="description">Add an option to an option array.</p>
|
|
<p class="code">
|
|
int cupsAddOption (<br>
|
|
const char *name,<br>
|
|
const char *value,<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> **options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Name of option</dd>
|
|
<dt>value</dt>
|
|
<dd class="description">Value of option</dd>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Pointer to options</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Number of options</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">New option arrays can be initialized simply by passing 0 for the
|
|
"num_options" parameter.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3>
|
|
<p class="description">Create the Windows PPD file for a printer.</p>
|
|
<p class="code">
|
|
char *cupsAdminCreateWindowsPPD (<br>
|
|
http_t *http,<br>
|
|
const char *dest,<br>
|
|
char *buffer,<br>
|
|
int bufsize<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>dest</dt>
|
|
<dd class="description">Printer or class</dd>
|
|
<dt>buffer</dt>
|
|
<dd class="description">Filename buffer</dd>
|
|
<dt>bufsize</dt>
|
|
<dd class="description">Size of filename buffer</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">PPD file or NULL</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsAdminExportSamba">cupsAdminExportSamba</a></h3>
|
|
<p class="description">Export a printer to Samba.</p>
|
|
<p class="code">
|
|
int cupsAdminExportSamba (<br>
|
|
const char *dest,<br>
|
|
const char *ppd,<br>
|
|
const char *samba_server,<br>
|
|
const char *samba_user,<br>
|
|
const char *samba_password,<br>
|
|
FILE *logfile<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>dest</dt>
|
|
<dd class="description">Destination to export</dd>
|
|
<dt>ppd</dt>
|
|
<dd class="description">PPD file</dd>
|
|
<dt>samba_server</dt>
|
|
<dd class="description">Samba server</dd>
|
|
<dt>samba_user</dt>
|
|
<dd class="description">Samba username</dd>
|
|
<dt>samba_password</dt>
|
|
<dd class="description">Samba password</dd>
|
|
<dt>logfile</dt>
|
|
<dd class="description">Log file, if any</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">1 on success, 0 on failure</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3>
|
|
<p class="description">Get settings from the server.</p>
|
|
<p class="code">
|
|
int cupsAdminGetServerSettings (<br>
|
|
http_t *http,<br>
|
|
int *num_settings,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> **settings<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>num_settings</dt>
|
|
<dd class="description">Number of settings</dd>
|
|
<dt>settings</dt>
|
|
<dd class="description">Settings</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">1 on success, 0 on failure</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The returned settings should be freed with cupsFreeOptions() when
|
|
you are done with them.
|
|
|
|
</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3>
|
|
<p class="description">Set settings on the server.</p>
|
|
<p class="code">
|
|
int cupsAdminSetServerSettings (<br>
|
|
http_t *http,<br>
|
|
int num_settings,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> *settings<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>num_settings</dt>
|
|
<dd class="description">Number of settings</dd>
|
|
<dt>settings</dt>
|
|
<dd class="description">Settings</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">1 on success, 0 on failure</p>
|
|
<h3 class="function"><a name="cupsCancelJob">cupsCancelJob</a></h3>
|
|
<p class="description">Cancel a print job on the default server.</p>
|
|
<p class="code">
|
|
int cupsCancelJob (<br>
|
|
const char *name,<br>
|
|
int job_id<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Name of printer or class</dd>
|
|
<dt>job_id</dt>
|
|
<dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">1 on success, 0 on failure</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code>
|
|
to cancel the current job on the named destination.<br>
|
|
<br>
|
|
Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get
|
|
the cause of any failure.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsCancelJob2">cupsCancelJob2</a></h3>
|
|
<p class="description">Cancel or purge a print job.</p>
|
|
<p class="code">
|
|
ipp_status_t cupsCancelJob2 (<br>
|
|
http_t *http,<br>
|
|
const char *name,<br>
|
|
int job_id,<br>
|
|
int purge<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Name of printer or class</dd>
|
|
<dt>job_id</dt>
|
|
<dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd>
|
|
<dt>purge</dt>
|
|
<dd class="description">1 to purge, 0 to cancel</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">IPP status</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Canceled jobs remain in the job history while purged jobs are removed
|
|
from the job history.<br>
|
|
<br>
|
|
Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code>
|
|
to cancel the current job on the named destination.<br>
|
|
<br>
|
|
Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get
|
|
the cause of any failure.
|
|
|
|
</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsCreateJob">cupsCreateJob</a></h3>
|
|
<p class="description">Create an empty job for streaming.</p>
|
|
<p class="code">
|
|
int cupsCreateJob (<br>
|
|
http_t *http,<br>
|
|
const char *name,<br>
|
|
const char *title,<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> *options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>title</dt>
|
|
<dd class="description">Title of job</dd>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Options</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Job ID or 0 on error</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Use this function when you want to stream print data using the
|
|
<a href="#cupsStartDocument"><code>cupsStartDocument</code></a>, <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a>, and
|
|
<a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> functions. If you have one or more files to
|
|
print, use the <a href="#cupsPrintFile2"><code>cupsPrintFile2</code></a> or <a href="#cupsPrintFiles2"><code>cupsPrintFiles2</code></a> function
|
|
instead.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsEncryption">cupsEncryption</a></h3>
|
|
<p class="description">Get the default encryption settings.</p>
|
|
<p class="code">
|
|
http_encryption_t cupsEncryption (void);</p>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Encryption settings</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
|
|
environment variable, then the ~/.cups/client.conf file, and finally the
|
|
/etc/cups/client.conf file. If not set, the default is
|
|
<code>HTTP_ENCRYPT_IF_REQUESTED</code>.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsFinishDocument">cupsFinishDocument</a></h3>
|
|
<p class="description">Finish sending a document.</p>
|
|
<p class="code">
|
|
ipp_status_t cupsFinishDocument (<br>
|
|
http_t *http,<br>
|
|
const char *name<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Status of document submission</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsFreeDests">cupsFreeDests</a></h3>
|
|
<p class="description">Free the memory used by the list of destinations.</p>
|
|
<p class="code">
|
|
void cupsFreeDests (<br>
|
|
int num_dests,<br>
|
|
<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>num_dests</dt>
|
|
<dd class="description">Number of destinations</dd>
|
|
<dt>dests</dt>
|
|
<dd class="description">Destinations</dd>
|
|
</dl>
|
|
<h3 class="function"><a name="cupsFreeJobs">cupsFreeJobs</a></h3>
|
|
<p class="description">Free memory used by job data.</p>
|
|
<p class="code">
|
|
void cupsFreeJobs (<br>
|
|
int num_jobs,<br>
|
|
<a href="#cups_job_t">cups_job_t</a> *jobs<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>num_jobs</dt>
|
|
<dd class="description">Number of jobs</dd>
|
|
<dt>jobs</dt>
|
|
<dd class="description">Jobs</dd>
|
|
</dl>
|
|
<h3 class="function"><a name="cupsFreeOptions">cupsFreeOptions</a></h3>
|
|
<p class="description">Free all memory used by options.</p>
|
|
<p class="code">
|
|
void cupsFreeOptions (<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> *options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Pointer to options</dd>
|
|
</dl>
|
|
<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsGetClasses">cupsGetClasses</a></h3>
|
|
<p class="description">Get a list of printer classes from the default server.</p>
|
|
<p class="code">
|
|
int cupsGetClasses (<br>
|
|
char ***classes<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>classes</dt>
|
|
<dd class="description">Classes</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Number of classes</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsGetDefault">cupsGetDefault</a></h3>
|
|
<p class="description">Get the default printer or class for the default server.</p>
|
|
<p class="code">
|
|
const char *cupsGetDefault (void);</p>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Default printer or <code>NULL</code></p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function returns the default printer or class as defined by
|
|
the LPDEST or PRINTER environment variables. If these environment
|
|
variables are not set, the server default destination is returned.
|
|
Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a>
|
|
functions to get the user-defined default printer, as this function does
|
|
not support the lpoptions-defined default printer.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetDefault2">cupsGetDefault2</a></h3>
|
|
<p class="description">Get the default printer or class for the specified server.</p>
|
|
<p class="code">
|
|
const char *cupsGetDefault2 (<br>
|
|
http_t *http<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Default printer or <code>NULL</code></p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function returns the default printer or class as defined by
|
|
the LPDEST or PRINTER environment variables. If these environment
|
|
variables are not set, the server default destination is returned.
|
|
Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a>
|
|
functions to get the user-defined default printer, as this function does
|
|
not support the lpoptions-defined default printer.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsGetDest">cupsGetDest</a></h3>
|
|
<p class="description">Get the named destination from the list.</p>
|
|
<p class="code">
|
|
<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest (<br>
|
|
const char *name,<br>
|
|
const char *instance,<br>
|
|
int num_dests,<br>
|
|
<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name or <code>NULL</code> for the default destination</dd>
|
|
<dt>instance</dt>
|
|
<dd class="description">Instance name or <code>NULL</code></dd>
|
|
<dt>num_dests</dt>
|
|
<dd class="description">Number of destinations</dd>
|
|
<dt>dests</dt>
|
|
<dd class="description">Destinations</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Destination pointer or <code>NULL</code></p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a
|
|
list of supported destinations for the current user.</p>
|
|
<h3 class="function"><a name="cupsGetDests">cupsGetDests</a></h3>
|
|
<p class="description">Get the list of destinations from the default server.</p>
|
|
<p class="code">
|
|
int cupsGetDests (<br>
|
|
<a href="#cups_dest_t">cups_dest_t</a> **dests<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>dests</dt>
|
|
<dd class="description">Destinations</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Number of destinations</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
|
|
printer-info, printer-is-accepting-jobs, printer-is-shared,
|
|
printer-make-and-model, printer-state, printer-state-change-time,
|
|
printer-state-reasons, and printer-type attributes as options. CUPS 1.4
|
|
adds the marker-change-time, marker-colors, marker-high-levels,
|
|
marker-levels, marker-low-levels, marker-message, marker-names,
|
|
marker-types, and printer-commands attributes as well.<br>
|
|
<br>
|
|
Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
|
|
the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetDests2">cupsGetDests2</a></h3>
|
|
<p class="description">Get the list of destinations from the specified server.</p>
|
|
<p class="code">
|
|
int cupsGetDests2 (<br>
|
|
http_t *http,<br>
|
|
<a href="#cups_dest_t">cups_dest_t</a> **dests<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>dests</dt>
|
|
<dd class="description">Destinations</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Number of destinations</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
|
|
printer-info, printer-is-accepting-jobs, printer-is-shared,
|
|
printer-make-and-model, printer-state, printer-state-change-time,
|
|
printer-state-reasons, and printer-type attributes as options. CUPS 1.4
|
|
adds the marker-change-time, marker-colors, marker-high-levels,
|
|
marker-levels, marker-low-levels, marker-message, marker-names,
|
|
marker-types, and printer-commands attributes as well.<br>
|
|
<br>
|
|
Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
|
|
the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsGetJobs">cupsGetJobs</a></h3>
|
|
<p class="description">Get the jobs from the default server.</p>
|
|
<p class="code">
|
|
int cupsGetJobs (<br>
|
|
<a href="#cups_job_t">cups_job_t</a> **jobs,<br>
|
|
const char *name,<br>
|
|
int myjobs,<br>
|
|
int whichjobs<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>jobs</dt>
|
|
<dd class="description">Job data</dd>
|
|
<dt>name</dt>
|
|
<dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd>
|
|
<dt>myjobs</dt>
|
|
<dd class="description">0 = all users, 1 = mine</dd>
|
|
<dt>whichjobs</dt>
|
|
<dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Number of jobs</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
|
|
of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
|
|
pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
|
|
jobs that are stopped, canceled, aborted, or completed.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3>
|
|
<p class="description">Get the jobs from the specified server.</p>
|
|
<p class="code">
|
|
int cupsGetJobs2 (<br>
|
|
http_t *http,<br>
|
|
<a href="#cups_job_t">cups_job_t</a> **jobs,<br>
|
|
const char *name,<br>
|
|
int myjobs,<br>
|
|
int whichjobs<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>jobs</dt>
|
|
<dd class="description">Job data</dd>
|
|
<dt>name</dt>
|
|
<dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd>
|
|
<dt>myjobs</dt>
|
|
<dd class="description">0 = all users, 1 = mine</dd>
|
|
<dt>whichjobs</dt>
|
|
<dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Number of jobs</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
|
|
of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
|
|
pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
|
|
jobs that are stopped, canceled, aborted, or completed.
|
|
|
|
</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3>
|
|
<p class="description">Get options for the named destination.</p>
|
|
<p class="code">
|
|
<a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br>
|
|
http_t *http,<br>
|
|
const char *name,<br>
|
|
const char *instance<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name or <code>NULL</code> for the default destination</dd>
|
|
<dt>instance</dt>
|
|
<dd class="description">Instance name or <code>NULL</code></dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Destination or <code>NULL</code></p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function is optimized for retrieving a single destination and should
|
|
be used instead of <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you either
|
|
know the name of the destination or want to print to the default destination.
|
|
If <code>NULL</code> is returned, the destination does not exist or there is no
|
|
default destination.<br>
|
|
<br>
|
|
If "http" is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print
|
|
server will be used.<br>
|
|
<br>
|
|
If "name" is <code>NULL</code>, the default printer for the current user will be
|
|
returned.<br>
|
|
<br>
|
|
The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a
|
|
"num_dests" value of 1.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsGetOption">cupsGetOption</a></h3>
|
|
<p class="description">Get an option value.</p>
|
|
<p class="code">
|
|
const char *cupsGetOption (<br>
|
|
const char *name,<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> *options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Name of option</dd>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Options</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Option value or <code>NULL</code></p>
|
|
<h3 class="function"><a name="cupsGetPPD">cupsGetPPD</a></h3>
|
|
<p class="description">Get the PPD file for a printer on the default server.</p>
|
|
<p class="code">
|
|
const char *cupsGetPPD (<br>
|
|
const char *name<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Filename for PPD file</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">For classes, <code>cupsGetPPD</code> returns the PPD file for the first printer
|
|
in the class.<br>
|
|
<br>
|
|
The returned filename is stored in a static buffer and is overwritten with
|
|
each call to <code>cupsGetPPD</code> or <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetPPD2">cupsGetPPD2</a></h3>
|
|
<p class="description">Get the PPD file for a printer from the specified server.</p>
|
|
<p class="code">
|
|
const char *cupsGetPPD2 (<br>
|
|
http_t *http,<br>
|
|
const char *name<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Filename for PPD file</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">For classes, <code>cupsGetPPD2</code> returns the PPD file for the first printer
|
|
in the class.<br>
|
|
<br>
|
|
The returned filename is stored in a static buffer and is overwritten with
|
|
each call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a> or <code>cupsGetPPD2</code>.
|
|
|
|
</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3>
|
|
<p class="description">Get the PPD file for a printer on the specified
|
|
server if it has changed.</p>
|
|
<p class="code">
|
|
http_status_t cupsGetPPD3 (<br>
|
|
http_t *http,<br>
|
|
const char *name,<br>
|
|
time_t *modtime,<br>
|
|
char *buffer,<br>
|
|
size_t bufsize<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>modtime</dt>
|
|
<dd class="description">Modification time</dd>
|
|
<dt>buffer</dt>
|
|
<dd class="description">Filename buffer</dd>
|
|
<dt>bufsize</dt>
|
|
<dd class="description">Size of filename buffer</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">HTTP status</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The "modtime" parameter contains the modification time of any
|
|
locally-cached content and is updated with the time from the PPD file on
|
|
the server.<br>
|
|
<br>
|
|
The "buffer" parameter contains the local PPD filename. If it contains
|
|
the empty string, a new temporary file is created, otherwise the existing
|
|
file will be overwritten as needed.<br>
|
|
<br>
|
|
On success, <code>HTTP_OK</code> is returned for a new PPD file and
|
|
<code>HTTP_NOT_MODIFIED</code> if the existing PPD file is up-to-date. Any other
|
|
status is an error.<br>
|
|
<br>
|
|
For classes, <code>cupsGetPPD3</code> returns the PPD file for the first printer
|
|
in the class.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsGetPassword">cupsGetPassword</a></h3>
|
|
<p class="description">Get a password from the user.</p>
|
|
<p class="code">
|
|
const char *cupsGetPassword (<br>
|
|
const char *prompt<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>prompt</dt>
|
|
<dd class="description">Prompt string</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Password</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
|
|
user does not provide a password.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetPassword2">cupsGetPassword2</a></h3>
|
|
<p class="description">Get a password from the user using the advanced
|
|
callback.</p>
|
|
<p class="code">
|
|
const char *cupsGetPassword2 (<br>
|
|
const char *prompt,<br>
|
|
http_t *http,<br>
|
|
const char *method,<br>
|
|
const char *resource<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>prompt</dt>
|
|
<dd class="description">Prompt string</dd>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>method</dt>
|
|
<dd class="description">Request method ("GET", "POST", "PUT")</dd>
|
|
<dt>resource</dt>
|
|
<dd class="description">Resource path</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Password</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
|
|
user does not provide a password.
|
|
|
|
</p>
|
|
<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsGetPrinters">cupsGetPrinters</a></h3>
|
|
<p class="description">Get a list of printers from the default server.</p>
|
|
<p class="code">
|
|
int cupsGetPrinters (<br>
|
|
char ***printers<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>printers</dt>
|
|
<dd class="description">Printers</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Number of printers</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
|
|
|
|
</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3>
|
|
<p class="description">Get an available PPD file from the server.</p>
|
|
<p class="code">
|
|
char *cupsGetServerPPD (<br>
|
|
http_t *http,<br>
|
|
const char *name<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Name of PPD file ("ppd-name")</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Name of PPD file or <code>NULL</code> on error</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function returns the named PPD file from the server. The
|
|
list of available PPDs is provided by the IPP <code>CUPS_GET_PPDS</code>
|
|
operation.<br>
|
|
<br>
|
|
You must remove (unlink) the PPD file when you are finished with
|
|
it. The PPD filename is stored in a static location that will be
|
|
overwritten on the next call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a>, <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>,
|
|
or <a href="#cupsGetServerPPD"><code>cupsGetServerPPD</code></a>.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsLangDefault">cupsLangDefault</a></h3>
|
|
<p class="description">Return the default language.</p>
|
|
<p class="code">
|
|
cups_lang_t *cupsLangDefault (void);</p>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Language data</p>
|
|
<h3 class="function"><a name="cupsLangEncoding">cupsLangEncoding</a></h3>
|
|
<p class="description">Return the character encoding (us-ascii, etc.)
|
|
for the given language.</p>
|
|
<p class="code">
|
|
const char *cupsLangEncoding (<br>
|
|
cups_lang_t *lang<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>lang</dt>
|
|
<dd class="description">Language data</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Character encoding</p>
|
|
<h3 class="function"><a name="cupsLangFlush">cupsLangFlush</a></h3>
|
|
<p class="description">Flush all language data out of the cache.</p>
|
|
<p class="code">
|
|
void cupsLangFlush (void);</p>
|
|
<h3 class="function"><a name="cupsLangFree">cupsLangFree</a></h3>
|
|
<p class="description">Free language data.</p>
|
|
<p class="code">
|
|
void cupsLangFree (<br>
|
|
cups_lang_t *lang<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>lang</dt>
|
|
<dd class="description">Language to free</dd>
|
|
</dl>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This does not actually free anything; use <a href="#cupsLangFlush"><code>cupsLangFlush</code></a> for that.</p>
|
|
<h3 class="function"><a name="cupsLangGet">cupsLangGet</a></h3>
|
|
<p class="description">Get a language.</p>
|
|
<p class="code">
|
|
cups_lang_t *cupsLangGet (<br>
|
|
const char *language<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>language</dt>
|
|
<dd class="description">Language or locale</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Language data</p>
|
|
<h3 class="function"><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"> CUPS 1.2/Mac OS X 10.5 </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"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3>
|
|
<p class="description">Return the subject for the given notification message.</p>
|
|
<p class="code">
|
|
char *cupsNotifySubject (<br>
|
|
cups_lang_t *lang,<br>
|
|
ipp_t *event<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>lang</dt>
|
|
<dd class="description">Language data</dd>
|
|
<dt>event</dt>
|
|
<dd class="description">Event data</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Subject string or <code>NULL</code></p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The returned string must be freed by the caller using <code>free</code>.
|
|
|
|
</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsNotifyText">cupsNotifyText</a></h3>
|
|
<p class="description">Return the text for the given notification message.</p>
|
|
<p class="code">
|
|
char *cupsNotifyText (<br>
|
|
cups_lang_t *lang,<br>
|
|
ipp_t *event<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>lang</dt>
|
|
<dd class="description">Language data</dd>
|
|
<dt>event</dt>
|
|
<dd class="description">Event data</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Message text or <code>NULL</code></p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The returned string must be freed by the caller using <code>free</code>.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsParseOptions">cupsParseOptions</a></h3>
|
|
<p class="description">Parse options from a command-line argument.</p>
|
|
<p class="code">
|
|
int cupsParseOptions (<br>
|
|
const char *arg,<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> **options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>arg</dt>
|
|
<dd class="description">Argument to parse</dd>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Options found</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Number of options found</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function converts space-delimited name/value pairs according
|
|
to the PAPI text option ABNF specification. Collection values
|
|
("name={a=... b=... c=...}") are stored with the curley brackets
|
|
intact - use <code>cupsParseOptions</code> on the value to extract the
|
|
collection attributes.</p>
|
|
<h3 class="function"><a name="cupsPrintFile">cupsPrintFile</a></h3>
|
|
<p class="description">Print a file to a printer or class on the default server.</p>
|
|
<p class="code">
|
|
int cupsPrintFile (<br>
|
|
const char *name,<br>
|
|
const char *filename,<br>
|
|
const char *title,<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> *options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>filename</dt>
|
|
<dd class="description">File to print</dd>
|
|
<dt>title</dt>
|
|
<dd class="description">Title of job</dd>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Options</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Job ID or 0 on error</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsPrintFile2">cupsPrintFile2</a></h3>
|
|
<p class="description">Print a file to a printer or class on the specified
|
|
server.</p>
|
|
<p class="code">
|
|
int cupsPrintFile2 (<br>
|
|
http_t *http,<br>
|
|
const char *name,<br>
|
|
const char *filename,<br>
|
|
const char *title,<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> *options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server</dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>filename</dt>
|
|
<dd class="description">File to print</dd>
|
|
<dt>title</dt>
|
|
<dd class="description">Title of job</dd>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Options</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Job ID or 0 on error</p>
|
|
<h3 class="function"><a name="cupsPrintFiles">cupsPrintFiles</a></h3>
|
|
<p class="description">Print one or more files to a printer or class on the
|
|
default server.</p>
|
|
<p class="code">
|
|
int cupsPrintFiles (<br>
|
|
const char *name,<br>
|
|
int num_files,<br>
|
|
const char **files,<br>
|
|
const char *title,<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> *options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>num_files</dt>
|
|
<dd class="description">Number of files</dd>
|
|
<dt>files</dt>
|
|
<dd class="description">File(s) to print</dd>
|
|
<dt>title</dt>
|
|
<dd class="description">Title of job</dd>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Options</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Job ID or 0 on error</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3>
|
|
<p class="description">Print one or more files to a printer or class on the
|
|
specified server.</p>
|
|
<p class="code">
|
|
int cupsPrintFiles2 (<br>
|
|
http_t *http,<br>
|
|
const char *name,<br>
|
|
int num_files,<br>
|
|
const char **files,<br>
|
|
const char *title,<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> *options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>num_files</dt>
|
|
<dd class="description">Number of files</dd>
|
|
<dt>files</dt>
|
|
<dd class="description">File(s) to print</dd>
|
|
<dt>title</dt>
|
|
<dd class="description">Title of job</dd>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Options</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Job ID or 0 on error</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3>
|
|
<p class="description">Remove a destination from the destination list.</p>
|
|
<p class="code">
|
|
int cupsRemoveDest (<br>
|
|
const char *name,<br>
|
|
const char *instance,<br>
|
|
int num_dests,<br>
|
|
<a href="#cups_dest_t">cups_dest_t</a> **dests<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>instance</dt>
|
|
<dd class="description">Instance name or <code>NULL</code></dd>
|
|
<dt>num_dests</dt>
|
|
<dd class="description">Number of destinations</dd>
|
|
<dt>dests</dt>
|
|
<dd class="description">Destinations</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">New number of destinations</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Removing a destination/instance does not delete the class or printer
|
|
queue, merely the lpoptions for that destination/instance. Use the
|
|
<a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new
|
|
options for the user.
|
|
|
|
</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3>
|
|
<p class="description">Remove an option from an option array.</p>
|
|
<p class="code">
|
|
int cupsRemoveOption (<br>
|
|
const char *name,<br>
|
|
int num_options,<br>
|
|
<a href="#cups_option_t">cups_option_t</a> **options<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Option name</dd>
|
|
<dt>num_options</dt>
|
|
<dd class="description">Current number of options</dd>
|
|
<dt>options</dt>
|
|
<dd class="description">Options</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">New number of options</p>
|
|
<h3 class="function"><a name="cupsServer">cupsServer</a></h3>
|
|
<p class="description">Return the hostname/address of the default server.</p>
|
|
<p class="code">
|
|
const char *cupsServer (void);</p>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Server name</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The returned value can be a fully-qualified hostname, a numeric
|
|
IPv4 or IPv6 address, or a domain socket pathname.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
|
|
<p class="description">Set the default destination.</p>
|
|
<p class="code">
|
|
void cupsSetDefaultDest (<br>
|
|
const char *name,<br>
|
|
const char *instance,<br>
|
|
int num_dests,<br>
|
|
<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>instance</dt>
|
|
<dd class="description">Instance name or <code>NULL</code></dd>
|
|
<dt>num_dests</dt>
|
|
<dd class="description">Number of destinations</dd>
|
|
<dt>dests</dt>
|
|
<dd class="description">Destinations</dd>
|
|
</dl>
|
|
<h3 class="function"><a name="cupsSetDests">cupsSetDests</a></h3>
|
|
<p class="description">Save the list of destinations for the default server.</p>
|
|
<p class="code">
|
|
void cupsSetDests (<br>
|
|
int num_dests,<br>
|
|
<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>num_dests</dt>
|
|
<dd class="description">Number of destinations</dd>
|
|
<dt>dests</dt>
|
|
<dd class="description">Destinations</dd>
|
|
</dl>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
|
|
as root and ~/.cups/lpoptions when run as a normal user.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsSetDests2">cupsSetDests2</a></h3>
|
|
<p class="description">Save the list of destinations for the specified server.</p>
|
|
<p class="code">
|
|
int cupsSetDests2 (<br>
|
|
http_t *http,<br>
|
|
int num_dests,<br>
|
|
<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>num_dests</dt>
|
|
<dd class="description">Number of destinations</dd>
|
|
<dt>dests</dt>
|
|
<dd class="description">Destinations</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">0 on success, -1 on error</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
|
|
as root and ~/.cups/lpoptions when run as a normal user.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsSetEncryption">cupsSetEncryption</a></h3>
|
|
<p class="description">Set the encryption preference.</p>
|
|
<p class="code">
|
|
void cupsSetEncryption (<br>
|
|
http_encryption_t e<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>e</dt>
|
|
<dd class="description">New encryption preference</dd>
|
|
</dl>
|
|
<h3 class="function"><a name="cupsSetPasswordCB">cupsSetPasswordCB</a></h3>
|
|
<p class="description">Set the password callback for CUPS.</p>
|
|
<p class="code">
|
|
void cupsSetPasswordCB (<br>
|
|
<a href="#cups_password_cb_t">cups_password_cb_t</a> cb<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>cb</dt>
|
|
<dd class="description">Callback function</dd>
|
|
</dl>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3>
|
|
<p class="description">Set the advanced password callback for CUPS.</p>
|
|
<p class="code">
|
|
void cupsSetPasswordCB2 (<br>
|
|
<a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb,<br>
|
|
void *user_data<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>cb</dt>
|
|
<dd class="description">Callback function</dd>
|
|
<dt>user_data</dt>
|
|
<dd class="description">User data pointer</dd>
|
|
</dl>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsSetServer">cupsSetServer</a></h3>
|
|
<p class="description">Set the default server name.</p>
|
|
<p class="code">
|
|
void cupsSetServer (<br>
|
|
const char *server<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>server</dt>
|
|
<dd class="description">Server name</dd>
|
|
</dl>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The "server" string can be a fully-qualified hostname, a numeric
|
|
IPv4 or IPv6 address, or a domain socket pathname. Pass <code>NULL</code> to
|
|
restore the default server name.</p>
|
|
<h3 class="function"><a name="cupsSetUser">cupsSetUser</a></h3>
|
|
<p class="description">Set the default user name.</p>
|
|
<p class="code">
|
|
void cupsSetUser (<br>
|
|
const char *user<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>user</dt>
|
|
<dd class="description">User name</dd>
|
|
</dl>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Pass <code>NULL</code> to restore the default user name.</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsStartDocument">cupsStartDocument</a></h3>
|
|
<p class="description">Add a document to a job created with cupsCreateJob().</p>
|
|
<p class="code">
|
|
http_status_t cupsStartDocument (<br>
|
|
http_t *http,<br>
|
|
const char *name,<br>
|
|
int job_id,<br>
|
|
const char *docname,<br>
|
|
const char *format,<br>
|
|
int last_document<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>http</dt>
|
|
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
|
|
<dt>name</dt>
|
|
<dd class="description">Destination name</dd>
|
|
<dt>job_id</dt>
|
|
<dd class="description">Job ID from <a href="#cupsCreateJob"><code>cupsCreateJob</code></a></dd>
|
|
<dt>docname</dt>
|
|
<dd class="description">Name of document</dd>
|
|
<dt>format</dt>
|
|
<dd class="description">MIME type or <code>CUPS_FORMAT_foo</code></dd>
|
|
<dt>last_document</dt>
|
|
<dd class="description">1 for last document in job, 0 otherwise</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">HTTP status of request</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write data for the document and
|
|
<a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> to finish the document and get the submission status.<br>
|
|
<br>
|
|
The MIME type constants <code>CUPS_FORMAT_AUTO</code>, <code>CUPS_FORMAT_PDF</code>,
|
|
<code>CUPS_FORMAT_POSTSCRIPT</code>, <code>CUPS_FORMAT_RAW</code>, and
|
|
<code>CUPS_FORMAT_TEXT</code> are provided for the "format" argument, although
|
|
any supported MIME type string can be supplied.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsTempFd">cupsTempFd</a></h3>
|
|
<p class="description">Creates a temporary file.</p>
|
|
<p class="code">
|
|
int cupsTempFd (<br>
|
|
char *filename,<br>
|
|
int len<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>filename</dt>
|
|
<dd class="description">Pointer to buffer</dd>
|
|
<dt>len</dt>
|
|
<dd class="description">Size of buffer</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">New file descriptor or -1 on error</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The temporary filename is returned in the filename buffer.
|
|
The temporary file is opened for reading and writing.</p>
|
|
<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsTempFile">cupsTempFile</a></h3>
|
|
<p class="description">Generates a temporary filename.</p>
|
|
<p class="code">
|
|
char *cupsTempFile (<br>
|
|
char *filename,<br>
|
|
int len<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>filename</dt>
|
|
<dd class="description">Pointer to buffer</dd>
|
|
<dt>len</dt>
|
|
<dd class="description">Size of buffer</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">Filename or <code>NULL</code> on error</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The temporary filename is returned in the filename buffer.
|
|
This function is deprecated - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or
|
|
<a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead.
|
|
|
|
</p>
|
|
<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsTempFile2">cupsTempFile2</a></h3>
|
|
<p class="description">Creates a temporary CUPS file.</p>
|
|
<p class="code">
|
|
cups_file_t *cupsTempFile2 (<br>
|
|
char *filename,<br>
|
|
int len<br>
|
|
);</p>
|
|
<h4 class="parameters">Parameters</h4>
|
|
<dl>
|
|
<dt>filename</dt>
|
|
<dd class="description">Pointer to buffer</dd>
|
|
<dt>len</dt>
|
|
<dd class="description">Size of buffer</dd>
|
|
</dl>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">CUPS file or <code>NULL</code> on error</p>
|
|
<h4 class="discussion">Discussion</h4>
|
|
<p class="discussion">The temporary filename is returned in the filename buffer.
|
|
The temporary file is opened for writing.
|
|
|
|
</p>
|
|
<h3 class="function"><a name="cupsUser">cupsUser</a></h3>
|
|
<p class="description">Return the current user's name.</p>
|
|
<p class="code">
|
|
const char *cupsUser (void);</p>
|
|
<h4 class="returnvalue">Return Value</h4>
|
|
<p class="description">User name</p>
|
|
<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"> CUPS 1.4/Mac OS X 10.6 </span><a name="cups_device_cb_t">cups_device_cb_t</a></h3>
|
|
<p class="description">Device callback </p>
|
|
<p class="code">
|
|
typedef void (*cups_device_cb_t)(const char *device_class, const char *device_id, const char *device_info, const char *device_make_and_model, const char *device_uri, const char *device_location, void *user_data);
|
|
</p>
|
|
<h3 class="typedef"><a name="cups_job_t">cups_job_t</a></h3>
|
|
<p class="description">Job</p>
|
|
<p class="code">
|
|
typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t;
|
|
</p>
|
|
<h3 class="typedef"><a name="cups_option_t">cups_option_t</a></h3>
|
|
<p class="description">Printer Options</p>
|
|
<p class="code">
|
|
typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t;
|
|
</p>
|
|
<h3 class="typedef"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cups_password_cb2_t">cups_password_cb2_t</a></h3>
|
|
<p class="description">New password callback </p>
|
|
<p class="code">
|
|
typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data);
|
|
</p>
|
|
<h3 class="typedef"><a name="cups_password_cb_t">cups_password_cb_t</a></h3>
|
|
<p class="description">Password callback</p>
|
|
<p class="code">
|
|
typedef const char *(*cups_password_cb_t)(const char *prompt);
|
|
</p>
|
|
<h3 class="typedef"><a name="cups_ptype_t">cups_ptype_t</a></h3>
|
|
<p class="description">Printer type/capability bits</p>
|
|
<p class="code">
|
|
typedef unsigned cups_ptype_t;
|
|
</p>
|
|
<h2 class="title"><a name="STRUCTURES">Structures</a></h2>
|
|
<h3 class="struct"><a name="cups_dest_s">cups_dest_s</a></h3>
|
|
<p class="description">Destination</p>
|
|
<p class="code">struct cups_dest_s {<br>
|
|
char *name, *instance;<br>
|
|
int is_default;<br>
|
|
int num_options;<br>
|
|
<a href="#cups_option_t">cups_option_t</a> *options;<br>
|
|
};</p>
|
|
<h4 class="members">Members</h4>
|
|
<dl>
|
|
<dt>instance </dt>
|
|
<dd class="description">Local instance name or NULL</dd>
|
|
<dt>is_default </dt>
|
|
<dd class="description">Is this printer the default?</dd>
|
|
<dt>num_options </dt>
|
|
<dd class="description">Number of options</dd>
|
|
<dt>options </dt>
|
|
<dd class="description">Options</dd>
|
|
</dl>
|
|
<h3 class="struct"><a name="cups_job_s">cups_job_s</a></h3>
|
|
<p class="description">Job</p>
|
|
<p class="code">struct cups_job_s {<br>
|
|
time_t completed_time;<br>
|
|
time_t creation_time;<br>
|
|
char *dest;<br>
|
|
char *format;<br>
|
|
int id;<br>
|
|
int priority;<br>
|
|
time_t processing_time;<br>
|
|
int size;<br>
|
|
ipp_jstate_t state;<br>
|
|
char *title;<br>
|
|
char *user;<br>
|
|
};</p>
|
|
<h4 class="members">Members</h4>
|
|
<dl>
|
|
<dt>completed_time </dt>
|
|
<dd class="description">Time the job was completed</dd>
|
|
<dt>creation_time </dt>
|
|
<dd class="description">Time the job was created</dd>
|
|
<dt>dest </dt>
|
|
<dd class="description">Printer or class name</dd>
|
|
<dt>format </dt>
|
|
<dd class="description">Document format</dd>
|
|
<dt>id </dt>
|
|
<dd class="description">The job ID</dd>
|
|
<dt>priority </dt>
|
|
<dd class="description">Priority (1-100)</dd>
|
|
<dt>processing_time </dt>
|
|
<dd class="description">Time the job was processed</dd>
|
|
<dt>size </dt>
|
|
<dd class="description">Size in kilobytes</dd>
|
|
<dt>state </dt>
|
|
<dd class="description">Job state</dd>
|
|
<dt>title </dt>
|
|
<dd class="description">Title/job name</dd>
|
|
<dt>user </dt>
|
|
<dd class="description">User the submitted the job</dd>
|
|
</dl>
|
|
<h3 class="struct"><a name="cups_option_s">cups_option_s</a></h3>
|
|
<p class="description">Printer Options</p>
|
|
<p class="code">struct cups_option_s {<br>
|
|
char *name;<br>
|
|
char *value;<br>
|
|
};</p>
|
|
<h4 class="members">Members</h4>
|
|
<dl>
|
|
<dt>name </dt>
|
|
<dd class="description">Name of option</dd>
|
|
<dt>value </dt>
|
|
<dd class="description">Value of option</dd>
|
|
</dl>
|
|
<h2 class="title"><a name="ENUMERATIONS">Constants</a></h2>
|
|
<h3 class="enumeration"><a name="cups_ptype_e">cups_ptype_e</a></h3>
|
|
<p class="description">Printer type/capability bit constants</p>
|
|
<h4 class="constants">Constants</h4>
|
|
<dl>
|
|
<dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
|
|
<dd class="description">Printer requires authentication </dd>
|
|
<dt>CUPS_PRINTER_BIND </dt>
|
|
<dd class="description">Can bind output</dd>
|
|
<dt>CUPS_PRINTER_BW </dt>
|
|
<dd class="description">Can do B&W printing</dd>
|
|
<dt>CUPS_PRINTER_CLASS </dt>
|
|
<dd class="description">Printer class</dd>
|
|
<dt>CUPS_PRINTER_COLLATE </dt>
|
|
<dd class="description">Can collage copies</dd>
|
|
<dt>CUPS_PRINTER_COLOR </dt>
|
|
<dd class="description">Can do color printing</dd>
|
|
<dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
|
|
<dd class="description">Printer supports maintenance commands </dd>
|
|
<dt>CUPS_PRINTER_COPIES </dt>
|
|
<dd class="description">Can do copies</dd>
|
|
<dt>CUPS_PRINTER_COVER </dt>
|
|
<dd class="description">Can cover output</dd>
|
|
<dt>CUPS_PRINTER_DEFAULT </dt>
|
|
<dd class="description">Default printer on network</dd>
|
|
<dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
|
|
<dd class="description">Delete printer </dd>
|
|
<dt>CUPS_PRINTER_DISCOVERED <span class="info"> CUPS 1.3/Mac OS X 10.5 </span></dt>
|
|
<dd class="description">Printer was automatically discovered and added </dd>
|
|
<dt>CUPS_PRINTER_DUPLEX </dt>
|
|
<dd class="description">Can do duplexing</dd>
|
|
<dt>CUPS_PRINTER_FAX </dt>
|
|
<dd class="description">Fax queue</dd>
|
|
<dt>CUPS_PRINTER_IMPLICIT </dt>
|
|
<dd class="description">Implicit class</dd>
|
|
<dt>CUPS_PRINTER_LARGE </dt>
|
|
<dd class="description">Can do D/E/A1/A0</dd>
|
|
<dt>CUPS_PRINTER_LOCAL </dt>
|
|
<dd class="description">Local printer or class</dd>
|
|
<dt>CUPS_PRINTER_MEDIUM </dt>
|
|
<dd class="description">Can do Tabloid/B/C/A3/A2</dd>
|
|
<dt>CUPS_PRINTER_MFP <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt>
|
|
<dd class="description">Printer with scanning capabilities </dd>
|
|
<dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
|
|
<dd class="description">Printer is not shared </dd>
|
|
<dt>CUPS_PRINTER_PUNCH </dt>
|
|
<dd class="description">Can punch output</dd>
|
|
<dt>CUPS_PRINTER_REJECTING </dt>
|
|
<dd class="description">Printer is rejecting jobs</dd>
|
|
<dt>CUPS_PRINTER_REMOTE </dt>
|
|
<dd class="description">Remote printer or class</dd>
|
|
<dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt>
|
|
<dd class="description">Scanner-only device </dd>
|
|
<dt>CUPS_PRINTER_SMALL </dt>
|
|
<dd class="description">Can do Letter/Legal/A4</dd>
|
|
<dt>CUPS_PRINTER_SORT </dt>
|
|
<dd class="description">Can sort output</dd>
|
|
<dt>CUPS_PRINTER_STAPLE </dt>
|
|
<dd class="description">Can staple output</dd>
|
|
<dt>CUPS_PRINTER_VARIABLE </dt>
|
|
<dd class="description">Can do variable sizes</dd>
|
|
</dl>
|
|
</div>
|
|
</body>
|
|
</html>
|