<head>
<title>CUPS API</title>
<meta name='keywords' content='Programming'>
- <meta name='creator' content='Mini-XML v2.3'>
+ <meta name='creator' content='Mini-XML v2.4'>
<style type='text/css'><!--
h1, h2, h3, p { font-family: sans-serif; text-align: justify; }
tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }
</head>
<body>
<!--
- "$Id$"
+ "$Id: api-cups.shtml 6649 2007-07-11 21:46:42Z mike $"
CUPS API introduction for the Common UNIX Printing System (CUPS).
- Copyright 1997-2006 by Easy Software Products.
+ Copyright 2007 by Apple Inc.
+ Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
- property of Easy Software Products and are protected by Federal
- copyright law. Distribution and use rights are outlined in the file
- "LICENSE.txt" which should have been included with this file. If this
- file is missing or damaged please contact Easy Software Products
- at:
-
- Attn: CUPS Licensing Information
- Easy Software Products
- 44141 Airport View Drive, Suite 204
- Hollywood, Maryland 20636 USA
-
- Voice: (301) 373-9600
- EMail: cups-info@cups.org
- WWW: http://www.cups.org
+ property of Apple Inc. and are protected by Federal copyright
+ law. Distribution and use rights are outlined in the file "LICENSE.txt"
+ which should have been included with this file. If this file is
+ file is missing or damaged, see the license at "http://www.cups.org/".
-->
<h2 class='title'>Introduction</h2>
<!-- NEW PAGE -->
<h3 class='title'><a name='cups_ptype_e'>cups_ptype_e</a></h3>
<h4>Description</h4>
-<p>Not a typedef'd enum so we can OR</p>
+<p>Not a typedef'd enum so we can OR
<h4>Values</h4>
-<div class='table'><table align='center' border='1' width='80%'>
+<div class='table'><table align='center' border='1' width='80%' summary='Values'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
-<tr><td><tt>CUPS_PRINTER_AUTHENTICATED</tt> <span class='info'> CUPS 1.2 </span></td><td>Printer requires authentication </td></tr>
-<tr><td><tt>CUPS_PRINTER_BIND</tt> </td><td>Can bind output</td></tr>
-<tr><td><tt>CUPS_PRINTER_BW</tt> </td><td>Can do B&W printing</td></tr>
-<tr><td><tt>CUPS_PRINTER_CLASS</tt> </td><td>Printer class</td></tr>
-<tr><td><tt>CUPS_PRINTER_COLLATE</tt> </td><td>Can collage copies</td></tr>
-<tr><td><tt>CUPS_PRINTER_COLOR</tt> </td><td>Can do color printing</td></tr>
-<tr><td><tt>CUPS_PRINTER_COPIES</tt> </td><td>Can do copies</td></tr>
-<tr><td><tt>CUPS_PRINTER_COVER</tt> </td><td>Can cover output</td></tr>
-<tr><td><tt>CUPS_PRINTER_DEFAULT</tt> </td><td>Default printer on network</td></tr>
-<tr><td><tt>CUPS_PRINTER_DELETE</tt> <span class='info'> CUPS 1.2 </span></td><td>Delete printer </td></tr>
-<tr><td><tt>CUPS_PRINTER_DUPLEX</tt> </td><td>Can do duplexing</td></tr>
-<tr><td><tt>CUPS_PRINTER_FAX</tt> </td><td>Fax queue</td></tr>
-<tr><td><tt>CUPS_PRINTER_IMPLICIT</tt> </td><td>Implicit class</td></tr>
-<tr><td><tt>CUPS_PRINTER_LARGE</tt> </td><td>Can do D/E/A1/A0</td></tr>
-<tr><td><tt>CUPS_PRINTER_LOCAL</tt> </td><td>Local printer or class</td></tr>
-<tr><td><tt>CUPS_PRINTER_MEDIUM</tt> </td><td>Can do Tabloid/B/C/A3/A2</td></tr>
-<tr><td><tt>CUPS_PRINTER_NOT_SHARED</tt> <span class='info'> CUPS 1.2 </span></td><td>Printer is not shared </td></tr>
-<tr><td><tt>CUPS_PRINTER_OPTIONS</tt> </td><td>~(CLASS | REMOTE | IMPLICIT)</td></tr>
-<tr><td><tt>CUPS_PRINTER_PUNCH</tt> </td><td>Can punch output</td></tr>
-<tr><td><tt>CUPS_PRINTER_REJECTING</tt> </td><td>Printer is rejecting jobs</td></tr>
-<tr><td><tt>CUPS_PRINTER_REMOTE</tt> </td><td>Remote printer or class</td></tr>
-<tr><td><tt>CUPS_PRINTER_SMALL</tt> </td><td>Can do Letter/Legal/A4</td></tr>
-<tr><td><tt>CUPS_PRINTER_SORT</tt> </td><td>Can sort output</td></tr>
-<tr><td><tt>CUPS_PRINTER_STAPLE</tt> </td><td>Can staple output</td></tr>
-<tr><td><tt>CUPS_PRINTER_VARIABLE</tt> </td><td>Can do variable sizes</td></tr>
+<tr><td><tt>CUPS_PRINTER_AUTHENTICATED</tt> <span class='info'> CUPS 1.2 </span></td><td>Printer requires authentication
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_BIND</tt> </td><td>Can bind output
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_BW</tt> </td><td>Can do B&W printing
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_CLASS</tt> </td><td>Printer class
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_COLLATE</tt> </td><td>Can collage copies
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_COLOR</tt> </td><td>Can do color printing
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_COMMANDS</tt> <span class='info'> CUPS 1.2 </span></td><td>Printer supports maintenance commands
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_COPIES</tt> </td><td>Can do copies
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_COVER</tt> </td><td>Can cover output
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_DEFAULT</tt> </td><td>Default printer on network
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_DELETE</tt> <span class='info'> CUPS 1.2 </span></td><td>Delete printer
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_DISCOVERED</tt> <span class='info'> CUPS 1.3 </span></td><td>Printer was automatically discovered and added
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_DUPLEX</tt> </td><td>Can do duplexing
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_FAX</tt> </td><td>Fax queue
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_IMPLICIT</tt> </td><td>Implicit class
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_LARGE</tt> </td><td>Can do D/E/A1/A0
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_LOCAL</tt> </td><td>Local printer or class
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_MEDIUM</tt> </td><td>Can do Tabloid/B/C/A3/A2
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_NOT_SHARED</tt> <span class='info'> CUPS 1.2 </span></td><td>Printer is not shared
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_OPTIONS</tt> </td><td>~(CLASS | REMOTE | IMPLICIT | DEFAULT | FAX | REJECTING | DELETE | NOT_SHARED | AUTHENTICATED | COMMANDS | DISCOVERED)
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_PUNCH</tt> </td><td>Can punch output
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_REJECTING</tt> </td><td>Printer is rejecting jobs
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_REMOTE</tt> </td><td>Remote printer or class
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_SMALL</tt> </td><td>Can do Letter/Legal/A4
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_SORT</tt> </td><td>Can sort output
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_STAPLE</tt> </td><td>Can staple output
+</td></tr>
+<tr><td><tt>CUPS_PRINTER_VARIABLE</tt> </td><td>Can do variable sizes
+</td></tr>
</tbody></table></div>
<!-- NEW PAGE -->
<h2 class='title'><a name='FUNCTIONS'>Functions</a></h2>
<li><a href='#cupsGetOption'><tt>cupsGetOption()</tt></a> </li>
<li><a href='#cupsGetPPD'><tt>cupsGetPPD()</tt></a> </li>
<li><a href='#cupsGetPPD2'><tt>cupsGetPPD2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
+ <li><a href='#cupsGetPPD3'><tt>cupsGetPPD3()</tt></a> </li>
<li><a href='#cupsGetPassword'><tt>cupsGetPassword()</tt></a> </li>
<li><a href='#cupsGetPrinters'><tt>cupsGetPrinters()</tt></a> <span class='info'> DEPRECATED </span></li>
+ <li><a href='#cupsGetServerPPD'><tt>cupsGetServerPPD()</tt></a> <span class='info'> CUPS 1.3 </span></li>
<li><a href='#cupsLangDefault'><tt>cupsLangDefault()</tt></a> </li>
<li><a href='#cupsLangEncoding'><tt>cupsLangEncoding()</tt></a> </li>
<li><a href='#cupsLangFlush'><tt>cupsLangFlush()</tt></a> </li>
<li><a href='#cupsLastError'><tt>cupsLastError()</tt></a> </li>
<li><a href='#cupsLastErrorString'><tt>cupsLastErrorString()</tt></a> <span class='info'> CUPS 1.2 </span></li>
<li><a href='#cupsMarkOptions'><tt>cupsMarkOptions()</tt></a> </li>
+ <li><a href='#cupsNotifySubject'><tt>cupsNotifySubject()</tt></a> <span class='info'> CUPS 1.2 </span></li>
+ <li><a href='#cupsNotifyText'><tt>cupsNotifyText()</tt></a> <span class='info'> CUPS 1.2 </span></li>
<li><a href='#cupsParseOptions'><tt>cupsParseOptions()</tt></a> </li>
<li><a href='#cupsPrintFile'><tt>cupsPrintFile()</tt></a> </li>
<li><a href='#cupsPrintFile2'><tt>cupsPrintFile2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
<li><a href='#cupsPrintFiles2'><tt>cupsPrintFiles2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
<li><a href='#cupsPutFd'><tt>cupsPutFd()</tt></a> <span class='info'> CUPS 1.1.20 </span></li>
<li><a href='#cupsPutFile'><tt>cupsPutFile()</tt></a> <span class='info'> CUPS 1.1.20 </span></li>
+ <li><a href='#cupsRemoveDest'><tt>cupsRemoveDest()</tt></a> <span class='info'> CUPS 1.3 </span></li>
+ <li><a href='#cupsRemoveOption'><tt>cupsRemoveOption()</tt></a> <span class='info'> CUPS 1.2 </span></li>
<li><a href='#cupsServer'><tt>cupsServer()</tt></a> </li>
+ <li><a href='#cupsSetDefaultDest'><tt>cupsSetDefaultDest()</tt></a> <span class='info'> CUPS 1.3 </span></li>
<li><a href='#cupsSetDests'><tt>cupsSetDests()</tt></a> </li>
<li><a href='#cupsSetDests2'><tt>cupsSetDests2()</tt></a> <span class='info'> CUPS 1.1.21 </span></li>
<li><a href='#cupsSetEncryption'><tt>cupsSetEncryption()</tt></a> </li>
<h3 class='title'><a name='cupsAddDest'>cupsAddDest()</a></h3>
<h4>Description</h4>
<p>Add a destination to the list of destinations.
-
-Use the cupsSaveDests() function to save the updated list of destinations
-to the user's lpoptions file.</p>
+<p>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.
+<p>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.
+<p>Use the cupsSaveDests() function to save the updated list of
+destinations to the user's lpoptions file.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsAddDest(
const char * name,
const char * instance,
int num_dests,
<a href='#cups_dest_t'>cups_dest_t</a> ** dests);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
-<tr><td><tt>name</tt></td><td>Name of destination</td></tr>
-<tr><td><tt>instance</tt></td><td>Instance of destination or NULL for none/primary</td></tr>
+<tr><td><tt>name</tt></td><td>Destination name</td></tr>
+<tr><td><tt>instance</tt></td><td>Instance name or NULL for none/primary</td></tr>
<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
</tbody></table></div>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsAddOption'>cupsAddOption()</a></h3>
<h4>Description</h4>
-<p>Add an option to an option array.</p>
+<p>Add an option to an option array.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsAddOption(
const char * name,
const char * value,
int num_options,
<a href='#cups_option_t'>cups_option_t</a> ** options);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>name</tt></td><td>Name of option</td></tr>
<h3 class='title'><a name='cupsCancelJob'>cupsCancelJob()</a></h3>
<h4>Description</h4>
<p>Cancel a print job on the default server.
-
-Use the cupsLastError() and cupsLastErrorString() functions to get
-the cause of any failure.</p>
+<p>Use the cupsLastError() and cupsLastErrorString() functions to get
+the cause of any failure.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsCancelJob(
const char * name,
int job);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>name</tt></td><td>Name of printer or class</td></tr>
<h3 class='title'><a name='cupsEncryption'>cupsEncryption()</a></h3>
<h4>Description</h4>
<p>Get the default encryption settings.
-
-The default encryption setting comes from the CUPS_ENCRYPTION
+<p>The default encryption setting comes from the CUPS_ENCRYPTION
environment variable, then the ~/.cupsrc file, and finally the
/etc/cups/client.conf file. If not set, the default is
-HTTP_ENCRYPT_IF_REQUESTED.</p>
+HTTP_ENCRYPT_IF_REQUESTED.
<h4>Syntax</h4>
-<pre>
-http_encryption_t
+<p><tt>
+http_encryption_t<br>
cupsEncryption(void);
-</pre>
+</tt></p>
<h4>Arguments</h4>
<p>None.</p>
<h4>Returns</h4>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsFreeDests'>cupsFreeDests()</a></h3>
<h4>Description</h4>
-<p>Free the memory used by the list of destinations.</p>
+<p>Free the memory used by the list of destinations.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsFreeDests(
int num_dests,
<a href='#cups_dest_t'>cups_dest_t</a> * dests);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsFreeJobs'>cupsFreeJobs()</a></h3>
<h4>Description</h4>
-<p>Free memory used by job data.</p>
+<p>Free memory used by job data.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsFreeJobs(
int num_jobs,
<a href='#cups_job_t'>cups_job_t</a> * jobs);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>num_jobs</tt></td><td>Number of jobs</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsFreeOptions'>cupsFreeOptions()</a></h3>
<h4>Description</h4>
-<p>Free all memory used by options.</p>
+<p>Free all memory used by options.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsFreeOptions(
int num_options,
<a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
<h3 class='title'><span class='info'> DEPRECATED </span><a name='cupsGetClasses'>cupsGetClasses()</a></h3>
<h4>Description</h4>
<p>Get a list of printer classes from the default server.
+<p>This function is deprecated - use cupsGetDests() instead.
-This function is deprecated - use cupsGetDests() instead.
-</p>
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsGetClasses(
char *** classes);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>classes</tt></td><td>Classes</td></tr>
<h3 class='title'><a name='cupsGetDefault'>cupsGetDefault()</a></h3>
<h4>Description</h4>
<p>Get the default printer or class for the default server.
-
-This function returns the default printer or class as defined by
+<p>This function returns the default printer or class as defined by
the LPDEST or PRINTER environment variables. If these environment
variables are not set, the server default destination is returned.
Applications should use the cupsGetDests() and cupsGetDest() functions
to get the user-defined default printer, as this function does not
-support the lpoptions-defined default printer.</p>
+support the lpoptions-defined default printer.
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsGetDefault(void);
-</pre>
+</tt></p>
<h4>Arguments</h4>
<p>None.</p>
<h4>Returns</h4>
<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsGetDefault2'>cupsGetDefault2()</a></h3>
<h4>Description</h4>
<p>Get the default printer or class for the specified server.
-
-This function returns the default printer or class as defined by
+<p>This function returns the default printer or class as defined by
the LPDEST or PRINTER environment variables. If these environment
variables are not set, the server default destination is returned.
Applications should use the cupsGetDests() and cupsGetDest() functions
to get the user-defined default printer, as this function does not
support the lpoptions-defined default printer.
-</p>
+
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsGetDefault2(
http_t * http);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
<h3 class='title'><a name='cupsGetDest'>cupsGetDest()</a></h3>
<h4>Description</h4>
<p>Get the named destination from the list.
-
-Use the cupsGetDests() or cupsGetDests2() functions to get a
-list of supported destinations for the current user.</p>
+<p>Use the cupsGetDests() or cupsGetDests2() functions to get a
+list of supported destinations for the current user.
<h4>Syntax</h4>
-<pre>
-<a href='#cups_dest_t'>cups_dest_t</a> *
+<p><tt>
+<a href='#cups_dest_t'>cups_dest_t</a> *<br>
cupsGetDest(
const char * name,
const char * instance,
int num_dests,
<a href='#cups_dest_t'>cups_dest_t</a> * dests);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
-<tr><td><tt>name</tt></td><td>Name of destination</td></tr>
-<tr><td><tt>instance</tt></td><td>Instance of destination</td></tr>
+<tr><td><tt>name</tt></td><td>Destination name or NULL for the default destination</td></tr>
+<tr><td><tt>instance</tt></td><td>Instance name or NULL</td></tr>
<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
</tbody></table></div>
<h3 class='title'><a name='cupsGetDests'>cupsGetDests()</a></h3>
<h4>Description</h4>
<p>Get the list of destinations from the default server.
-
-Starting with CUPS 1.2, the returned list of destinations include the
+<p>Starting with CUPS 1.2, the returned list of destinations include the
printer-info, printer-is-accepting-jobs, printer-is-shared,
printer-make-and-model, printer-state, printer-state-change-time,
-printer-state-reasons, and printer-type attributes as options.</p>
+printer-state-reasons, and printer-type attributes as options.
+<p>Use the cupsFreeDests() function to free the destination list and
+the cupsGetDest() function to find a particular destination.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsGetDests(
<a href='#cups_dest_t'>cups_dest_t</a> ** dests);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsGetDests2'>cupsGetDests2()</a></h3>
<h4>Description</h4>
<p>Get the list of destinations from the specified server.
-
-Starting with CUPS 1.2, the returned list of destinations include the
+<p>Starting with CUPS 1.2, the returned list of destinations include the
printer-info, printer-is-accepting-jobs, printer-is-shared,
printer-make-and-model, printer-state, printer-state-change-time,
printer-state-reasons, and printer-type attributes as options.
+<p>Use the cupsFreeDests() function to free the destination list and
+the cupsGetDest() function to find a particular destination.
+
-</p>
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsGetDests2(
http_t * http,
<a href='#cups_dest_t'>cups_dest_t</a> ** dests);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
<h3 class='title'><span class='info'> CUPS 1.1.20 </span><a name='cupsGetFd'>cupsGetFd()</a></h3>
<h4>Description</h4>
<p>Get a file from the server.
+<p>This function returns HTTP_OK when the file is successfully retrieved.
-This function returns HTTP_OK when the file is successfully retrieved.
-</p>
<h4>Syntax</h4>
-<pre>
-http_status_t
+<p><tt>
+http_status_t<br>
cupsGetFd(
http_t * http,
const char * resource,
int fd);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
<h3 class='title'><span class='info'> CUPS 1.1.20 </span><a name='cupsGetFile'>cupsGetFile()</a></h3>
<h4>Description</h4>
<p>Get a file from the server.
+<p>This function returns HTTP_OK when the file is successfully retrieved.
-This function returns HTTP_OK when the file is successfully retrieved.
-</p>
<h4>Syntax</h4>
-<pre>
-http_status_t
+<p><tt>
+http_status_t<br>
cupsGetFile(
http_t * http,
const char * resource,
const char * filename);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsGetJobs'>cupsGetJobs()</a></h3>
<h4>Description</h4>
-<p>Get the jobs from the default server.</p>
+<p>Get the jobs from the default server.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsGetJobs(
<a href='#cups_job_t'>cups_job_t</a> ** jobs,
const char * mydest,
int myjobs,
int completed);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>jobs</tt></td><td>Job data</td></tr>
<h4>Description</h4>
<p>Get the jobs from the specified server.
-</p>
+
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsGetJobs2(
http_t * http,
<a href='#cups_job_t'>cups_job_t</a> ** jobs,
const char * mydest,
int myjobs,
int completed);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsGetOption'>cupsGetOption()</a></h3>
<h4>Description</h4>
-<p>Get an option value.</p>
+<p>Get an option value.
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsGetOption(
const char * name,
int num_options,
<a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>name</tt></td><td>Name of option</td></tr>
<h3 class='title'><a name='cupsGetPPD'>cupsGetPPD()</a></h3>
<h4>Description</h4>
<p>Get the PPD file for a printer on the default server.
-
-For classes, cupsGetPPD() returns the PPD file for the first printer
-in the class.</p>
+<p>For classes, cupsGetPPD() returns the PPD file for the first printer
+in the class.
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsGetPPD(
const char * name);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>name</tt></td><td>Printer name</td></tr>
<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsGetPPD2'>cupsGetPPD2()</a></h3>
<h4>Description</h4>
<p>Get the PPD file for a printer from the specified server.
-
-For classes, cupsGetPPD2() returns the PPD file for the first printer
+<p>For classes, cupsGetPPD2() returns the PPD file for the first printer
in the class.
-</p>
+
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsGetPPD2(
http_t * http,
const char * name);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
<h4>Returns</h4>
<p>Filename for PPD file</p>
<!-- NEW PAGE -->
+<h3 class='title'><a name='cupsGetPPD3'>cupsGetPPD3()</a></h3>
+<h4>Description</h4>
+<p>Get the PPD file for a printer on the specified
+server if it has changed.
+<p>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.
+<p>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.
+<p>On success, HTTP_OK is returned for a new PPD file and HTTP_NOT_MODIFIED
+if the existing PPD file is up-to-date. Any other status is an error.
+<h4>Syntax</h4>
+<p><tt>
+http_status_t<br>
+cupsGetPPD3(
+ http_t * http,
+ const char * name,
+ time_t * modtime,
+ char * buffer,
+ size_t bufsize);
+</tt></p>
+<h4>Arguments</h4>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
+<thead><tr><th>Name</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
+<tr><td><tt>name</tt></td><td>Printer name</td></tr>
+<tr><td><tt>modtime</tt></td><td>Modification time</td></tr>
+<tr><td><tt>buffer</tt></td><td>Filename buffer</td></tr>
+<tr><td><tt>bufsize</tt></td><td>Size of filename buffer</td></tr>
+</tbody></table></div>
+<h4>Returns</h4>
+<p>HTTP status</p>
+<!-- NEW PAGE -->
<h3 class='title'><a name='cupsGetPassword'>cupsGetPassword()</a></h3>
<h4>Description</h4>
<p>Get a password from the user.
-
-Uses the current password callback function. Returns NULL if the
-user does not provide a password.</p>
+<p>Uses the current password callback function. Returns NULL if the
+user does not provide a password.
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsGetPassword(
const char * prompt);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>prompt</tt></td><td>Prompt string</td></tr>
<h3 class='title'><span class='info'> DEPRECATED </span><a name='cupsGetPrinters'>cupsGetPrinters()</a></h3>
<h4>Description</h4>
<p>Get a list of printers from the default server.
+<p>This function is deprecated - use cupsGetDests() instead.
-This function is deprecated - use cupsGetDests() instead.
-</p>
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsGetPrinters(
char *** printers);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>printers</tt></td><td>Printers</td></tr>
<h4>Returns</h4>
<p>Number of printers</p>
<!-- NEW PAGE -->
+<h3 class='title'><span class='info'> CUPS 1.3 </span><a name='cupsGetServerPPD'>cupsGetServerPPD()</a></h3>
+<h4>Description</h4>
+<p>Get an available PPD file from the server.
+<p>This function returns the named PPD file from the server. The
+list of available PPDs is provided by the IPP CUPS_GET_PPDS
+operation.
+<p>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 cupsGetPPD(), cupsGetPPD2(), or
+cupsGetServerPPD().
+
+
+<h4>Syntax</h4>
+<p><tt>
+char *<br>
+cupsGetServerPPD(
+ http_t * http,
+ const char * name);
+</tt></p>
+<h4>Arguments</h4>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
+<thead><tr><th>Name</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
+<tr><td><tt>name</tt></td><td>Name of PPD file ("ppd-name")</td></tr>
+</tbody></table></div>
+<h4>Returns</h4>
+<p>Name of PPD file or NULL on error</p>
+<!-- NEW PAGE -->
<h3 class='title'><a name='cupsLangDefault'>cupsLangDefault()</a></h3>
<h4>Description</h4>
-<p>Return the default language.</p>
+<p>Return the default language.
<h4>Syntax</h4>
-<pre>
-cups_lang_t *
+<p><tt>
+cups_lang_t *<br>
cupsLangDefault(void);
-</pre>
+</tt></p>
<h4>Arguments</h4>
<p>None.</p>
<h4>Returns</h4>
<h3 class='title'><a name='cupsLangEncoding'>cupsLangEncoding()</a></h3>
<h4>Description</h4>
<p>Return the character encoding (us-ascii, etc.)
-for the given language.</p>
+for the given language.
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsLangEncoding(
cups_lang_t * lang);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>lang</tt></td><td>Language data</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsLangFlush'>cupsLangFlush()</a></h3>
<h4>Description</h4>
-<p>Flush all language data out of the cache.</p>
+<p>Flush all language data out of the cache.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsLangFlush(void);
-</pre>
+</tt></p>
<h4>Arguments</h4>
<p>None.</p>
<h4>Returns</h4>
<h3 class='title'><a name='cupsLangFree'>cupsLangFree()</a></h3>
<h4>Description</h4>
<p>Free language data.
-
-This does not actually free anything; use cupsLangFlush() for that.</p>
+<p>This does not actually free anything; use cupsLangFlush() for that.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsLangFree(
cups_lang_t * lang);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>lang</tt></td><td>Language to free</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsLangGet'>cupsLangGet()</a></h3>
<h4>Description</h4>
-<p>Get a language.</p>
+<p>Get a language.
<h4>Syntax</h4>
-<pre>
-cups_lang_t *
+<p><tt>
+cups_lang_t *<br>
cupsLangGet(
const char * language);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>language</tt></td><td>Language or locale</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsLastError'>cupsLastError()</a></h3>
<h4>Description</h4>
-<p>Return the last IPP status code.</p>
+<p>Return the last IPP status code.
<h4>Syntax</h4>
-<pre>
-ipp_status_t
+<p><tt>
+ipp_status_t<br>
cupsLastError(void);
-</pre>
+</tt></p>
<h4>Arguments</h4>
<p>None.</p>
<h4>Returns</h4>
<h4>Description</h4>
<p>Return the last IPP status-message.
-</p>
+
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsLastErrorString(void);
-</pre>
+</tt></p>
<h4>Arguments</h4>
<p>None.</p>
<h4>Returns</h4>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsMarkOptions'>cupsMarkOptions()</a></h3>
<h4>Description</h4>
-<p>Mark command-line options in a PPD file.</p>
+<p>Mark command-line options in a PPD file.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsMarkOptions(
ppd_file_t * ppd,
int num_options,
<a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>ppd</tt></td><td>PPD file</td></tr>
<h4>Returns</h4>
<p>1 if conflicting</p>
<!-- NEW PAGE -->
+<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsNotifySubject'>cupsNotifySubject()</a></h3>
+<h4>Description</h4>
+<p>Return the subject for the given notification message.
+<p>The returned string must be freed by the caller using free().
+
+
+<h4>Syntax</h4>
+<p><tt>
+char *<br>
+cupsNotifySubject(
+ cups_lang_t * lang,
+ ipp_t * event);
+</tt></p>
+<h4>Arguments</h4>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
+<thead><tr><th>Name</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><tt>lang</tt></td><td>Language data</td></tr>
+<tr><td><tt>event</tt></td><td>Event data</td></tr>
+</tbody></table></div>
+<h4>Returns</h4>
+<p>Subject string or NULL</p>
+<!-- NEW PAGE -->
+<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsNotifyText'>cupsNotifyText()</a></h3>
+<h4>Description</h4>
+<p>Return the text for the given notification message.
+<p>The returned string must be freed by the caller using free().
+
+
+<h4>Syntax</h4>
+<p><tt>
+char *<br>
+cupsNotifyText(
+ cups_lang_t * lang,
+ ipp_t * event);
+</tt></p>
+<h4>Arguments</h4>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
+<thead><tr><th>Name</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><tt>lang</tt></td><td>Language data</td></tr>
+<tr><td><tt>event</tt></td><td>Event data</td></tr>
+</tbody></table></div>
+<h4>Returns</h4>
+<p>Message text or NULL</p>
+<!-- NEW PAGE -->
<h3 class='title'><a name='cupsParseOptions'>cupsParseOptions()</a></h3>
<h4>Description</h4>
<p>Parse options from a command-line argument.
-
-This function converts space-delimited name/value pairs according
+<p>This function converts space-delimited name/value pairs according
to the PAPI text option ABNF specification. Collection values
("name={a=... b=... c=...}") are stored with the curley brackets
intact - use cupsParseOptions() on the value to extract the collection
-attributes.</p>
+attributes.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsParseOptions(
const char * arg,
int num_options,
<a href='#cups_option_t'>cups_option_t</a> ** options);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>arg</tt></td><td>Argument to parse</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsPrintFile'>cupsPrintFile()</a></h3>
<h4>Description</h4>
-<p>Print a file to a printer or class on the default server.</p>
+<p>Print a file to a printer or class on the default server.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsPrintFile(
const char * name,
const char * filename,
const char * title,
int num_options,
<a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
<h4>Description</h4>
<p>Print a file to a printer or class on the specified server.
-</p>
+
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsPrintFile2(
http_t * http,
const char * name,
const char * title,
int num_options,
<a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
<h3 class='title'><a name='cupsPrintFiles'>cupsPrintFiles()</a></h3>
<h4>Description</h4>
<p>Print one or more files to a printer or class on the
-default server.</p>
+default server.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsPrintFiles(
const char * name,
int num_files,
const char * title,
int num_options,
<a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
<p>Print one or more files to a printer or class on the
specified server.
-</p>
+
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsPrintFiles2(
http_t * http,
const char * name,
const char * title,
int num_options,
<a href='#cups_option_t'>cups_option_t</a> * options);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
<h3 class='title'><span class='info'> CUPS 1.1.20 </span><a name='cupsPutFd'>cupsPutFd()</a></h3>
<h4>Description</h4>
<p>Put a file on the server.
+<p>This function returns HTTP_CREATED when the file is stored successfully.
-This function returns HTTP_CREATED when the file is stored successfully.
-</p>
<h4>Syntax</h4>
-<pre>
-http_status_t
+<p><tt>
+http_status_t<br>
cupsPutFd(
http_t * http,
const char * resource,
int fd);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
<h3 class='title'><span class='info'> CUPS 1.1.20 </span><a name='cupsPutFile'>cupsPutFile()</a></h3>
<h4>Description</h4>
<p>Put a file on the server.
+<p>This function returns HTTP_CREATED when the file is stored successfully.
-This function returns HTTP_CREATED when the file is stored successfully.
-</p>
<h4>Syntax</h4>
-<pre>
-http_status_t
+<p><tt>
+http_status_t<br>
cupsPutFile(
http_t * http,
const char * resource,
const char * filename);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
<h4>Returns</h4>
<p>HTTP status</p>
<!-- NEW PAGE -->
+<h3 class='title'><span class='info'> CUPS 1.3 </span><a name='cupsRemoveDest'>cupsRemoveDest()</a></h3>
+<h4>Description</h4>
+<p>Remove a destination from the destination list.
+<p>Removing a destination/instance does not delete the class or printer
+queue, merely the lpoptions for that destination/instance. Use the
+cupsSetDests() or cupsSetDests2() functions to save the new options
+for the user.
+
+
+<h4>Syntax</h4>
+<p><tt>
+int<br>
+cupsRemoveDest(
+ const char * name,
+ const char * instance,
+ int num_dests,
+ <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
+</tt></p>
+<h4>Arguments</h4>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
+<thead><tr><th>Name</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><tt>name</tt></td><td>Destination name</td></tr>
+<tr><td><tt>instance</tt></td><td>Instance name or NULL</td></tr>
+<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
+<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
+</tbody></table></div>
+<h4>Returns</h4>
+<p>New number of destinations</p>
+<!-- NEW PAGE -->
+<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsRemoveOption'>cupsRemoveOption()</a></h3>
+<h4>Description</h4>
+<p>Remove an option from an option array.
+
+
+<h4>Syntax</h4>
+<p><tt>
+int<br>
+cupsRemoveOption(
+ const char * name,
+ int num_options,
+ <a href='#cups_option_t'>cups_option_t</a> ** options);
+</tt></p>
+<h4>Arguments</h4>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
+<thead><tr><th>Name</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><tt>name</tt></td><td>Option name</td></tr>
+<tr><td><tt>num_options</tt></td><td>Current number of options</td></tr>
+<tr><td><tt>options</tt></td><td>Options</td></tr>
+</tbody></table></div>
+<h4>Returns</h4>
+<p>New number of options</p>
+<!-- NEW PAGE -->
<h3 class='title'><a name='cupsServer'>cupsServer()</a></h3>
<h4>Description</h4>
<p>Return the hostname/address of the default server.
-
-The returned value can be a fully-qualified hostname, a numeric
-IPv4 or IPv6 address, or a domain socket pathname.</p>
+<p>The returned value can be a fully-qualified hostname, a numeric
+IPv4 or IPv6 address, or a domain socket pathname.
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsServer(void);
-</pre>
+</tt></p>
<h4>Arguments</h4>
<p>None.</p>
<h4>Returns</h4>
<p>Server name</p>
<!-- NEW PAGE -->
+<h3 class='title'><span class='info'> CUPS 1.3 </span><a name='cupsSetDefaultDest'>cupsSetDefaultDest()</a></h3>
+<h4>Description</h4>
+<p>Set the default destination.
+
+
+<h4>Syntax</h4>
+<p><tt>
+void<br>
+cupsSetDefaultDest(
+ const char * name,
+ const char * instance,
+ int num_dests,
+ <a href='#cups_dest_t'>cups_dest_t</a> * dests);
+</tt></p>
+<h4>Arguments</h4>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
+<thead><tr><th>Name</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><tt>name</tt></td><td>Destination name</td></tr>
+<tr><td><tt>instance</tt></td><td>Instance name or NULL</td></tr>
+<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
+<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
+</tbody></table></div>
+<h4>Returns</h4>
+<p>Nothing.</p>
+<!-- NEW PAGE -->
<h3 class='title'><a name='cupsSetDests'>cupsSetDests()</a></h3>
<h4>Description</h4>
<p>Save the list of destinations for the default server.
-
-This function saves the destinations to /etc/cups/lpoptions when run
-as root and ~/.lpoptions when run as a normal user.</p>
+<p>This function saves the destinations to /etc/cups/lpoptions when run
+as root and ~/.cups/lpoptions when run as a normal user.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsSetDests(
int num_dests,
<a href='#cups_dest_t'>cups_dest_t</a> * dests);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
<h3 class='title'><span class='info'> CUPS 1.1.21 </span><a name='cupsSetDests2'>cupsSetDests2()</a></h3>
<h4>Description</h4>
<p>Save the list of destinations for the specified server.
+<p>This function saves the destinations to /etc/cups/lpoptions when run
+as root and ~/.cups/lpoptions when run as a normal user.
-This function saves the destinations to /etc/cups/lpoptions when run
-as root and ~/.lpoptions when run as a normal user.
-</p>
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsSetDests2(
http_t * http,
int num_dests,
<a href='#cups_dest_t'>cups_dest_t</a> * dests);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsSetEncryption'>cupsSetEncryption()</a></h3>
<h4>Description</h4>
-<p>Set the encryption preference.</p>
+<p>Set the encryption preference.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsSetEncryption(
http_encryption_t e);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>e</tt></td><td>New encryption preference</td></tr>
<h3 class='title'><a name='cupsSetPasswordCB'>cupsSetPasswordCB()</a></h3>
<h4>Description</h4>
<p>Set the password callback for CUPS.
-
-Pass NULL to restore the default (console) password callback.</p>
+<p>Pass NULL to restore the default (console) password callback.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsSetPasswordCB(
<a href='#cups_password_cb_t'>cups_password_cb_t</a> cb);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>cb</tt></td><td>Callback function</td></tr>
<h3 class='title'><a name='cupsSetServer'>cupsSetServer()</a></h3>
<h4>Description</h4>
<p>Set the default server name.
-
-The "server" string can be a fully-qualified hostname, a numeric
+<p>The "server" string can be a fully-qualified hostname, a numeric
IPv4 or IPv6 address, or a domain socket pathname. Pass NULL to
-restore the default server name.</p>
+restore the default server name.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsSetServer(
const char * server);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>server</tt></td><td>Server name</td></tr>
<h3 class='title'><a name='cupsSetUser'>cupsSetUser()</a></h3>
<h4>Description</h4>
<p>Set the default user name.
-
-Pass NULL to restore the default user name.</p>
+<p>Pass NULL to restore the default user name.
<h4>Syntax</h4>
-<pre>
-void
+<p><tt>
+void<br>
cupsSetUser(
const char * user);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>user</tt></td><td>User name</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsTempFd'>cupsTempFd()</a></h3>
<h4>Description</h4>
-<p>Create a temporary file.
-
-The temporary filename is stored in the filename buffer.</p>
+<p>Creates a temporary file.
+<p>The temporary filename is returned in the filename buffer.
+The temporary file is opened for reading and writing.
<h4>Syntax</h4>
-<pre>
-int
+<p><tt>
+int<br>
cupsTempFd(
char * filename,
int len);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
<tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
</tbody></table></div>
<h4>Returns</h4>
-<p>New file descriptor</p>
+<p>New file descriptor or -1 on error</p>
<!-- NEW PAGE -->
<h3 class='title'><span class='info'> DEPRECATED </span><a name='cupsTempFile'>cupsTempFile()</a></h3>
<h4>Description</h4>
-<p>Generate a temporary filename.
-
-The temporary filename is stored in the filename buffer.
+<p>Generates a temporary filename.
+<p>The temporary filename is returned in the filename buffer.
This function is deprecated - use cupsTempFd() or cupsTempFile2()
instead.
-</p>
+
<h4>Syntax</h4>
-<pre>
-char *
+<p><tt>
+char *<br>
cupsTempFile(
char * filename,
int len);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
<tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
</tbody></table></div>
<h4>Returns</h4>
-<p>Filename</p>
+<p>Filename or NULL on error</p>
<!-- NEW PAGE -->
<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsTempFile2'>cupsTempFile2()</a></h3>
<h4>Description</h4>
-<p>Create a temporary CUPS file.
+<p>Creates a temporary CUPS file.
+<p>The temporary filename is returned in the filename buffer.
+The temporary file is opened for writing.
-The temporary filename is stored in the filename buffer.
-</p>
<h4>Syntax</h4>
-<pre>
-cups_file_t *
+<p><tt>
+cups_file_t *<br>
cupsTempFile2(
char * filename,
int len);
-</pre>
+</tt></p>
<h4>Arguments</h4>
-<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
+<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0' summary='Arguments'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
<!-- NEW PAGE -->
<h3 class='title'><a name='cupsUser'>cupsUser()</a></h3>
<h4>Description</h4>
-<p>Return the current user's name.</p>
+<p>Return the current user's name.
<h4>Syntax</h4>
-<pre>
-const char *
+<p><tt>
+const char *<br>
cupsUser(void);
-</pre>
+</tt></p>
<h4>Arguments</h4>
<p>None.</p>
<h4>Returns</h4>
<!-- NEW PAGE -->
<h3 class='title'><a name='cups_dest_s'>cups_dest_s</a></h3>
<h4>Description</h4>
-<p>Destination</p>
+<p>Destination
<h4>Definition</h4>
-<pre>
-struct cups_dest_s
-{
- char *name, * instance;
- int is_default;
- int num_options;
- <a href='#cups_option_t'>cups_option_t</a> * options;
-};
-</pre>
+<p><tt>
+struct cups_dest_s<br>
+{<br>
+ char *name, * instance;<br>
+ int is_default;<br>
+ int num_options;<br>
+ <a href='#cups_option_t'>cups_option_t</a> * options;<br>
+};</tt></p>
<h4>Members</h4>
-<div class='table'><table align='center' border='1' width='80%'>
+<div class='table'><table align='center' border='1' width='80%' summary='Members'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
-<tr><td><tt>instance</tt> </td><td>Local instance name or NULL</td></tr>
-<tr><td><tt>is_default</tt> </td><td>Is this printer the default?</td></tr>
-<tr><td><tt>num_options</tt> </td><td>Number of options</td></tr>
-<tr><td><tt>options</tt> </td><td>Options</td></tr>
+<tr><td><tt>instance</tt> </td><td>Local instance name or NULL
+</td></tr>
+<tr><td><tt>is_default</tt> </td><td>Is this printer the default?
+</td></tr>
+<tr><td><tt>num_options</tt> </td><td>Number of options
+</td></tr>
+<tr><td><tt>options</tt> </td><td>Options
+</td></tr>
</tbody></table></div>
<!-- NEW PAGE -->
<h3 class='title'><a name='cups_job_s'>cups_job_s</a></h3>
<h4>Description</h4>
-<p>Job</p>
+<p>Job
<h4>Definition</h4>
-<pre>
-struct cups_job_s
-{
- time_t completed_time;
- time_t creation_time;
- char * dest;
- char * format;
- int id;
- int priority;
- time_t processing_time;
- int size;
- ipp_jstate_t state;
- char * title;
- char * user;
-};
-</pre>
+<p><tt>
+struct cups_job_s<br>
+{<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>
+};</tt></p>
<h4>Members</h4>
-<div class='table'><table align='center' border='1' width='80%'>
+<div class='table'><table align='center' border='1' width='80%' summary='Members'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
-<tr><td><tt>completed_time</tt> </td><td>Time the job was completed</td></tr>
-<tr><td><tt>creation_time</tt> </td><td>Time the job was created</td></tr>
-<tr><td><tt>dest</tt> </td><td>Printer or class name</td></tr>
-<tr><td><tt>format</tt> </td><td>Document format</td></tr>
-<tr><td><tt>id</tt> </td><td>The job ID</td></tr>
-<tr><td><tt>priority</tt> </td><td>Priority (1-100)</td></tr>
-<tr><td><tt>processing_time</tt> </td><td>Time the job was processed</td></tr>
-<tr><td><tt>size</tt> </td><td>Size in kilobytes</td></tr>
-<tr><td><tt>state</tt> </td><td>Job state</td></tr>
-<tr><td><tt>title</tt> </td><td>Title/job name</td></tr>
-<tr><td><tt>user</tt> </td><td>User the submitted the job</td></tr>
+<tr><td><tt>completed_time</tt> </td><td>Time the job was completed
+</td></tr>
+<tr><td><tt>creation_time</tt> </td><td>Time the job was created
+</td></tr>
+<tr><td><tt>dest</tt> </td><td>Printer or class name
+</td></tr>
+<tr><td><tt>format</tt> </td><td>Document format
+</td></tr>
+<tr><td><tt>id</tt> </td><td>The job ID
+</td></tr>
+<tr><td><tt>priority</tt> </td><td>Priority (1-100)
+</td></tr>
+<tr><td><tt>processing_time</tt> </td><td>Time the job was processed
+</td></tr>
+<tr><td><tt>size</tt> </td><td>Size in kilobytes
+</td></tr>
+<tr><td><tt>state</tt> </td><td>Job state
+</td></tr>
+<tr><td><tt>title</tt> </td><td>Title/job name
+</td></tr>
+<tr><td><tt>user</tt> </td><td>User the submitted the job
+</td></tr>
</tbody></table></div>
<!-- NEW PAGE -->
<h3 class='title'><a name='cups_option_s'>cups_option_s</a></h3>
<h4>Description</h4>
-<p>Printer Options</p>
+<p>Printer Options
<h4>Definition</h4>
-<pre>
-struct cups_option_s
-{
- char * name;
- char * value;
-};
-</pre>
+<p><tt>
+struct cups_option_s<br>
+{<br>
+ char * name;<br>
+ char * value;<br>
+};</tt></p>
<h4>Members</h4>
-<div class='table'><table align='center' border='1' width='80%'>
+<div class='table'><table align='center' border='1' width='80%' summary='Members'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
-<tr><td><tt>name</tt> </td><td>Name of option</td></tr>
-<tr><td><tt>value</tt> </td><td>Value of option</td></tr>
+<tr><td><tt>name</tt> </td><td>Name of option
+</td></tr>
+<tr><td><tt>value</tt> </td><td>Value of option
+</td></tr>
</tbody></table></div>
<!-- NEW PAGE -->
<h2 class='title'><a name='TYPES'>Types</a></h2>
<!-- NEW PAGE -->
<h3 class='title'><a name='cups_dest_t'>cups_dest_t</a></h3>
<h4>Description</h4>
-<p>Destination</p>
+<p>Destination
<h4>Definition</h4>
-<pre>
+<p><tt>
typedef struct <a href='#cups_dest_s'>cups_dest_s</a> cups_dest_t;
-</pre>
+</tt></p>
<!-- NEW PAGE -->
<h3 class='title'><a name='cups_job_t'>cups_job_t</a></h3>
<h4>Description</h4>
-<p>Job</p>
+<p>Job
<h4>Definition</h4>
-<pre>
+<p><tt>
typedef struct <a href='#cups_job_s'>cups_job_s</a> cups_job_t;
-</pre>
+</tt></p>
<!-- NEW PAGE -->
<h3 class='title'><a name='cups_option_t'>cups_option_t</a></h3>
<h4>Description</h4>
-<p>Printer Options</p>
+<p>Printer Options
<h4>Definition</h4>
-<pre>
+<p><tt>
typedef struct <a href='#cups_option_s'>cups_option_s</a> cups_option_t;
-</pre>
+</tt></p>
<!-- NEW PAGE -->
<h3 class='title'><a name='cups_password_cb_t'>cups_password_cb_t</a></h3>
<h4>Description</h4>
-<p>Password callback</p>
+<p>Password callback
<h4>Definition</h4>
-<pre>
+<p><tt>
typedef const char * (*cups_password_cb_t)(const char *);
-</pre>
+</tt></p>
<!-- NEW PAGE -->
<h3 class='title'><a name='cups_ptype_t'>cups_ptype_t</a></h3>
<h4>Description</h4>
-<p>Printer Type/Capability Bits</p>
+<p>Printer Type/Capability Bits
<h4>Definition</h4>
-<pre>
+<p><tt>
typedef unsigned cups_ptype_t;
-</pre>
+</tt></p>
</body>
</html>
projects / thirdparty / cups.git / blobdiff