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