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