doc/help/api-cups.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
   2 <html>
   3 <!-- SECTION: Programming -->
   4 <head>
   5         <title>CUPS API</title>
   6         <meta name='keywords' content='Programming'>
   7         <meta name='creator' content='Mini-XML v2.3'>
   8         <style type='text/css'><!--
   9         h1, h2, h3, p { font-family: sans-serif; text-align: justify; }
  10         tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }
  11         pre { font-weight: bold; color: #7f0000; margin-left: 2em; }
  12         span.info { background: #000000; border: solid thin #000000; color: #ffffff; font-size: 80%; font-style: italic; font-weight: bold; white-space: nowrap; }
  13         h3 span.info { float: right; font-size: 100%; }
  14         h1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }
  15         --></style>
  16 </head>
  17 <body>
  18 <!--
  19   "$Id: api-cups.shtml 5138 2006-02-21 10:49:06Z mike $"
  20
  21   CUPS API introduction for the Common UNIX Printing System (CUPS).
  22
  23   Copyright 1997-2006 by Easy Software Products.
  24
  25   These coded instructions, statements, and computer programs are the
  26   property of Easy Software Products and are protected by Federal
  27   copyright law.  Distribution and use rights are outlined in the file
  28   "LICENSE.txt" which should have been included with this file.  If this
  29   file is missing or damaged please contact Easy Software Products
  30   at:
  31
  32       Attn: CUPS Licensing Information
  33       Easy Software Products
  34       44141 Airport View Drive, Suite 204
  35       Hollywood, Maryland 20636 USA
  36
  37       Voice: (301) 373-9600
  38       EMail: cups-info@cups.org
  39         WWW: http://www.cups.org
  40 -->
  41
  42 <h2 class='title'>Introduction</h2>
  43
  44 <p>The CUPS library provides a whole collection of interfaces
  45 needed to support the internal needs of the CUPS software as well
  46 as the needs of applications, filters, printer drivers, and
  47 backends.</p>
  48
  49 <p>Unlike the rest of CUPS, the CUPS API library is provided
  50 under the GNU Library General Public License. This means that you
  51 can use the CUPS API library in both proprietary and open-source
  52 programs.</p>
  53
  54 <h2 class='title'>General Usage</h2>
  55
  56 <p>The <var>&lt;cups/cups.h&gt;</var> header file must be included to
  57 use the CUPS functions.</p>
  58
  59 <p>Programs using these functions must be linked to the CUPS
  60 library: <var>libcups.a</var>, <var>libcups.so.2</var>,
  61 <var>libcups.2.dylib</var>, <var>libcups_s.a</var>, or
  62 <var>libcups2.lib</var> depending on the platform. The following
  63 command compiles <var>myprogram.c</var> using GCC and the CUPS
  64 library:</p>
  65
  66 <pre class='command'>
  67 <kbd>gcc -o myprogram myprogram.c -lcups</kbd>
  68 </pre>
  69
  70 <h2 class='title'>Compatibility</h2>
  71
  72 <p>Unless otherwise specified, the CUPS API functions require
  73 CUPS 1.1 or higher.</p>
  74 <h2 class='title'>Contents</h2>
  75 <ul>
  76         <li><a href='#ENUMERATIONS'>Enumerations</a></li>
  77         <li><a href='#FUNCTIONS'>Functions</a></li>
  78         <li><a href='#STRUCTURES'>Structures</a></li>
  79         <li><a href='#TYPES'>Types</a></li>
  80 </ul>
  81 <!-- NEW PAGE -->
  82 <h2 class='title'><a name='ENUMERATIONS'>Enumerations</a></h2>
  83 <ul>
  84         <li><a href='#cups_ptype_e'><tt>cups_ptype_e</tt></a> </li>
  85 </ul>
  86 <!-- NEW PAGE -->
  87 <h3 class='title'><a name='cups_ptype_e'>cups_ptype_e</a></h3>
  88 <h4>Description</h4>
  89 <p>Not a typedef'd enum so we can OR</p>
  90 <h4>Values</h4>
  91 <div class='table'><table align='center' border='1' width='80%'>
  92 <thead><tr><th>Name</th><th>Description</th></tr></thead>
  93 <tbody>
  94 <tr><td><tt>CUPS_PRINTER_AUTHENTICATED</tt> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></td><td>Printer requires authentication </td></tr>
  95 <tr><td><tt>CUPS_PRINTER_BIND</tt> </td><td>Can bind output</td></tr>
  96 <tr><td><tt>CUPS_PRINTER_BW</tt> </td><td>Can do B&amp;W printing</td></tr>
  97 <tr><td><tt>CUPS_PRINTER_CLASS</tt> </td><td>Printer class</td></tr>
  98 <tr><td><tt>CUPS_PRINTER_COLLATE</tt> </td><td>Can collage copies</td></tr>
  99 <tr><td><tt>CUPS_PRINTER_COLOR</tt> </td><td>Can do color printing</td></tr>
 100 <tr><td><tt>CUPS_PRINTER_COMMANDS</tt> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></td><td>Printer supports maintenance commands </td></tr>
 101 <tr><td><tt>CUPS_PRINTER_COPIES</tt> </td><td>Can do copies</td></tr>
 102 <tr><td><tt>CUPS_PRINTER_COVER</tt> </td><td>Can cover output</td></tr>
 103 <tr><td><tt>CUPS_PRINTER_DEFAULT</tt> </td><td>Default printer on network</td></tr>
 104 <tr><td><tt>CUPS_PRINTER_DELETE</tt> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></td><td>Delete printer </td></tr>
 105 <tr><td><tt>CUPS_PRINTER_DUPLEX</tt> </td><td>Can do duplexing</td></tr>
 106 <tr><td><tt>CUPS_PRINTER_FAX</tt> </td><td>Fax queue</td></tr>
 107 <tr><td><tt>CUPS_PRINTER_IMPLICIT</tt> </td><td>Implicit class</td></tr>
 108 <tr><td><tt>CUPS_PRINTER_LARGE</tt> </td><td>Can do D/E/A1/A0</td></tr>
 109 <tr><td><tt>CUPS_PRINTER_LOCAL</tt> </td><td>Local printer or class</td></tr>
 110 <tr><td><tt>CUPS_PRINTER_MEDIUM</tt> </td><td>Can do Tabloid/B/C/A3/A2</td></tr>
 111 <tr><td><tt>CUPS_PRINTER_NOT_SHARED</tt> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></td><td>Printer is not shared </td></tr>
 112 <tr><td><tt>CUPS_PRINTER_OPTIONS</tt> </td><td>~(CLASS | REMOTE | IMPLICIT)</td></tr>
 113 <tr><td><tt>CUPS_PRINTER_PUNCH</tt> </td><td>Can punch output</td></tr>
 114 <tr><td><tt>CUPS_PRINTER_REJECTING</tt> </td><td>Printer is rejecting jobs</td></tr>
 115 <tr><td><tt>CUPS_PRINTER_REMOTE</tt> </td><td>Remote printer or class</td></tr>
 116 <tr><td><tt>CUPS_PRINTER_SMALL</tt> </td><td>Can do Letter/Legal/A4</td></tr>
 117 <tr><td><tt>CUPS_PRINTER_SORT</tt> </td><td>Can sort output</td></tr>
 118 <tr><td><tt>CUPS_PRINTER_STAPLE</tt> </td><td>Can staple output</td></tr>
 119 <tr><td><tt>CUPS_PRINTER_VARIABLE</tt> </td><td>Can do variable sizes</td></tr>
 120 </tbody></table></div>
 121 <!-- NEW PAGE -->
 122 <h2 class='title'><a name='FUNCTIONS'>Functions</a></h2>
 123 <ul>
 124         <li><a href='#cupsAddDest'><tt>cupsAddDest()</tt></a> </li>
 125         <li><a href='#cupsAddOption'><tt>cupsAddOption()</tt></a> </li>
 126         <li><a href='#cupsCancelJob'><tt>cupsCancelJob()</tt></a> </li>
 127         <li><a href='#cupsEncryption'><tt>cupsEncryption()</tt></a> </li>
 128         <li><a href='#cupsFreeDests'><tt>cupsFreeDests()</tt></a> </li>
 129         <li><a href='#cupsFreeJobs'><tt>cupsFreeJobs()</tt></a> </li>
 130         <li><a href='#cupsFreeOptions'><tt>cupsFreeOptions()</tt></a> </li>
 131         <li><a href='#cupsGetClasses'><tt>cupsGetClasses()</tt></a> <span class='info'>&nbsp;DEPRECATED&nbsp;</span></li>
 132         <li><a href='#cupsGetDefault'><tt>cupsGetDefault()</tt></a> </li>
 133         <li><a href='#cupsGetDefault2'><tt>cupsGetDefault2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
 134         <li><a href='#cupsGetDest'><tt>cupsGetDest()</tt></a> </li>
 135         <li><a href='#cupsGetDests'><tt>cupsGetDests()</tt></a> </li>
 136         <li><a href='#cupsGetDests2'><tt>cupsGetDests2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
 137         <li><a href='#cupsGetFd'><tt>cupsGetFd()</tt></a> <span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span></li>
 138         <li><a href='#cupsGetFile'><tt>cupsGetFile()</tt></a> <span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span></li>
 139         <li><a href='#cupsGetJobs'><tt>cupsGetJobs()</tt></a> </li>
 140         <li><a href='#cupsGetJobs2'><tt>cupsGetJobs2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
 141         <li><a href='#cupsGetOption'><tt>cupsGetOption()</tt></a> </li>
 142         <li><a href='#cupsGetPPD'><tt>cupsGetPPD()</tt></a> </li>
 143         <li><a href='#cupsGetPPD2'><tt>cupsGetPPD2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
 144         <li><a href='#cupsGetPassword'><tt>cupsGetPassword()</tt></a> </li>
 145         <li><a href='#cupsGetPrinters'><tt>cupsGetPrinters()</tt></a> <span class='info'>&nbsp;DEPRECATED&nbsp;</span></li>
 146         <li><a href='#cupsLangDefault'><tt>cupsLangDefault()</tt></a> </li>
 147         <li><a href='#cupsLangEncoding'><tt>cupsLangEncoding()</tt></a> </li>
 148         <li><a href='#cupsLangFlush'><tt>cupsLangFlush()</tt></a> </li>
 149         <li><a href='#cupsLangFree'><tt>cupsLangFree()</tt></a> </li>
 150         <li><a href='#cupsLangGet'><tt>cupsLangGet()</tt></a> </li>
 151         <li><a href='#cupsLastError'><tt>cupsLastError()</tt></a> </li>
 152         <li><a href='#cupsLastErrorString'><tt>cupsLastErrorString()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
 153         <li><a href='#cupsMarkOptions'><tt>cupsMarkOptions()</tt></a> </li>
 154         <li><a href='#cupsParseOptions'><tt>cupsParseOptions()</tt></a> </li>
 155         <li><a href='#cupsPrintFile'><tt>cupsPrintFile()</tt></a> </li>
 156         <li><a href='#cupsPrintFile2'><tt>cupsPrintFile2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
 157         <li><a href='#cupsPrintFiles'><tt>cupsPrintFiles()</tt></a> </li>
 158         <li><a href='#cupsPrintFiles2'><tt>cupsPrintFiles2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
 159         <li><a href='#cupsPutFd'><tt>cupsPutFd()</tt></a> <span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span></li>
 160         <li><a href='#cupsPutFile'><tt>cupsPutFile()</tt></a> <span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span></li>
 161         <li><a href='#cupsRemoveOption'><tt>cupsRemoveOption()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
 162         <li><a href='#cupsServer'><tt>cupsServer()</tt></a> </li>
 163         <li><a href='#cupsSetDests'><tt>cupsSetDests()</tt></a> </li>
 164         <li><a href='#cupsSetDests2'><tt>cupsSetDests2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
 165         <li><a href='#cupsSetEncryption'><tt>cupsSetEncryption()</tt></a> </li>
 166         <li><a href='#cupsSetPasswordCB'><tt>cupsSetPasswordCB()</tt></a> </li>
 167         <li><a href='#cupsSetServer'><tt>cupsSetServer()</tt></a> </li>
 168         <li><a href='#cupsSetUser'><tt>cupsSetUser()</tt></a> </li>
 169         <li><a href='#cupsTempFd'><tt>cupsTempFd()</tt></a> </li>
 170         <li><a href='#cupsTempFile'><tt>cupsTempFile()</tt></a> <span class='info'>&nbsp;DEPRECATED&nbsp;</span></li>
 171         <li><a href='#cupsTempFile2'><tt>cupsTempFile2()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
 172         <li><a href='#cupsUser'><tt>cupsUser()</tt></a> </li>
 173 </ul>
 174 <!-- NEW PAGE -->
 175 <h3 class='title'><a name='cupsAddDest'>cupsAddDest()</a></h3>
 176 <h4>Description</h4>
 177 <p>Add a destination to the list of destinations.
 178
 179 This function cannot be used to add a new class or printer queue,
 180 it only adds a new container of saved options for the named
 181 destination or instance.
 182
 183 If the named destination already exists, the destination list is
 184 returned unchanged.  Adding a new instance of a destination creates
 185 a copy of that destination's options.
 186
 187 Use the cupsSaveDests() function to save the updated list of
 188 destinations to the user's lpoptions file.</p>
 189 <h4>Syntax</h4>
 190 <pre>
 191 int
 192 cupsAddDest(
 193     const char * name,
 194     const char * instance,
 195     int num_dests,
 196     <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
 197 </pre>
 198 <h4>Arguments</h4>
 199 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 200 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 201 <tbody>
 202 <tr><td><tt>name</tt></td><td>Destination name</td></tr>
 203 <tr><td><tt>instance</tt></td><td>Instance name or NULL for none/primary</td></tr>
 204 <tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
 205 <tr><td><tt>dests</tt></td><td>Destinations</td></tr>
 206 </tbody></table></div>
 207 <h4>Returns</h4>
 208 <p>New number of destinations</p>
 209 <!-- NEW PAGE -->
 210 <h3 class='title'><a name='cupsAddOption'>cupsAddOption()</a></h3>
 211 <h4>Description</h4>
 212 <p>Add an option to an option array.</p>
 213 <h4>Syntax</h4>
 214 <pre>
 215 int
 216 cupsAddOption(
 217     const char * name,
 218     const char * value,
 219     int num_options,
 220     <a href='#cups_option_t'>cups_option_t</a> ** options);
 221 </pre>
 222 <h4>Arguments</h4>
 223 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 224 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 225 <tbody>
 226 <tr><td><tt>name</tt></td><td>Name of option</td></tr>
 227 <tr><td><tt>value</tt></td><td>Value of option</td></tr>
 228 <tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
 229 <tr><td><tt>options</tt></td><td>Pointer to options</td></tr>
 230 </tbody></table></div>
 231 <h4>Returns</h4>
 232 <p>Number of options</p>
 233 <!-- NEW PAGE -->
 234 <h3 class='title'><a name='cupsCancelJob'>cupsCancelJob()</a></h3>
 235 <h4>Description</h4>
 236 <p>Cancel a print job on the default server.
 237
 238 Use the cupsLastError() and cupsLastErrorString() functions to get
 239 the cause of any failure.</p>
 240 <h4>Syntax</h4>
 241 <pre>
 242 int
 243 cupsCancelJob(
 244     const char * name,
 245     int job);
 246 </pre>
 247 <h4>Arguments</h4>
 248 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 249 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 250 <tbody>
 251 <tr><td><tt>name</tt></td><td>Name of printer or class</td></tr>
 252 <tr><td><tt>job</tt></td><td>Job ID</td></tr>
 253 </tbody></table></div>
 254 <h4>Returns</h4>
 255 <p>1 on success, 0 on failure</p>
 256 <!-- NEW PAGE -->
 257 <h3 class='title'><a name='cupsEncryption'>cupsEncryption()</a></h3>
 258 <h4>Description</h4>
 259 <p>Get the default encryption settings.
 260
 261 The default encryption setting comes from the CUPS_ENCRYPTION
 262 environment variable, then the ~/.cupsrc file, and finally the
 263 /etc/cups/client.conf file. If not set, the default is
 264 HTTP_ENCRYPT_IF_REQUESTED.</p>
 265 <h4>Syntax</h4>
 266 <pre>
 267 http_encryption_t
 268 cupsEncryption(void);
 269 </pre>
 270 <h4>Arguments</h4>
 271 <p>None.</p>
 272 <h4>Returns</h4>
 273 <p>Encryption settings</p>
 274 <!-- NEW PAGE -->
 275 <h3 class='title'><a name='cupsFreeDests'>cupsFreeDests()</a></h3>
 276 <h4>Description</h4>
 277 <p>Free the memory used by the list of destinations.</p>
 278 <h4>Syntax</h4>
 279 <pre>
 280 void
 281 cupsFreeDests(
 282     int num_dests,
 283     <a href='#cups_dest_t'>cups_dest_t</a> * dests);
 284 </pre>
 285 <h4>Arguments</h4>
 286 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 287 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 288 <tbody>
 289 <tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
 290 <tr><td><tt>dests</tt></td><td>Destinations</td></tr>
 291 </tbody></table></div>
 292 <h4>Returns</h4>
 293 <p>Nothing.</p>
 294 <!-- NEW PAGE -->
 295 <h3 class='title'><a name='cupsFreeJobs'>cupsFreeJobs()</a></h3>
 296 <h4>Description</h4>
 297 <p>Free memory used by job data.</p>
 298 <h4>Syntax</h4>
 299 <pre>
 300 void
 301 cupsFreeJobs(
 302     int num_jobs,
 303     <a href='#cups_job_t'>cups_job_t</a> * jobs);
 304 </pre>
 305 <h4>Arguments</h4>
 306 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 307 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 308 <tbody>
 309 <tr><td><tt>num_jobs</tt></td><td>Number of jobs</td></tr>
 310 <tr><td><tt>jobs</tt></td><td>Jobs</td></tr>
 311 </tbody></table></div>
 312 <h4>Returns</h4>
 313 <p>Nothing.</p>
 314 <!-- NEW PAGE -->
 315 <h3 class='title'><a name='cupsFreeOptions'>cupsFreeOptions()</a></h3>
 316 <h4>Description</h4>
 317 <p>Free all memory used by options.</p>
 318 <h4>Syntax</h4>
 319 <pre>
 320 void
 321 cupsFreeOptions(
 322     int num_options,
 323     <a href='#cups_option_t'>cups_option_t</a> * options);
 324 </pre>
 325 <h4>Arguments</h4>
 326 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 327 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 328 <tbody>
 329 <tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
 330 <tr><td><tt>options</tt></td><td>Pointer to options</td></tr>
 331 </tbody></table></div>
 332 <h4>Returns</h4>
 333 <p>Nothing.</p>
 334 <!-- NEW PAGE -->
 335 <h3 class='title'><span class='info'>&nbsp;DEPRECATED&nbsp;</span><a name='cupsGetClasses'>cupsGetClasses()</a></h3>
 336 <h4>Description</h4>
 337 <p>Get a list of printer classes from the default server.
 338
 339 This function is deprecated - use cupsGetDests() instead.
 340
 341 </p>
 342 <h4>Syntax</h4>
 343 <pre>
 344 int
 345 cupsGetClasses(
 346     char *** classes);
 347 </pre>
 348 <h4>Arguments</h4>
 349 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 350 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 351 <tbody>
 352 <tr><td><tt>classes</tt></td><td>Classes</td></tr>
 353 </tbody></table></div>
 354 <h4>Returns</h4>
 355 <p>Number of classes</p>
 356 <!-- NEW PAGE -->
 357 <h3 class='title'><a name='cupsGetDefault'>cupsGetDefault()</a></h3>
 358 <h4>Description</h4>
 359 <p>Get the default printer or class for the default server.
 360
 361 This function returns the default printer or class as defined by
 362 the LPDEST or PRINTER environment variables. If these environment
 363 variables are not set, the server default destination is returned.
 364 Applications should use the cupsGetDests() and cupsGetDest() functions
 365 to get the user-defined default printer, as this function does not
 366 support the lpoptions-defined default printer.</p>
 367 <h4>Syntax</h4>
 368 <pre>
 369 const char *
 370 cupsGetDefault(void);
 371 </pre>
 372 <h4>Arguments</h4>
 373 <p>None.</p>
 374 <h4>Returns</h4>
 375 <p>Default printer or NULL</p>
 376 <!-- NEW PAGE -->
 377 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsGetDefault2'>cupsGetDefault2()</a></h3>
 378 <h4>Description</h4>
 379 <p>Get the default printer or class for the specified server.
 380
 381 This function returns the default printer or class as defined by
 382 the LPDEST or PRINTER environment variables. If these environment
 383 variables are not set, the server default destination is returned.
 384 Applications should use the cupsGetDests() and cupsGetDest() functions
 385 to get the user-defined default printer, as this function does not
 386 support the lpoptions-defined default printer.
 387
 388 </p>
 389 <h4>Syntax</h4>
 390 <pre>
 391 const char *
 392 cupsGetDefault2(
 393     http_t * http);
 394 </pre>
 395 <h4>Arguments</h4>
 396 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 397 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 398 <tbody>
 399 <tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
 400 </tbody></table></div>
 401 <h4>Returns</h4>
 402 <p>Default printer or NULL</p>
 403 <!-- NEW PAGE -->
 404 <h3 class='title'><a name='cupsGetDest'>cupsGetDest()</a></h3>
 405 <h4>Description</h4>
 406 <p>Get the named destination from the list.
 407
 408 Use the cupsGetDests() or cupsGetDests2() functions to get a
 409 list of supported destinations for the current user.</p>
 410 <h4>Syntax</h4>
 411 <pre>
 412 <a href='#cups_dest_t'>cups_dest_t</a> *
 413 cupsGetDest(
 414     const char * name,
 415     const char * instance,
 416     int num_dests,
 417     <a href='#cups_dest_t'>cups_dest_t</a> * dests);
 418 </pre>
 419 <h4>Arguments</h4>
 420 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 421 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 422 <tbody>
 423 <tr><td><tt>name</tt></td><td>Destination name or NULL for the default destination</td></tr>
 424 <tr><td><tt>instance</tt></td><td>Instance name or NULL</td></tr>
 425 <tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
 426 <tr><td><tt>dests</tt></td><td>Destinations</td></tr>
 427 </tbody></table></div>
 428 <h4>Returns</h4>
 429 <p>Destination pointer or NULL</p>
 430 <!-- NEW PAGE -->
 431 <h3 class='title'><a name='cupsGetDests'>cupsGetDests()</a></h3>
 432 <h4>Description</h4>
 433 <p>Get the list of destinations from the default server.
 434
 435 Starting with CUPS 1.2, the returned list of destinations include the
 436 printer-info, printer-is-accepting-jobs, printer-is-shared,
 437 printer-make-and-model, printer-state, printer-state-change-time,
 438 printer-state-reasons, and printer-type attributes as options.
 439
 440 Use the cupsFreeDests() function to free the destination list and
 441 the cupsGetDest() function to find a particular destination.</p>
 442 <h4>Syntax</h4>
 443 <pre>
 444 int
 445 cupsGetDests(
 446     <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
 447 </pre>
 448 <h4>Arguments</h4>
 449 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 450 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 451 <tbody>
 452 <tr><td><tt>dests</tt></td><td>Destinations</td></tr>
 453 </tbody></table></div>
 454 <h4>Returns</h4>
 455 <p>Number of destinations</p>
 456 <!-- NEW PAGE -->
 457 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsGetDests2'>cupsGetDests2()</a></h3>
 458 <h4>Description</h4>
 459 <p>Get the list of destinations from the specified server.
 460
 461 Starting with CUPS 1.2, the returned list of destinations include the
 462 printer-info, printer-is-accepting-jobs, printer-is-shared,
 463 printer-make-and-model, printer-state, printer-state-change-time,
 464 printer-state-reasons, and printer-type attributes as options.
 465
 466 Use the cupsFreeDests() function to free the destination list and
 467 the cupsGetDest() function to find a particular destination.
 468
 469 </p>
 470 <h4>Syntax</h4>
 471 <pre>
 472 int
 473 cupsGetDests2(
 474     http_t * http,
 475     <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
 476 </pre>
 477 <h4>Arguments</h4>
 478 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 479 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 480 <tbody>
 481 <tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
 482 <tr><td><tt>dests</tt></td><td>Destinations</td></tr>
 483 </tbody></table></div>
 484 <h4>Returns</h4>
 485 <p>Number of destinations</p>
 486 <!-- NEW PAGE -->
 487 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span><a name='cupsGetFd'>cupsGetFd()</a></h3>
 488 <h4>Description</h4>
 489 <p>Get a file from the server.
 490
 491 This function returns HTTP_OK when the file is successfully retrieved.
 492
 493 </p>
 494 <h4>Syntax</h4>
 495 <pre>
 496 http_status_t
 497 cupsGetFd(
 498     http_t * http,
 499     const char * resource,
 500     int fd);
 501 </pre>
 502 <h4>Arguments</h4>
 503 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 504 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 505 <tbody>
 506 <tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
 507 <tr><td><tt>resource</tt></td><td>Resource name</td></tr>
 508 <tr><td><tt>fd</tt></td><td>File descriptor</td></tr>
 509 </tbody></table></div>
 510 <h4>Returns</h4>
 511 <p>HTTP status</p>
 512 <!-- NEW PAGE -->
 513 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span><a name='cupsGetFile'>cupsGetFile()</a></h3>
 514 <h4>Description</h4>
 515 <p>Get a file from the server.
 516
 517 This function returns HTTP_OK when the file is successfully retrieved.
 518
 519 </p>
 520 <h4>Syntax</h4>
 521 <pre>
 522 http_status_t
 523 cupsGetFile(
 524     http_t * http,
 525     const char * resource,
 526     const char * filename);
 527 </pre>
 528 <h4>Arguments</h4>
 529 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 530 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 531 <tbody>
 532 <tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
 533 <tr><td><tt>resource</tt></td><td>Resource name</td></tr>
 534 <tr><td><tt>filename</tt></td><td>Filename</td></tr>
 535 </tbody></table></div>
 536 <h4>Returns</h4>
 537 <p>HTTP status</p>
 538 <!-- NEW PAGE -->
 539 <h3 class='title'><a name='cupsGetJobs'>cupsGetJobs()</a></h3>
 540 <h4>Description</h4>
 541 <p>Get the jobs from the default server.</p>
 542 <h4>Syntax</h4>
 543 <pre>
 544 int
 545 cupsGetJobs(
 546     <a href='#cups_job_t'>cups_job_t</a> ** jobs,
 547     const char * mydest,
 548     int myjobs,
 549     int completed);
 550 </pre>
 551 <h4>Arguments</h4>
 552 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 553 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 554 <tbody>
 555 <tr><td><tt>jobs</tt></td><td>Job data</td></tr>
 556 <tr><td><tt>mydest</tt></td><td>NULL = all destinations,       *
 557 otherwise show jobs for mydest</td></tr>
 558 <tr><td><tt>myjobs</tt></td><td>0 = all users, 1 = mine</td></tr>
 559 <tr><td><tt>completed</tt></td><td>-1 = show all, 0 = active, *
 560 1 = completed jobs</td></tr>
 561 </tbody></table></div>
 562 <h4>Returns</h4>
 563 <p>Number of jobs</p>
 564 <!-- NEW PAGE -->
 565 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsGetJobs2'>cupsGetJobs2()</a></h3>
 566 <h4>Description</h4>
 567 <p>Get the jobs from the specified server.
 568
 569 </p>
 570 <h4>Syntax</h4>
 571 <pre>
 572 int
 573 cupsGetJobs2(
 574     http_t * http,
 575     <a href='#cups_job_t'>cups_job_t</a> ** jobs,
 576     const char * mydest,
 577     int myjobs,
 578     int completed);
 579 </pre>
 580 <h4>Arguments</h4>
 581 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 582 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 583 <tbody>
 584 <tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
 585 <tr><td><tt>jobs</tt></td><td>Job data</td></tr>
 586 <tr><td><tt>mydest</tt></td><td>NULL = all destinations,       *
 587 otherwise show jobs for mydest</td></tr>
 588 <tr><td><tt>myjobs</tt></td><td>0 = all users, 1 = mine</td></tr>
 589 <tr><td><tt>completed</tt></td><td>-1 = show all, 0 = active, *
 590 1 = completed jobs</td></tr>
 591 </tbody></table></div>
 592 <h4>Returns</h4>
 593 <p>Number of jobs</p>
 594 <!-- NEW PAGE -->
 595 <h3 class='title'><a name='cupsGetOption'>cupsGetOption()</a></h3>
 596 <h4>Description</h4>
 597 <p>Get an option value.</p>
 598 <h4>Syntax</h4>
 599 <pre>
 600 const char *
 601 cupsGetOption(
 602     const char * name,
 603     int num_options,
 604     <a href='#cups_option_t'>cups_option_t</a> * options);
 605 </pre>
 606 <h4>Arguments</h4>
 607 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 608 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 609 <tbody>
 610 <tr><td><tt>name</tt></td><td>Name of option</td></tr>
 611 <tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
 612 <tr><td><tt>options</tt></td><td>Options</td></tr>
 613 </tbody></table></div>
 614 <h4>Returns</h4>
 615 <p>Option value or NULL</p>
 616 <!-- NEW PAGE -->
 617 <h3 class='title'><a name='cupsGetPPD'>cupsGetPPD()</a></h3>
 618 <h4>Description</h4>
 619 <p>Get the PPD file for a printer on the default server.
 620
 621 For classes, cupsGetPPD() returns the PPD file for the first printer
 622 in the class.</p>
 623 <h4>Syntax</h4>
 624 <pre>
 625 const char *
 626 cupsGetPPD(
 627     const char * name);
 628 </pre>
 629 <h4>Arguments</h4>
 630 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 631 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 632 <tbody>
 633 <tr><td><tt>name</tt></td><td>Printer name</td></tr>
 634 </tbody></table></div>
 635 <h4>Returns</h4>
 636 <p>Filename for PPD file</p>
 637 <!-- NEW PAGE -->
 638 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsGetPPD2'>cupsGetPPD2()</a></h3>
 639 <h4>Description</h4>
 640 <p>Get the PPD file for a printer from the specified server.
 641
 642 For classes, cupsGetPPD2() returns the PPD file for the first printer
 643 in the class.
 644
 645 </p>
 646 <h4>Syntax</h4>
 647 <pre>
 648 const char *
 649 cupsGetPPD2(
 650     http_t * http,
 651     const char * name);
 652 </pre>
 653 <h4>Arguments</h4>
 654 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 655 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 656 <tbody>
 657 <tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
 658 <tr><td><tt>name</tt></td><td>Printer name</td></tr>
 659 </tbody></table></div>
 660 <h4>Returns</h4>
 661 <p>Filename for PPD file</p>
 662 <!-- NEW PAGE -->
 663 <h3 class='title'><a name='cupsGetPassword'>cupsGetPassword()</a></h3>
 664 <h4>Description</h4>
 665 <p>Get a password from the user.
 666
 667 Uses the current password callback function. Returns NULL if the
 668 user does not provide a password.</p>
 669 <h4>Syntax</h4>
 670 <pre>
 671 const char *
 672 cupsGetPassword(
 673     const char * prompt);
 674 </pre>
 675 <h4>Arguments</h4>
 676 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 677 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 678 <tbody>
 679 <tr><td><tt>prompt</tt></td><td>Prompt string</td></tr>
 680 </tbody></table></div>
 681 <h4>Returns</h4>
 682 <p>Password</p>
 683 <!-- NEW PAGE -->
 684 <h3 class='title'><span class='info'>&nbsp;DEPRECATED&nbsp;</span><a name='cupsGetPrinters'>cupsGetPrinters()</a></h3>
 685 <h4>Description</h4>
 686 <p>Get a list of printers from the default server.
 687
 688 This function is deprecated - use cupsGetDests() instead.
 689
 690 </p>
 691 <h4>Syntax</h4>
 692 <pre>
 693 int
 694 cupsGetPrinters(
 695     char *** printers);
 696 </pre>
 697 <h4>Arguments</h4>
 698 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 699 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 700 <tbody>
 701 <tr><td><tt>printers</tt></td><td>Printers</td></tr>
 702 </tbody></table></div>
 703 <h4>Returns</h4>
 704 <p>Number of printers</p>
 705 <!-- NEW PAGE -->
 706 <h3 class='title'><a name='cupsLangDefault'>cupsLangDefault()</a></h3>
 707 <h4>Description</h4>
 708 <p>Return the default language.</p>
 709 <h4>Syntax</h4>
 710 <pre>
 711 cups_lang_t *
 712 cupsLangDefault(void);
 713 </pre>
 714 <h4>Arguments</h4>
 715 <p>None.</p>
 716 <h4>Returns</h4>
 717 <p>Language data</p>
 718 <!-- NEW PAGE -->
 719 <h3 class='title'><a name='cupsLangEncoding'>cupsLangEncoding()</a></h3>
 720 <h4>Description</h4>
 721 <p>Return the character encoding (us-ascii, etc.)
 722 for the given language.</p>
 723 <h4>Syntax</h4>
 724 <pre>
 725 const char *
 726 cupsLangEncoding(
 727     cups_lang_t * lang);
 728 </pre>
 729 <h4>Arguments</h4>
 730 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 731 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 732 <tbody>
 733 <tr><td><tt>lang</tt></td><td>Language data</td></tr>
 734 </tbody></table></div>
 735 <h4>Returns</h4>
 736 <p>Character encoding</p>
 737 <!-- NEW PAGE -->
 738 <h3 class='title'><a name='cupsLangFlush'>cupsLangFlush()</a></h3>
 739 <h4>Description</h4>
 740 <p>Flush all language data out of the cache.</p>
 741 <h4>Syntax</h4>
 742 <pre>
 743 void
 744 cupsLangFlush(void);
 745 </pre>
 746 <h4>Arguments</h4>
 747 <p>None.</p>
 748 <h4>Returns</h4>
 749 <p>Nothing.</p>
 750 <!-- NEW PAGE -->
 751 <h3 class='title'><a name='cupsLangFree'>cupsLangFree()</a></h3>
 752 <h4>Description</h4>
 753 <p>Free language data.
 754
 755 This does not actually free anything; use cupsLangFlush() for that.</p>
 756 <h4>Syntax</h4>
 757 <pre>
 758 void
 759 cupsLangFree(
 760     cups_lang_t * lang);
 761 </pre>
 762 <h4>Arguments</h4>
 763 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 764 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 765 <tbody>
 766 <tr><td><tt>lang</tt></td><td>Language to free</td></tr>
 767 </tbody></table></div>
 768 <h4>Returns</h4>
 769 <p>Nothing.</p>
 770 <!-- NEW PAGE -->
 771 <h3 class='title'><a name='cupsLangGet'>cupsLangGet()</a></h3>
 772 <h4>Description</h4>
 773 <p>Get a language.</p>
 774 <h4>Syntax</h4>
 775 <pre>
 776 cups_lang_t *
 777 cupsLangGet(
 778     const char * language);
 779 </pre>
 780 <h4>Arguments</h4>
 781 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 782 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 783 <tbody>
 784 <tr><td><tt>language</tt></td><td>Language or locale</td></tr>
 785 </tbody></table></div>
 786 <h4>Returns</h4>
 787 <p>Language data</p>
 788 <!-- NEW PAGE -->
 789 <h3 class='title'><a name='cupsLastError'>cupsLastError()</a></h3>
 790 <h4>Description</h4>
 791 <p>Return the last IPP status code.</p>
 792 <h4>Syntax</h4>
 793 <pre>
 794 ipp_status_t
 795 cupsLastError(void);
 796 </pre>
 797 <h4>Arguments</h4>
 798 <p>None.</p>
 799 <h4>Returns</h4>
 800 <p>IPP status code from last request</p>
 801 <!-- NEW PAGE -->
 802 <h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsLastErrorString'>cupsLastErrorString()</a></h3>
 803 <h4>Description</h4>
 804 <p>Return the last IPP status-message.
 805
 806 </p>
 807 <h4>Syntax</h4>
 808 <pre>
 809 const char *
 810 cupsLastErrorString(void);
 811 </pre>
 812 <h4>Arguments</h4>
 813 <p>None.</p>
 814 <h4>Returns</h4>
 815 <p>status-message text from last request</p>
 816 <!-- NEW PAGE -->
 817 <h3 class='title'><a name='cupsMarkOptions'>cupsMarkOptions()</a></h3>
 818 <h4>Description</h4>
 819 <p>Mark command-line options in a PPD file.</p>
 820 <h4>Syntax</h4>
 821 <pre>
 822 int
 823 cupsMarkOptions(
 824     ppd_file_t * ppd,
 825     int num_options,
 826     <a href='#cups_option_t'>cups_option_t</a> * options);
 827 </pre>
 828 <h4>Arguments</h4>
 829 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 830 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 831 <tbody>
 832 <tr><td><tt>ppd</tt></td><td>PPD file</td></tr>
 833 <tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
 834 <tr><td><tt>options</tt></td><td>Options</td></tr>
 835 </tbody></table></div>
 836 <h4>Returns</h4>
 837 <p>1 if conflicting</p>
 838 <!-- NEW PAGE -->
 839 <h3 class='title'><a name='cupsParseOptions'>cupsParseOptions()</a></h3>
 840 <h4>Description</h4>
 841 <p>Parse options from a command-line argument.
 842
 843 This function converts space-delimited name/value pairs according
 844 to the PAPI text option ABNF specification. Collection values
 845 (&quot;name={a=... b=... c=...}&quot;) are stored with the curley brackets
 846 intact - use cupsParseOptions() on the value to extract the collection
 847 attributes.</p>
 848 <h4>Syntax</h4>
 849 <pre>
 850 int
 851 cupsParseOptions(
 852     const char * arg,
 853     int num_options,
 854     <a href='#cups_option_t'>cups_option_t</a> ** options);
 855 </pre>
 856 <h4>Arguments</h4>
 857 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 858 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 859 <tbody>
 860 <tr><td><tt>arg</tt></td><td>Argument to parse</td></tr>
 861 <tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
 862 <tr><td><tt>options</tt></td><td>Options found</td></tr>
 863 </tbody></table></div>
 864 <h4>Returns</h4>
 865 <p>Number of options found</p>
 866 <!-- NEW PAGE -->
 867 <h3 class='title'><a name='cupsPrintFile'>cupsPrintFile()</a></h3>
 868 <h4>Description</h4>
 869 <p>Print a file to a printer or class on the default server.</p>
 870 <h4>Syntax</h4>
 871 <pre>
 872 int
 873 cupsPrintFile(
 874     const char * name,
 875     const char * filename,
 876     const char * title,
 877     int num_options,
 878     <a href='#cups_option_t'>cups_option_t</a> * options);
 879 </pre>
 880 <h4>Arguments</h4>
 881 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 882 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 883 <tbody>
 884 <tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
 885 <tr><td><tt>filename</tt></td><td>File to print</td></tr>
 886 <tr><td><tt>title</tt></td><td>Title of job</td></tr>
 887 <tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
 888 <tr><td><tt>options</tt></td><td>Options</td></tr>
 889 </tbody></table></div>
 890 <h4>Returns</h4>
 891 <p>Job ID</p>
 892 <!-- NEW PAGE -->
 893 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsPrintFile2'>cupsPrintFile2()</a></h3>
 894 <h4>Description</h4>
 895 <p>Print a file to a printer or class on the specified server.
 896
 897 </p>
 898 <h4>Syntax</h4>
 899 <pre>
 900 int
 901 cupsPrintFile2(
 902     http_t * http,
 903     const char * name,
 904     const char * filename,
 905     const char * title,
 906     int num_options,
 907     <a href='#cups_option_t'>cups_option_t</a> * options);
 908 </pre>
 909 <h4>Arguments</h4>
 910 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 911 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 912 <tbody>
 913 <tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
 914 <tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
 915 <tr><td><tt>filename</tt></td><td>File to print</td></tr>
 916 <tr><td><tt>title</tt></td><td>Title of job</td></tr>
 917 <tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
 918 <tr><td><tt>options</tt></td><td>Options</td></tr>
 919 </tbody></table></div>
 920 <h4>Returns</h4>
 921 <p>Job ID</p>
 922 <!-- NEW PAGE -->
 923 <h3 class='title'><a name='cupsPrintFiles'>cupsPrintFiles()</a></h3>
 924 <h4>Description</h4>
 925 <p>Print one or more files to a printer or class on the
 926 default server.</p>
 927 <h4>Syntax</h4>
 928 <pre>
 929 int
 930 cupsPrintFiles(
 931     const char * name,
 932     int num_files,
 933     const char ** files,
 934     const char * title,
 935     int num_options,
 936     <a href='#cups_option_t'>cups_option_t</a> * options);
 937 </pre>
 938 <h4>Arguments</h4>
 939 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 940 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 941 <tbody>
 942 <tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
 943 <tr><td><tt>num_files</tt></td><td>Number of files</td></tr>
 944 <tr><td><tt>files</tt></td><td>File(s) to print</td></tr>
 945 <tr><td><tt>title</tt></td><td>Title of job</td></tr>
 946 <tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
 947 <tr><td><tt>options</tt></td><td>Options</td></tr>
 948 </tbody></table></div>
 949 <h4>Returns</h4>
 950 <p>Job ID</p>
 951 <!-- NEW PAGE -->
 952 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsPrintFiles2'>cupsPrintFiles2()</a></h3>
 953 <h4>Description</h4>
 954 <p>Print one or more files to a printer or class on the
 955 specified server.
 956
 957 </p>
 958 <h4>Syntax</h4>
 959 <pre>
 960 int
 961 cupsPrintFiles2(
 962     http_t * http,
 963     const char * name,
 964     int num_files,
 965     const char ** files,
 966     const char * title,
 967     int num_options,
 968     <a href='#cups_option_t'>cups_option_t</a> * options);
 969 </pre>
 970 <h4>Arguments</h4>
 971 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 972 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 973 <tbody>
 974 <tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
 975 <tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
 976 <tr><td><tt>num_files</tt></td><td>Number of files</td></tr>
 977 <tr><td><tt>files</tt></td><td>File(s) to print</td></tr>
 978 <tr><td><tt>title</tt></td><td>Title of job</td></tr>
 979 <tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
 980 <tr><td><tt>options</tt></td><td>Options</td></tr>
 981 </tbody></table></div>
 982 <h4>Returns</h4>
 983 <p>Job ID</p>
 984 <!-- NEW PAGE -->
 985 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span><a name='cupsPutFd'>cupsPutFd()</a></h3>
 986 <h4>Description</h4>
 987 <p>Put a file on the server.
 988
 989 This function returns HTTP_CREATED when the file is stored successfully.
 990
 991 </p>
 992 <h4>Syntax</h4>
 993 <pre>
 994 http_status_t
 995 cupsPutFd(
 996     http_t * http,
 997     const char * resource,
 998     int fd);
 999 </pre>
1000 <h4>Arguments</h4>
1001 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1002 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1003 <tbody>
1004 <tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
1005 <tr><td><tt>resource</tt></td><td>Resource name</td></tr>
1006 <tr><td><tt>fd</tt></td><td>File descriptor</td></tr>
1007 </tbody></table></div>
1008 <h4>Returns</h4>
1009 <p>HTTP status</p>
1010 <!-- NEW PAGE -->
1011 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span><a name='cupsPutFile'>cupsPutFile()</a></h3>
1012 <h4>Description</h4>
1013 <p>Put a file on the server.
1014
1015 This function returns HTTP_CREATED when the file is stored successfully.
1016
1017 </p>
1018 <h4>Syntax</h4>
1019 <pre>
1020 http_status_t
1021 cupsPutFile(
1022     http_t * http,
1023     const char * resource,
1024     const char * filename);
1025 </pre>
1026 <h4>Arguments</h4>
1027 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1028 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1029 <tbody>
1030 <tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
1031 <tr><td><tt>resource</tt></td><td>Resource name</td></tr>
1032 <tr><td><tt>filename</tt></td><td>Filename</td></tr>
1033 </tbody></table></div>
1034 <h4>Returns</h4>
1035 <p>HTTP status</p>
1036 <!-- NEW PAGE -->
1037 <h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsRemoveOption'>cupsRemoveOption()</a></h3>
1038 <h4>Description</h4>
1039 <p>Remove an option from an option array.
1040
1041 </p>
1042 <h4>Syntax</h4>
1043 <pre>
1044 int
1045 cupsRemoveOption(
1046     const char * name,
1047     int num_options,
1048     <a href='#cups_option_t'>cups_option_t</a> ** options);
1049 </pre>
1050 <h4>Arguments</h4>
1051 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1052 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1053 <tbody>
1054 <tr><td><tt>name</tt></td><td>Option name</td></tr>
1055 <tr><td><tt>num_options</tt></td><td>Current number of options</td></tr>
1056 <tr><td><tt>options</tt></td><td>Options</td></tr>
1057 </tbody></table></div>
1058 <h4>Returns</h4>
1059 <p>New number of options</p>
1060 <!-- NEW PAGE -->
1061 <h3 class='title'><a name='cupsServer'>cupsServer()</a></h3>
1062 <h4>Description</h4>
1063 <p>Return the hostname/address of the default server.
1064
1065 The returned value can be a fully-qualified hostname, a numeric
1066 IPv4 or IPv6 address, or a domain socket pathname.</p>
1067 <h4>Syntax</h4>
1068 <pre>
1069 const char *
1070 cupsServer(void);
1071 </pre>
1072 <h4>Arguments</h4>
1073 <p>None.</p>
1074 <h4>Returns</h4>
1075 <p>Server name</p>
1076 <!-- NEW PAGE -->
1077 <h3 class='title'><a name='cupsSetDests'>cupsSetDests()</a></h3>
1078 <h4>Description</h4>
1079 <p>Save the list of destinations for the default server.
1080
1081 This function saves the destinations to /etc/cups/lpoptions when run
1082 as root and ~/.cups/lpoptions when run as a normal user.</p>
1083 <h4>Syntax</h4>
1084 <pre>
1085 void
1086 cupsSetDests(
1087     int num_dests,
1088     <a href='#cups_dest_t'>cups_dest_t</a> * dests);
1089 </pre>
1090 <h4>Arguments</h4>
1091 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1092 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1093 <tbody>
1094 <tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
1095 <tr><td><tt>dests</tt></td><td>Destinations</td></tr>
1096 </tbody></table></div>
1097 <h4>Returns</h4>
1098 <p>Nothing.</p>
1099 <!-- NEW PAGE -->
1100 <h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsSetDests2'>cupsSetDests2()</a></h3>
1101 <h4>Description</h4>
1102 <p>Save the list of destinations for the specified server.
1103
1104 This function saves the destinations to /etc/cups/lpoptions when run
1105 as root and ~/.cups/lpoptions when run as a normal user.
1106
1107 </p>
1108 <h4>Syntax</h4>
1109 <pre>
1110 int
1111 cupsSetDests2(
1112     http_t * http,
1113     int num_dests,
1114     <a href='#cups_dest_t'>cups_dest_t</a> * dests);
1115 </pre>
1116 <h4>Arguments</h4>
1117 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1118 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1119 <tbody>
1120 <tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
1121 <tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
1122 <tr><td><tt>dests</tt></td><td>Destinations</td></tr>
1123 </tbody></table></div>
1124 <h4>Returns</h4>
1125 <p>0 on success, -1 on error</p>
1126 <!-- NEW PAGE -->
1127 <h3 class='title'><a name='cupsSetEncryption'>cupsSetEncryption()</a></h3>
1128 <h4>Description</h4>
1129 <p>Set the encryption preference.</p>
1130 <h4>Syntax</h4>
1131 <pre>
1132 void
1133 cupsSetEncryption(
1134     http_encryption_t e);
1135 </pre>
1136 <h4>Arguments</h4>
1137 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1138 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1139 <tbody>
1140 <tr><td><tt>e</tt></td><td>New encryption preference</td></tr>
1141 </tbody></table></div>
1142 <h4>Returns</h4>
1143 <p>Nothing.</p>
1144 <!-- NEW PAGE -->
1145 <h3 class='title'><a name='cupsSetPasswordCB'>cupsSetPasswordCB()</a></h3>
1146 <h4>Description</h4>
1147 <p>Set the password callback for CUPS.
1148
1149 Pass NULL to restore the default (console) password callback.</p>
1150 <h4>Syntax</h4>
1151 <pre>
1152 void
1153 cupsSetPasswordCB(
1154     <a href='#cups_password_cb_t'>cups_password_cb_t</a> cb);
1155 </pre>
1156 <h4>Arguments</h4>
1157 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1158 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1159 <tbody>
1160 <tr><td><tt>cb</tt></td><td>Callback function</td></tr>
1161 </tbody></table></div>
1162 <h4>Returns</h4>
1163 <p>Nothing.</p>
1164 <!-- NEW PAGE -->
1165 <h3 class='title'><a name='cupsSetServer'>cupsSetServer()</a></h3>
1166 <h4>Description</h4>
1167 <p>Set the default server name.
1168
1169 The &quot;server&quot; string can be a fully-qualified hostname, a numeric
1170 IPv4 or IPv6 address, or a domain socket pathname. Pass NULL to
1171 restore the default server name.</p>
1172 <h4>Syntax</h4>
1173 <pre>
1174 void
1175 cupsSetServer(
1176     const char * server);
1177 </pre>
1178 <h4>Arguments</h4>
1179 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1180 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1181 <tbody>
1182 <tr><td><tt>server</tt></td><td>Server name</td></tr>
1183 </tbody></table></div>
1184 <h4>Returns</h4>
1185 <p>Nothing.</p>
1186 <!-- NEW PAGE -->
1187 <h3 class='title'><a name='cupsSetUser'>cupsSetUser()</a></h3>
1188 <h4>Description</h4>
1189 <p>Set the default user name.
1190
1191 Pass NULL to restore the default user name.</p>
1192 <h4>Syntax</h4>
1193 <pre>
1194 void
1195 cupsSetUser(
1196     const char * user);
1197 </pre>
1198 <h4>Arguments</h4>
1199 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1200 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1201 <tbody>
1202 <tr><td><tt>user</tt></td><td>User name</td></tr>
1203 </tbody></table></div>
1204 <h4>Returns</h4>
1205 <p>Nothing.</p>
1206 <!-- NEW PAGE -->
1207 <h3 class='title'><a name='cupsTempFd'>cupsTempFd()</a></h3>
1208 <h4>Description</h4>
1209 <p>Creates a temporary file.
1210
1211 The temporary filename is returned in the filename buffer.
1212 The temporary file is opened for reading and writing.</p>
1213 <h4>Syntax</h4>
1214 <pre>
1215 int
1216 cupsTempFd(
1217     char * filename,
1218     int len);
1219 </pre>
1220 <h4>Arguments</h4>
1221 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1222 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1223 <tbody>
1224 <tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
1225 <tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
1226 </tbody></table></div>
1227 <h4>Returns</h4>
1228 <p>New file descriptor or -1 on error</p>
1229 <!-- NEW PAGE -->
1230 <h3 class='title'><span class='info'>&nbsp;DEPRECATED&nbsp;</span><a name='cupsTempFile'>cupsTempFile()</a></h3>
1231 <h4>Description</h4>
1232 <p>Generates a temporary filename.
1233
1234 The temporary filename is returned in the filename buffer.
1235 This function is deprecated - use cupsTempFd() or cupsTempFile2()
1236 instead.
1237
1238 </p>
1239 <h4>Syntax</h4>
1240 <pre>
1241 char *
1242 cupsTempFile(
1243     char * filename,
1244     int len);
1245 </pre>
1246 <h4>Arguments</h4>
1247 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1248 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1249 <tbody>
1250 <tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
1251 <tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
1252 </tbody></table></div>
1253 <h4>Returns</h4>
1254 <p>Filename or NULL on error</p>
1255 <!-- NEW PAGE -->
1256 <h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsTempFile2'>cupsTempFile2()</a></h3>
1257 <h4>Description</h4>
1258 <p>Creates a temporary CUPS file.
1259
1260 The temporary filename is returned in the filename buffer.
1261 The temporary file is opened for writing.
1262
1263 </p>
1264 <h4>Syntax</h4>
1265 <pre>
1266 cups_file_t *
1267 cupsTempFile2(
1268     char * filename,
1269     int len);
1270 </pre>
1271 <h4>Arguments</h4>
1272 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1273 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1274 <tbody>
1275 <tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
1276 <tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
1277 </tbody></table></div>
1278 <h4>Returns</h4>
1279 <p>CUPS file or NULL on error</p>
1280 <!-- NEW PAGE -->
1281 <h3 class='title'><a name='cupsUser'>cupsUser()</a></h3>
1282 <h4>Description</h4>
1283 <p>Return the current user's name.</p>
1284 <h4>Syntax</h4>
1285 <pre>
1286 const char *
1287 cupsUser(void);
1288 </pre>
1289 <h4>Arguments</h4>
1290 <p>None.</p>
1291 <h4>Returns</h4>
1292 <p>User name</p>
1293 <!-- NEW PAGE -->
1294 <h2 class='title'><a name='STRUCTURES'>Structures</a></h2>
1295 <ul>
1296         <li><a href='#cups_dest_s'><tt>cups_dest_s</tt></a> </li>
1297         <li><a href='#cups_job_s'><tt>cups_job_s</tt></a> </li>
1298         <li><a href='#cups_option_s'><tt>cups_option_s</tt></a> </li>
1299 </ul>
1300 <!-- NEW PAGE -->
1301 <h3 class='title'><a name='cups_dest_s'>cups_dest_s</a></h3>
1302 <h4>Description</h4>
1303 <p>Destination</p>
1304 <h4>Definition</h4>
1305 <pre>
1306 struct cups_dest_s
1307 {
1308   char *name, * instance;
1309   int is_default;
1310   int num_options;
1311   <a href='#cups_option_t'>cups_option_t</a> * options;
1312 };
1313 </pre>
1314 <h4>Members</h4>
1315 <div class='table'><table align='center' border='1' width='80%'>
1316 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1317 <tbody>
1318 <tr><td><tt>instance</tt> </td><td>Local instance name or NULL</td></tr>
1319 <tr><td><tt>is_default</tt> </td><td>Is this printer the default?</td></tr>
1320 <tr><td><tt>num_options</tt> </td><td>Number of options</td></tr>
1321 <tr><td><tt>options</tt> </td><td>Options</td></tr>
1322 </tbody></table></div>
1323 <!-- NEW PAGE -->
1324 <h3 class='title'><a name='cups_job_s'>cups_job_s</a></h3>
1325 <h4>Description</h4>
1326 <p>Job</p>
1327 <h4>Definition</h4>
1328 <pre>
1329 struct cups_job_s
1330 {
1331   time_t completed_time;
1332   time_t creation_time;
1333   char * dest;
1334   char * format;
1335   int id;
1336   int priority;
1337   time_t processing_time;
1338   int size;
1339   ipp_jstate_t state;
1340   char * title;
1341   char * user;
1342 };
1343 </pre>
1344 <h4>Members</h4>
1345 <div class='table'><table align='center' border='1' width='80%'>
1346 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1347 <tbody>
1348 <tr><td><tt>completed_time</tt> </td><td>Time the job was completed</td></tr>
1349 <tr><td><tt>creation_time</tt> </td><td>Time the job was created</td></tr>
1350 <tr><td><tt>dest</tt> </td><td>Printer or class name</td></tr>
1351 <tr><td><tt>format</tt> </td><td>Document format</td></tr>
1352 <tr><td><tt>id</tt> </td><td>The job ID</td></tr>
1353 <tr><td><tt>priority</tt> </td><td>Priority (1-100)</td></tr>
1354 <tr><td><tt>processing_time</tt> </td><td>Time the job was processed</td></tr>
1355 <tr><td><tt>size</tt> </td><td>Size in kilobytes</td></tr>
1356 <tr><td><tt>state</tt> </td><td>Job state</td></tr>
1357 <tr><td><tt>title</tt> </td><td>Title/job name</td></tr>
1358 <tr><td><tt>user</tt> </td><td>User the submitted the job</td></tr>
1359 </tbody></table></div>
1360 <!-- NEW PAGE -->
1361 <h3 class='title'><a name='cups_option_s'>cups_option_s</a></h3>
1362 <h4>Description</h4>
1363 <p>Printer Options</p>
1364 <h4>Definition</h4>
1365 <pre>
1366 struct cups_option_s
1367 {
1368   char * name;
1369   char * value;
1370 };
1371 </pre>
1372 <h4>Members</h4>
1373 <div class='table'><table align='center' border='1' width='80%'>
1374 <thead><tr><th>Name</th><th>Description</th></tr></thead>
1375 <tbody>
1376 <tr><td><tt>name</tt> </td><td>Name of option</td></tr>
1377 <tr><td><tt>value</tt> </td><td>Value of option</td></tr>
1378 </tbody></table></div>
1379 <!-- NEW PAGE -->
1380 <h2 class='title'><a name='TYPES'>Types</a></h2>
1381 <ul>
1382         <li><a href='#cups_dest_t'><tt>cups_dest_t</tt></a> </li>
1383         <li><a href='#cups_job_t'><tt>cups_job_t</tt></a> </li>
1384         <li><a href='#cups_option_t'><tt>cups_option_t</tt></a> </li>
1385         <li><a href='#cups_password_cb_t'><tt>cups_password_cb_t</tt></a> </li>
1386         <li><a href='#cups_ptype_t'><tt>cups_ptype_t</tt></a> </li>
1387 </ul>
1388 <!-- NEW PAGE -->
1389 <h3 class='title'><a name='cups_dest_t'>cups_dest_t</a></h3>
1390 <h4>Description</h4>
1391 <p>Destination</p>
1392 <h4>Definition</h4>
1393 <pre>
1394 typedef struct <a href='#cups_dest_s'>cups_dest_s</a> cups_dest_t;
1395 </pre>
1396 <!-- NEW PAGE -->
1397 <h3 class='title'><a name='cups_job_t'>cups_job_t</a></h3>
1398 <h4>Description</h4>
1399 <p>Job</p>
1400 <h4>Definition</h4>
1401 <pre>
1402 typedef struct <a href='#cups_job_s'>cups_job_s</a> cups_job_t;
1403 </pre>
1404 <!-- NEW PAGE -->
1405 <h3 class='title'><a name='cups_option_t'>cups_option_t</a></h3>
1406 <h4>Description</h4>
1407 <p>Printer Options</p>
1408 <h4>Definition</h4>
1409 <pre>
1410 typedef struct <a href='#cups_option_s'>cups_option_s</a> cups_option_t;
1411 </pre>
1412 <!-- NEW PAGE -->
1413 <h3 class='title'><a name='cups_password_cb_t'>cups_password_cb_t</a></h3>
1414 <h4>Description</h4>
1415 <p>Password callback</p>
1416 <h4>Definition</h4>
1417 <pre>
1418 typedef const char * (*cups_password_cb_t)(const char *);
1419 </pre>
1420 <!-- NEW PAGE -->
1421 <h3 class='title'><a name='cups_ptype_t'>cups_ptype_t</a></h3>
1422 <h4>Description</h4>
1423 <p>Printer Type/Capability Bits</p>
1424 <h4>Definition</h4>
1425 <pre>
1426 typedef unsigned cups_ptype_t;
1427 </pre>
1428 </body>
1429 </html>