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.5">
   8 <style type="text/css"><!--
   9 BODY {
  10   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  11 }
  12
  13 H1, H2, H3, H4, H5, H6, P, TD, TH {
  14   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  15 }
  16
  17 KBD {
  18   font-family: monaco, courier, monospace;
  19   font-weight: bold;
  20 }
  21
  22 PRE {
  23   font-family: monaco, courier, monospace;
  24 }
  25
  26 PRE.command {
  27   margin-left: 36pt;
  28 }
  29
  30 PRE.example {
  31   background: #eeeeee;
  32   border: dotted thin #999999;
  33   margin-left: 36pt;
  34   padding: 10px;
  35 }
  36
  37 PRE.command EM, PRE.example EM {
  38   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  39 }
  40
  41 P.command {
  42   font-family: monaco, courier, monospace;
  43   margin-left: 36pt;
  44 }
  45
  46 P.formula {
  47   font-style: italic;
  48   margin-left: 36pt;
  49 }
  50
  51 BLOCKQUOTE {
  52   background: #cccccc;
  53   border: solid thin #999999;
  54   padding: 10pt;
  55 }
  56
  57 A:link, A:visited {
  58   text-decoration: none;
  59   font-weight: bold;
  60 }
  61
  62 A:link:hover, A:visited:hover, A:active {
  63   text-decoration: underline;
  64   font-weight: bold;
  65 }
  66
  67 SUB, SUP {
  68   font-size: 50%;
  69 }
  70
  71 DIV.table TABLE {
  72   border: solid thin #999999;
  73   border-collapse: collapse;
  74   border-spacing: 0;
  75   margin-left: auto;
  76   margin-right: auto;
  77 }
  78
  79 DIV.table CAPTION {
  80   caption-side: top;
  81   font-size: 120%;
  82   font-style: italic;
  83   font-weight: bold;
  84   margin-left: auto;
  85   margin-right: auto;
  86 }
  87
  88 DIV.table TABLE TD {
  89   border: solid thin #cccccc;
  90   padding-top: 5pt;
  91 }
  92
  93 DIV.table TABLE TH {
  94   background: #cccccc;
  95   border: none;
  96   border-bottom: solid thin #999999;
  97 }
  98
  99 DIV.figure TABLE {
 100   margin-left: auto;
 101   margin-right: auto;
 102 }
 103
 104 DIV.figure CAPTION {
 105   caption-side: bottom;
 106   font-size: 120%;
 107   font-style: italic;
 108   font-weight: bold;
 109   margin-left: auto;
 110   margin-right: auto;
 111 }
 112
 113 TH.label {
 114   padding-top: 5pt;
 115   text-align: right;
 116   vertical-align: top;
 117 }
 118
 119 HR {
 120   border: solid thin;
 121 }
 122
 123 SPAN.info {
 124   background: #000000;
 125   border: thin solid #000000;
 126   color: #ffffff;
 127   font-size: 80%;
 128   font-style: italic;
 129   font-weight: bold;
 130   white-space: nowrap;
 131 }
 132
 133 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 134   float: right;
 135   font-size: 100%;
 136 }
 137
 138 H2.title, H3.title {
 139   border-bottom: solid 2pt #000000;
 140 }
 141
 142 DT {
 143   margin-left: 36pt;
 144   margin-top: 12pt;
 145 }
 146
 147 DD {
 148   margin-left: 54pt;
 149 }
 150
 151 DL.category DT {
 152   font-weight: bold;
 153 }
 154
 155 P.summary {
 156   margin-left: 36pt;
 157   font-family: monaco, courier, monospace;
 158 }
 159
 160 SPAN.message {
 161   font-style: italic;
 162   font-size: smaller;
 163 }
 164
 165 DIV.summary TABLE {
 166   border: solid thin #999999;
 167   border-collapse: collapse;
 168   border-spacing: 0;
 169   margin: 10px;
 170 }
 171
 172 DIV.summary TABLE TD, DIV.summary TABLE TH {
 173   border: solid thin #999999;
 174   padding: 5px;
 175   text-align: left;
 176   vertical-align: top;
 177 }
 178
 179 DIV.summary TABLE THEAD TH {
 180   background: #eeeeee;
 181 }
 182
 183 /* API documentation styles... */
 184 div.body h1 {
 185   margin: 0;
 186 }
 187 div.body h2 {
 188   margin-top: 1.5em;
 189 }
 190 div.body h3, div.body h4, div.body h5 {
 191   margin-bottom: 0.5em;
 192   margin-top: 1.5em;
 193 }
 194 .class, .enumeration, .function, .struct, .typedef, .union {
 195   border-bottom: solid thin #999999;
 196   margin-bottom: 0;
 197   margin-top: 2em;
 198 }
 199 .description {
 200   margin-top: 0.5em;
 201 }
 202 code, p.code, pre, ul.code li {
 203   font-family: monaco, courier, monospace;
 204   font-size: 90%;
 205 }
 206 ul.code, ul.contents, ul.subcontents {
 207   list-style-type: none;
 208   margin: 0;
 209   padding-left: 0;
 210 }
 211 ul.code li {
 212   margin: 0;
 213 }
 214 ul.contents > li {
 215   margin-top: 1em;
 216 }
 217 ul.contents li ul.code, ul.contents li ul.subcontents {
 218   padding-left: 2em;
 219 }
 220 div.body dl {
 221   margin-left: 0;
 222   margin-top: 0;
 223 }
 224 div.body dt {
 225   font-style: italic;
 226   margin-left: 0;
 227   margin-top: 0;
 228 }
 229 div.body dd {
 230   margin-bottom: 0.5em;
 231 }
 232
 233 /* This is just for the HTML files generated with the framedhelp target */
 234 div.contents {
 235   background: #e8e8e8;
 236   border: solid thin black;
 237   padding: 10px;
 238 }
 239 div.contents h1 {
 240   font-size: 110%;
 241 }
 242 div.contents h2 {
 243   font-size: 100%;
 244 }
 245 div.contents ul.contents {
 246   font-size: 80%;
 247 }
 248 div.contents ul.subcontents li {
 249   margin-left: 1em;
 250   text-indent: -1em;
 251 }
 252 --></style>
 253 </head>
 254 <body>
 255 <div class='body'>
 256 <!--
 257   "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
 258
 259   CUPS API header for the Common UNIX Printing System (CUPS).
 260
 261   Copyright 2008 by Apple Inc.
 262
 263   These coded instructions, statements, and computer programs are the
 264   property of Apple Inc. and are protected by Federal copyright
 265   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 266   which should have been included with this file.  If this file is
 267   file is missing or damaged, see the license at "http://www.cups.org/".
 268 -->
 269
 270 <h1 class="title">CUPS API</h1>
 271
 272 <div class='summary'><table summary='General Information'>
 273 <thead>
 274 <tr>
 275         <th>Header</th>
 276         <th>cups/cups.h</th>
 277 </tr>
 278 </thead>
 279 <tbody>
 280 <tr>
 281         <th>Library</th>
 282         <td>-lcups</td>
 283 </tr>
 284 <tr>
 285         <th>See Also</th>
 286         <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br>
 287         Programming: <a href='api-array.html' target='_top'>Array API</a><br>
 288         Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
 289         Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br>
 290         Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
 291         Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
 292         Programming: <a href='api-raster.html' target='_top'>Raster API</a></td>
 293 </tr>
 294 </tbody>
 295 </table></div>
 296 <h2 class="title">Contents</h2>
 297 <ul class="contents">
 298 </li>
 299 <li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
 300 <li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li>
 301 <li><a href="#OPTIONS">Options</a></li>
 302 <li><a href="#PRINT_JOBS">Print Jobs</a></li>
 303 <li><a href="#ERROR_HANDLING">Error Handling</a></li>
 304 <li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li>
 305 </ul></li>
 306 <li><a href="#FUNCTIONS">Functions</a><ul class="code">
 307 <li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li>
 308 <li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li>
 309 <li><a href="#cupsCancelJob" title="Cancel a print job on the default server.">cupsCancelJob</a></li>
 310 <li><a href="#cupsCancelJob2" title="Cancel or purge a print job.">cupsCancelJob2</a></li>
 311 <li><a href="#cupsCreateJob" title="Create an empty job.">cupsCreateJob</a></li>
 312 <li><a href="#cupsEncryption" title="Get the default encryption settings.">cupsEncryption</a></li>
 313 <li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li>
 314 <li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li>
 315 <li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li>
 316 <li><a href="#cupsFreeOptions" title="Free all memory used by options.">cupsFreeOptions</a></li>
 317 <li><a href="#cupsGetClasses" title="Get a list of printer classes from the default server.">cupsGetClasses</a></li>
 318 <li><a href="#cupsGetDefault" title="Get the default printer or class for the default server.">cupsGetDefault</a></li>
 319 <li><a href="#cupsGetDefault2" title="Get the default printer or class for the specified server.">cupsGetDefault2</a></li>
 320 <li><a href="#cupsGetDest" title="Get the named destination from the list.">cupsGetDest</a></li>
 321 <li><a href="#cupsGetDests" title="Get the list of destinations from the default server.">cupsGetDests</a></li>
 322 <li><a href="#cupsGetDests2" title="Get the list of destinations from the specified server.">cupsGetDests2</a></li>
 323 <li><a href="#cupsGetFd" title="Get a file from the server.">cupsGetFd</a></li>
 324 <li><a href="#cupsGetFile" title="Get a file from the server.">cupsGetFile</a></li>
 325 <li><a href="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</a></li>
 326 <li><a href="#cupsGetJobs2" title="Get the jobs from the specified server.">cupsGetJobs2</a></li>
 327 <li><a href="#cupsGetNamedDest" title="Get options for the named destination.">cupsGetNamedDest</a></li>
 328 <li><a href="#cupsGetOption" title="Get an option value.">cupsGetOption</a></li>
 329 <li><a href="#cupsGetPPD" title="Get the PPD file for a printer on the default server.">cupsGetPPD</a></li>
 330 <li><a href="#cupsGetPPD2" title="Get the PPD file for a printer from the specified server.">cupsGetPPD2</a></li>
 331 <li><a href="#cupsGetPPD3" title="Get the PPD file for a printer on the specified
 332 server if it has changed.">cupsGetPPD3</a></li>
 333 <li><a href="#cupsGetPassword" title="Get a password from the user.">cupsGetPassword</a></li>
 334 <li><a href="#cupsGetPrinters" title="Get a list of printers from the default server.">cupsGetPrinters</a></li>
 335 <li><a href="#cupsGetServerPPD" title="Get an available PPD file from the server.">cupsGetServerPPD</a></li>
 336 <li><a href="#cupsLangDefault" title="Return the default language.">cupsLangDefault</a></li>
 337 <li><a href="#cupsLangEncoding" title="Return the character encoding (us-ascii, etc.)
 338 for the given language.">cupsLangEncoding</a></li>
 339 <li><a href="#cupsLangFlush" title="Flush all language data out of the cache.">cupsLangFlush</a></li>
 340 <li><a href="#cupsLangFree" title="Free language data.">cupsLangFree</a></li>
 341 <li><a href="#cupsLangGet" title="Get a language.">cupsLangGet</a></li>
 342 <li><a href="#cupsLastError" title="Return the last IPP status code.">cupsLastError</a></li>
 343 <li><a href="#cupsLastErrorString" title="Return the last IPP status-message.">cupsLastErrorString</a></li>
 344 <li><a href="#cupsNotifySubject" title="Return the subject for the given notification message.">cupsNotifySubject</a></li>
 345 <li><a href="#cupsNotifyText" title="Return the text for the given notification message.">cupsNotifyText</a></li>
 346 <li><a href="#cupsParseOptions" title="Parse options from a command-line argument.">cupsParseOptions</a></li>
 347 <li><a href="#cupsPrintFile" title="Print a file to a printer or class on the default server.">cupsPrintFile</a></li>
 348 <li><a href="#cupsPrintFile2" title="Print a file to a printer or class on the specified
 349 server.">cupsPrintFile2</a></li>
 350 <li><a href="#cupsPrintFiles" title="Print one or more files to a printer or class on the
 351 default server.">cupsPrintFiles</a></li>
 352 <li><a href="#cupsPrintFiles2" title="Print one or more files to a printer or class on the
 353 specified server.">cupsPrintFiles2</a></li>
 354 <li><a href="#cupsPutFd" title="Put a file on the server.">cupsPutFd</a></li>
 355 <li><a href="#cupsPutFile" title="Put a file on the server.">cupsPutFile</a></li>
 356 <li><a href="#cupsRemoveDest" title="Remove a destination from the destination list.">cupsRemoveDest</a></li>
 357 <li><a href="#cupsRemoveOption" title="Remove an option from an option array.">cupsRemoveOption</a></li>
 358 <li><a href="#cupsServer" title="Return the hostname/address of the default server.">cupsServer</a></li>
 359 <li><a href="#cupsSetDefaultDest" title="Set the default destination.">cupsSetDefaultDest</a></li>
 360 <li><a href="#cupsSetDests" title="Save the list of destinations for the default server.">cupsSetDests</a></li>
 361 <li><a href="#cupsSetDests2" title="Save the list of destinations for the specified server.">cupsSetDests2</a></li>
 362 <li><a href="#cupsSetEncryption" title="Set the encryption preference.">cupsSetEncryption</a></li>
 363 <li><a href="#cupsSetPasswordCB" title="Set the password callback for CUPS.">cupsSetPasswordCB</a></li>
 364 <li><a href="#cupsSetServer" title="Set the default server name.">cupsSetServer</a></li>
 365 <li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li>
 366 <li><a href="#cupsStartDocument" title="Add a document to a job created with cupsCreateJob().">cupsStartDocument</a></li>
 367 <li><a href="#cupsTempFd" title="Creates a temporary file.">cupsTempFd</a></li>
 368 <li><a href="#cupsTempFile" title="Generates a temporary filename.">cupsTempFile</a></li>
 369 <li><a href="#cupsTempFile2" title="Creates a temporary CUPS file.">cupsTempFile2</a></li>
 370 <li><a href="#cupsUser" title="Return the current user's name.">cupsUser</a></li>
 371 </ul>
 372 <li><a href="#TYPES">Data Types</a><ul class="code">
 373         <li><a href="#cups_dest_t" title="Destination">cups_dest_t</a></li>
 374         <li><a href="#cups_job_t" title="Job">cups_job_t</a></li>
 375         <li><a href="#cups_option_t" title="Printer Options">cups_option_t</a></li>
 376         <li><a href="#cups_password_cb_t" title="Password callback">cups_password_cb_t</a></li>
 377         <li><a href="#cups_ptype_t" title="Printer type/capability bits">cups_ptype_t</a></li>
 378 </ul></li>
 379 <li><a href="#STRUCTURES">Structures</a><ul class="code">
 380         <li><a href="#cups_dest_s" title="Destination">cups_dest_s</a></li>
 381         <li><a href="#cups_job_s" title="Job">cups_job_s</a></li>
 382         <li><a href="#cups_option_s" title="Printer Options">cups_option_s</a></li>
 383 </ul></li>
 384 <li><a href="#ENUMERATIONS">Constants</a><ul class="code">
 385         <li><a href="#cups_ptype_e" title="Printer type/capability bit constants">cups_ptype_e</a></li>
 386 </ul></li>
 387 </ul>
 388 <!--
 389   "$Id: api-cups.shtml 7258 2008-01-28 00:15:05Z mike $"
 390
 391   CUPS API introduction for the Common UNIX Printing System (CUPS).
 392
 393   Copyright 2007-2008 by Apple Inc.
 394   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 395
 396   These coded instructions, statements, and computer programs are the
 397   property of Apple Inc. and are protected by Federal copyright
 398   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 399   which should have been included with this file.  If this file is
 400   file is missing or damaged, see the license at "http://www.cups.org/".
 401 -->
 402
 403 <h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
 404
 405 <p>The CUPS API provides the convenience functions needed to support
 406 applications, filters, printer drivers, and backends that need to interface
 407 with the CUPS scheduler.</p>
 408
 409 <h3><a name='PRINTERS_AND_CLASSES'>Printers and Classes</a></h3>
 410
 411 <p>Printers and classes (collections of printers) are accessed through
 412 the <a href="#cups_dest_t"><code>cups_dest_t</code></a> structure which
 413 includes the name (<code>name</code>), instance (<code>instance</code> -
 414 a way of selected certain saved options), and the options and attributes
 415 associated with that destination (<code>num_options</code> and
 416 <code>options</code>). Destinations are created using the
 417 <a href="#cupsGetDests"><code>cupsGetDests</code></a> function and freed
 418 using the <a href='#cupsFreeDests'><code>cupsFreeDests</code></a> function.
 419 The <a href='#cupsGetDest'><code>cupsGetDest</code></a> function finds a
 420 specific destination for printing:</p>
 421
 422 <pre class='example'>
 423 #include &lt;cups/cups.h&gt;
 424
 425 <a href='#cups_dest_t'>cups_dest_t</a> *dests;
 426 int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&amp;dests);
 427 <a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests);
 428
 429 /* do something wiith dest */
 430
 431 <a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
 432 </pre>
 433
 434 <p>Passing <code>NULL</code> to
 435 <a href='#cupsGetDest'><code>cupsGetDest</code></a> for the destination name
 436 will return the default destination. Similarly, passing a <code>NULL</code>
 437 instance will return the default instance for that destination.</p>
 438
 439 <div class='table'><table summary='Table 1: Printer Attributes' width='80%'>
 440 <caption>Table 1: <a name='TABLE1'>Printer Attributes</a></caption>
 441 <thead>
 442 <tr>
 443         <th>Attribute Name</th>
 444         <th>Description</th>
 445 </tr>
 446 </thead>
 447 <tbody>
 448 <tr>
 449         <td>"auth-info-required"</td>
 450         <td>The type of authentication required for printing to this
 451         destination: "none", "username,password", "domain,username,password",
 452         or "negotiate" (Kerberos)</td>
 453 </tr>
 454 <tr>
 455         <td>"printer-info"</td>
 456         <td>The human-readable description of the destination such as "My
 457         Laser Printer".</td>
 458 </tr>
 459 <tr>
 460         <td>"printer-is-accepting-jobs"</td>
 461         <td>"1" if the destination is accepting new jobs, "0" if not.</td>
 462 </tr>
 463 <tr>
 464         <td>"printer-is-shared"</td>
 465         <td>"1" if the destination is being shared with other computers, "0" if
 466         not.</td>
 467 </tr>
 468 <tr>
 469         <td>"printer-location"</td>
 470         <td>The human-readable location of the destination such as "Lab 4".</td>
 471 </tr>
 472 <tr>
 473         <td>"printer-make-and-model"</td>
 474         <td>The human-readable make and model of the destination such as "HP
 475         LaserJet 4000 Series".</td>
 476 </tr>
 477 <tr>
 478         <td>"printer-state"</td>
 479         <td>"3" if the destination is idle, "4" if the destination is printing
 480         a job, and "5" if the destination is stopped.</td>
 481 </tr>
 482 <tr>
 483         <td>"printer-state-change-time"</td>
 484         <td>The UNIX time when the destination entered the current state.</td>
 485 </tr>
 486 <tr>
 487         <td>"printer-state-reasons"</td>
 488         <td>Additional comma-delimited state keywords for the destination
 489         such as "media-tray-empty-error" and "toner-low-warning".</td>
 490 </tr>
 491 <tr>
 492         <td>"printer-type"</td>
 493         <td>The <a href='#cups_printer_t'><code>cups_printer_t</code></a>
 494         value associated with the destination.</td>
 495 </tr>
 496 </tbody>
 497 </table></div>
 498
 499 <h3><a name='OPTIONS'>Options</a></h3>
 500
 501 <p>Options are stored in arrays of
 502 <a href='#cups_option_t'><code>cups_option_t</code></a> structures. Each
 503 option has a name (<code>name</code>) and value (<code>value</code>)
 504 associated with it. The <a href='#cups_dest_t'><code>cups_dest_t</code></a>
 505 <code>num_options</code> and <code>options</code> members contain the
 506 default options for a particular destination, along with several informational
 507 attributes about the destination as shown in <a href='#TABLE1'>Table 1</a>.
 508 The <a href='#cupsGetOption'><code>cupsGetOption</code></a> function gets
 509 the value for the named option. For example, the following code lists the
 510 available destinations and their human-readable descriptions:</p>
 511
 512 <pre class='example'>
 513 #include &lt;cups/cups.h&gt;
 514
 515 <a href='#cups_dest_t'>cups_dest_t</a> *dests;
 516 int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&amp;dests);
 517 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 518 int i;
 519 const char *value;
 520
 521 for (i = num_dests, dest = dests; i > 0; i --, dest ++)
 522   if (dest->instance == NULL)
 523   {
 524     value = <a href='#cupsGetOption'>cupsGetOption</a>("printer-info", dest->num_options, dest->options);
 525     printf("%s (%s)\n", dest->name, value ? value : "no description");
 526   }
 527
 528 <a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
 529 </pre>
 530
 531 <p>You can create your own option arrays using the
 532 <a href='#cupsAddOption'><code>cupsAddOption</code></a> function, which
 533 adds a single named option to an array:</p>
 534
 535 <pre class='example'>
 536 #include &lt;cups/cups.h&gt;
 537
 538 int num_options = 0;
 539 <a href='#cups_option_t'>cups_option_t</a> *options = NULL;
 540
 541 /* The returned num_options value is updated as needed */
 542 num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "value", num_options, &amp;options);
 543
 544 /* This adds a second option value */
 545 num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &amp;options);
 546
 547 /* This replaces the first option we added */
 548 num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &amp;options);
 549 </pre>
 550
 551 <p>Use a <code>for</code> loop to copy the options from a destination:</p>
 552
 553 <pre class='example'>
 554 #include &lt;cups/cups.h&gt;
 555
 556 int i;
 557 int num_options = 0;
 558 <a href='#cups_option_t'>cups_option_t</a> *options = NULL;
 559 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 560
 561 for (i = 0; i < dest->num_options; i ++)
 562   num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value, num_options, &amp;options);
 563 </pre>
 564
 565 <p>Use the <a href='#cupsFreeOptions'><code>cupsFreeOptions</code></a>
 566 function to free the options array when you are done using it:</p>
 567
 568 <pre class='example'>
 569 <a href='#cupsFreeOptions'>cupsFreeOptions</a>(num_options, options);
 570 </pre>
 571
 572 <h3><a name='PRINT_JOBS'>Print Jobs</a></h3>
 573
 574 <p>Print jobs are identified by a locally-unique job ID number from 1 to
 575 2<sup>31</sup>-1 and have options and one or more files for printing to a
 576 single destination. The <a href='#cupsPrintFile'><code>cupsPrintFile</code></a>
 577 function creates a new job with one file. The following code prints the CUPS
 578 test page file:</p>
 579
 580 <pre class='example'>
 581 #include &lt;cups/cups.h&gt;
 582
 583 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 584 int num_options;
 585 <a href='#cups_option_t'>cups_option_t</a> *options;
 586 int job_id;
 587
 588 /* Print a single file */
 589 job_id = <a href='#cupsPrintFile'>cupsPrintFile</a>(dest->name, "/usr/share/cups/data/testprint.ps", "Test Print", num_options, options);
 590 </pre>
 591
 592 <p>The <a href='#cupsPrintFiles'><code>cupsPrintFiles</code></a> function
 593 creates a job with multiple files. The files are provided in a
 594 <code>char *</code> array:</p>
 595
 596 <pre class='example'>
 597 #include &lt;cups/cups.h&gt;
 598
 599 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 600 int num_options;
 601 <a href='#cups_option_t'>cups_option_t</a> *options;
 602 int job_id;
 603 char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" };
 604
 605 /* Print three files */
 606 job_id = <a href='#cupsPrintFiles'>cupsPrintFiles</a>(dest->name, 3, files, "Test Print", num_options, options);
 607 </pre>
 608
 609 <p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a>
 610 function creates a new job with no files in it. Files are added using the
 611 <a href='#cupsStartDocument'><code>cupsStartDocument</code></a>,
 612 <a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>,
 613 and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions.
 614 The following example creates a job with 10 text files for printing:</p>
 615
 616 <pre class='example'>
 617 #include &lt;cups/cups.h&gt;
 618
 619 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 620 int num_options;
 621 <a href='#cups_option_t'>cups_option_t</a> *options;
 622 int job_id;
 623 int i;
 624 char buffer[1024];
 625
 626 /* Create the job */
 627 job_id = <a href='#cupsCreateJob'>cupsCreateJob</a>(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files", num_options, options);
 628
 629 /* If the job is created, add 10 files */
 630 if (job_id > 0)
 631 {
 632   for (i = 1; i &lt;= 10; i ++)
 633   {
 634     snprintf(buffer, sizeof(buffer), "file%d.txt", i);
 635
 636     <a href='#cupsStartDocument'>cupsStartDocument</a>(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer, CUPS_FORMAT_TEXT, i == 10);
 637
 638     snprintf(buffer, sizeof(buffer),
 639              "File %d\n"
 640              "\n"
 641              "One fish,\n"
 642              "Two fish,\n
 643              "Red fish,\n
 644              "Blue fish\n", i);
 645
 646     /* cupsWriteRequestData can be called as many times as needed */
 647     <a href='#cupsWriteRequestData'>cupsWriteRequestData</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));
 648
 649     <a href='#cupsFinishDocument'>cupsFinishDocument</a>(CUPS_HTTP_DEFAULT, dest->name);
 650   }
 651 }
 652 </pre>
 653
 654 <p>Once you have created a job, you can monitor its status using the
 655 <a href='#cupsGetJobs'><code>cupsGetJobs</code></a> function, which returns
 656 an array of <a href='#cups_job_t'><code>cups_job_t</code></a> structures.
 657 Each contains the job ID (<code>id</code>), destination name
 658 (<code>dest</code>), title (<code>title</code>), and other information
 659 associated with the job. The job array is freed using the
 660 <a href='#cupsFreeJobs'><code>cupsFreeJobs</code></a> function. The following
 661 example monitors a specific job ID, showing the current job state once every
 662 5 seconds until the job is completed:</p>
 663
 664 <pre class='example'>
 665 #include &lt;cups/cups.h&gt;
 666
 667 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 668 int job_id;
 669 int num_jobs;
 670 <a href='#cups_job_t'>cups_job_t</a> *jobs;
 671 int i;
 672 ipp_jstate_t job_state = IPP_JOB_PENDING;
 673
 674 while (job_state &lt; IPP_JOB_STOPPED)
 675 {
 676   /* Get my jobs (1) with any state (-1) */
 677   num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&amp;jobs, dest->name, 1, -1);
 678
 679   /* Loop to find my job */
 680   job_state = IPP_JOB_COMPLETED;
 681
 682   for (i = 0; i &lt; num_jobs; i ++)
 683     if (jobs[i].id == job_id)
 684     {
 685       job_state = jobs[i].state;
 686       break;
 687     }
 688
 689   /* Free the job array */
 690   <a href='#cupsFreeJobs'>cupsFreeJobs</a>(num_jobs, jobs);
 691
 692   /* Show the current state */
 693   switch (job_state)
 694   {
 695     case IPP_JOB_PENDING :
 696         printf("Job %d is pending.\n", job_id);
 697         break;
 698     case IPP_JOB_HELD :
 699         printf("Job %d is held.\n", job_id);
 700         break;
 701     case IPP_JOB_PROCESSING :
 702         printf("Job %d is processing.\n", job_id);
 703         break;
 704     case IPP_JOB_STOPPED :
 705         printf("Job %d is stopped.\n", job_id);
 706         break;
 707     case IPP_JOB_CANCELED :
 708         printf("Job %d is canceled.\n", job_id);
 709         break;
 710     case IPP_JOB_ABORTED :
 711         printf("Job %d is aborted.\n", job_id);
 712         break;
 713     case IPP_JOB_COMPLETED :
 714         printf("Job %d is completed.\n", job_id);
 715         break;
 716   }
 717
 718   /* Sleep if the job is not finished */
 719   if (job_state &lt; IPP_JOB_STOPPED)
 720     sleep(5);
 721 }
 722 </pre>
 723
 724 <p>To cancel a job, use the
 725 <a href='#cupsCancelJob'><code>cupsCancelJob</code></a> function with the
 726 job ID:</p>
 727
 728 <pre class='exmaple'>
 729 #include &lt;cups/cups.h&gt;
 730
 731 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 732 int job_id;
 733
 734 <a href='#cupsCancelJob'>cupsCancelJob</a>(dest->name, job_id);
 735 </pre>
 736
 737 <h3><a name='ERROR_HANDLING'>Error Handling</a></h3>
 738
 739 <p>If any of the CUPS API printing functions returns an error, the reason for
 740 that error can be found by calling the
 741 <a href='#cupsLastError'><code>cupsLastError</code></a> and
 742 <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> functions.
 743 <a href='#cupsLastError'><code>cupsLastError</code></a> returns the last IPP
 744 error code
 745 (<a href='api-httpipp.html#ipp_status_t'><code>ipp_status_t</code></a>)
 746 that was encountered, while
 747 <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> returns
 748 a (localized) human-readable string that can be shown to the user. For example,
 749 if any of the job creation functions returns a job ID of 0, you can use
 750 <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> to show
 751 the reason why the job could not be created:</p>
 752
 753 <pre class='example'>
 754 #include &lt;cups/cups.h&gt;
 755
 756 int job_id;
 757
 758 if (job_id == 0)
 759   puts(cupsLastErrorString());
 760 </pre>
 761
 762 <h3><a name='PASSWORDS_AND_AUTHENTICATION'>Passwords and Authentication</a></h3>
 763
 764 <p>CUPS supports authentication of any request, including submission of print
 765 jobs. The default mechanism for getting the username and password is to use the
 766 login user and a password from the console.</p>
 767
 768 <p>To support other types of applications, in particular Graphical User
 769 Interfaces ("GUIs"), the CUPS API provides functions to set the default
 770 username and to register a callback function that returns a password string.</p>
 771
 772 <p>The <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a>
 773 function is used to set a password callback in your program. Only one
 774 function can be used at any time.</p>
 775
 776 <p>The <a href="#cupsSetUser"><code>cupsSetUser</code></a> function sets the
 777 current username for authentication. This function can be called by your
 778 password callback function to change the current username as needed.</p>
 779
 780 <p>The following example shows a simple password callback that gets a
 781 username and password from the user:</p>
 782
 783 <pre class='example'>
 784 #include &lt;cups/cups.h&gt;
 785
 786 const char *
 787 my_password_cb(const char *prompt)
 788 {
 789   char  user[65];
 790
 791
 792   puts(prompt);
 793
 794   /* Get a username from the user */
 795   printf("Username: ");
 796   if (fgets(user, sizeof(user), stdin) == NULL)
 797     return (NULL);
 798
 799   /* Strip the newline from the string and set the user */
 800   user[strlen(user) - 1] = '\0';
 801
 802   <a href='#cupsSetUser'>cupsSetUser</a>(user);
 803
 804   /* Use getpass() to ask for the password... */
 805   return (getpass("Password: "));
 806 }
 807
 808 <a href='#cupsSetPasswordCB'>cupsSetPasswordCB</a>(my_password_cb);
 809 </pre>
 810
 811 <p>Similarly, a GUI could display the prompt string in a window with input
 812 fields for the username and password. The username should default to the
 813 string returned by the <a href="#cupsUser"><code>cupsUser</code></a>
 814 function.</p>
 815 <h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
 816 <h3 class="function"><a name="cupsAddDest">cupsAddDest</a></h3>
 817 <p class="description">Add a destination to the list of destinations.</p>
 818 <p class="code">
 819 int cupsAddDest (<br>
 820 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
 821 &nbsp;&nbsp;&nbsp;&nbsp;const char *instance,<br>
 822 &nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
 823 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dest_t">cups_dest_t</a> **dests<br>
 824 );</p>
 825 <h4 class="parameters">Parameters</h4>
 826 <dl>
 827 <dt>name</dt>
 828 <dd class="description">Destination name</dd>
 829 <dt>instance</dt>
 830 <dd class="description">Instance name or <code>NULL</code> for none/primary</dd>
 831 <dt>num_dests</dt>
 832 <dd class="description">Number of destinations</dd>
 833 <dt>dests</dt>
 834 <dd class="description">Destinations</dd>
 835 </dl>
 836 <h4 class="returnvalue">Return Value</h4>
 837 <p class="description">New number of destinations</p>
 838 <h4 class="discussion">Discussion</h4>
 839 <p class="discussion">This function cannot be used to add a new class or printer queue,
 840 it only adds a new container of saved options for the named
 841 destination or instance.<br>
 842 <br>
 843 If the named destination already exists, the destination list is
 844 returned unchanged.  Adding a new instance of a destination creates
 845 a copy of that destination's options.<br>
 846 <br>
 847 Use the <a href="#cupsSaveDests"><code>cupsSaveDests</code></a> function to save the updated list of
 848 destinations to the user's lpoptions file.</p>
 849 <h3 class="function"><a name="cupsAddOption">cupsAddOption</a></h3>
 850 <p class="description">Add an option to an option array.</p>
 851 <p class="code">
 852 int cupsAddOption (<br>
 853 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
 854 &nbsp;&nbsp;&nbsp;&nbsp;const char *value,<br>
 855 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
 856 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> **options<br>
 857 );</p>
 858 <h4 class="parameters">Parameters</h4>
 859 <dl>
 860 <dt>name</dt>
 861 <dd class="description">Name of option</dd>
 862 <dt>value</dt>
 863 <dd class="description">Value of option</dd>
 864 <dt>num_options</dt>
 865 <dd class="description">Number of options</dd>
 866 <dt>options</dt>
 867 <dd class="description">Pointer to options</dd>
 868 </dl>
 869 <h4 class="returnvalue">Return Value</h4>
 870 <p class="description">Number of options</p>
 871 <h4 class="discussion">Discussion</h4>
 872 <p class="discussion">New option arrays can be initialized simply by passing 0 for the
 873 &quot;num_options&quot; parameter.</p>
 874 <h3 class="function"><a name="cupsCancelJob">cupsCancelJob</a></h3>
 875 <p class="description">Cancel a print job on the default server.</p>
 876 <p class="code">
 877 int cupsCancelJob (<br>
 878 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
 879 &nbsp;&nbsp;&nbsp;&nbsp;int job_id<br>
 880 );</p>
 881 <h4 class="parameters">Parameters</h4>
 882 <dl>
 883 <dt>name</dt>
 884 <dd class="description">Name of printer or class</dd>
 885 <dt>job_id</dt>
 886 <dd class="description">Job ID</dd>
 887 </dl>
 888 <h4 class="returnvalue">Return Value</h4>
 889 <p class="description">1 on success, 0 on failure</p>
 890 <h4 class="discussion">Discussion</h4>
 891 <p class="discussion">Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code>
 892 to cancel the current job on the named destination.<br>
 893 <br>
 894 Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get
 895 the cause of any failure.</p>
 896 <h3 class="function"><span class="info">&nbsp;CUPS 1.4&nbsp;</span><a name="cupsCancelJob2">cupsCancelJob2</a></h3>
 897 <p class="description">Cancel or purge a print job.</p>
 898 <p class="code">
 899 ipp_status_t cupsCancelJob2 (<br>
 900 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
 901 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
 902 &nbsp;&nbsp;&nbsp;&nbsp;int job_id,<br>
 903 &nbsp;&nbsp;&nbsp;&nbsp;int purge<br>
 904 );</p>
 905 <h4 class="parameters">Parameters</h4>
 906 <dl>
 907 <dt>http</dt>
 908 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
 909 <dt>name</dt>
 910 <dd class="description">Name of printer or class</dd>
 911 <dt>job_id</dt>
 912 <dd class="description">Job ID or 0 for the current job, -1 for all jobs</dd>
 913 <dt>purge</dt>
 914 <dd class="description">1 to purge, 0 to cancel</dd>
 915 </dl>
 916 <h4 class="returnvalue">Return Value</h4>
 917 <p class="description">IPP status</p>
 918 <h4 class="discussion">Discussion</h4>
 919 <p class="discussion">Canceled jobs remain in the job history while purged jobs are removed
 920 from the job history.<br>
 921 <br>
 922 Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code>
 923 to cancel the current job on the named destination.<br>
 924 <br>
 925 Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get
 926 the cause of any failure.
 927
 928 </p>
 929 <h3 class="function"><span class="info">&nbsp;CUPS 1.4&nbsp;</span><a name="cupsCreateJob">cupsCreateJob</a></h3>
 930 <p class="description">Create an empty job.</p>
 931 <p class="code">
 932 int cupsCreateJob (<br>
 933 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
 934 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
 935 &nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
 936 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
 937 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> *options<br>
 938 );</p>
 939 <h4 class="parameters">Parameters</h4>
 940 <dl>
 941 <dt>http</dt>
 942 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
 943 <dt>name</dt>
 944 <dd class="description">Printer or class name</dd>
 945 <dt>title</dt>
 946 <dd class="description">Title of job</dd>
 947 <dt>num_options</dt>
 948 <dd class="description">Number of options</dd>
 949 <dt>options</dt>
 950 <dd class="description">Options</dd>
 951 </dl>
 952 <h4 class="returnvalue">Return Value</h4>
 953 <p class="description">Job ID or 0 on error</p>
 954 <h4 class="discussion">Discussion</h4>
 955 <p class="discussion">Submit files for printing to the job using the <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>,
 956 <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a>, and <a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> functions.
 957
 958 </p>
 959 <h3 class="function"><a name="cupsEncryption">cupsEncryption</a></h3>
 960 <p class="description">Get the default encryption settings.</p>
 961 <p class="code">
 962 http_encryption_t cupsEncryption (void);</p>
 963 <h4 class="returnvalue">Return Value</h4>
 964 <p class="description">Encryption settings</p>
 965 <h4 class="discussion">Discussion</h4>
 966 <p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
 967 environment variable, then the ~/.cupsrc file, and finally the
 968 /etc/cups/client.conf file. If not set, the default is
 969 <code>HTTP_ENCRYPT_IF_REQUESTED</code>.</p>
 970 <h3 class="function"><span class="info">&nbsp;CUPS 1.4&nbsp;</span><a name="cupsFinishDocument">cupsFinishDocument</a></h3>
 971 <p class="description">Finish sending a document.</p>
 972 <p class="code">
 973 ipp_status_t cupsFinishDocument (<br>
 974 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
 975 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
 976 );</p>
 977 <h4 class="parameters">Parameters</h4>
 978 <dl>
 979 <dt>http</dt>
 980 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
 981 <dt>name</dt>
 982 <dd class="description">Printer or class name</dd>
 983 </dl>
 984 <h4 class="returnvalue">Return Value</h4>
 985 <p class="description">Status of document submission</p>
 986 <h4 class="discussion">Discussion</h4>
 987 <p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>.
 988
 989 </p>
 990 <h3 class="function"><a name="cupsFreeDests">cupsFreeDests</a></h3>
 991 <p class="description">Free the memory used by the list of destinations.</p>
 992 <p class="code">
 993 void cupsFreeDests (<br>
 994 &nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
 995 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
 996 );</p>
 997 <h4 class="parameters">Parameters</h4>
 998 <dl>
 999 <dt>num_dests</dt>
1000 <dd class="description">Number of destinations</dd>
1001 <dt>dests</dt>
1002 <dd class="description">Destinations</dd>
1003 </dl>
1004 <h3 class="function"><a name="cupsFreeJobs">cupsFreeJobs</a></h3>
1005 <p class="description">Free memory used by job data.</p>
1006 <p class="code">
1007 void cupsFreeJobs (<br>
1008 &nbsp;&nbsp;&nbsp;&nbsp;int num_jobs,<br>
1009 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_job_t">cups_job_t</a> *jobs<br>
1010 );</p>
1011 <h4 class="parameters">Parameters</h4>
1012 <dl>
1013 <dt>num_jobs</dt>
1014 <dd class="description">Number of jobs</dd>
1015 <dt>jobs</dt>
1016 <dd class="description">Jobs</dd>
1017 </dl>
1018 <h3 class="function"><a name="cupsFreeOptions">cupsFreeOptions</a></h3>
1019 <p class="description">Free all memory used by options.</p>
1020 <p class="code">
1021 void cupsFreeOptions (<br>
1022 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1023 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> *options<br>
1024 );</p>
1025 <h4 class="parameters">Parameters</h4>
1026 <dl>
1027 <dt>num_options</dt>
1028 <dd class="description">Number of options</dd>
1029 <dt>options</dt>
1030 <dd class="description">Pointer to options</dd>
1031 </dl>
1032 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="cupsGetClasses">cupsGetClasses</a></h3>
1033 <p class="description">Get a list of printer classes from the default server.</p>
1034 <p class="code">
1035 int cupsGetClasses (<br>
1036 &nbsp;&nbsp;&nbsp;&nbsp;char ***classes<br>
1037 );</p>
1038 <h4 class="parameters">Parameters</h4>
1039 <dl>
1040 <dt>classes</dt>
1041 <dd class="description">Classes</dd>
1042 </dl>
1043 <h4 class="returnvalue">Return Value</h4>
1044 <p class="description">Number of classes</p>
1045 <h4 class="discussion">Discussion</h4>
1046 <p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
1047
1048 </p>
1049 <h3 class="function"><a name="cupsGetDefault">cupsGetDefault</a></h3>
1050 <p class="description">Get the default printer or class for the default server.</p>
1051 <p class="code">
1052 const char *cupsGetDefault (void);</p>
1053 <h4 class="returnvalue">Return Value</h4>
1054 <p class="description">Default printer or <code>NULL</code></p>
1055 <h4 class="discussion">Discussion</h4>
1056 <p class="discussion">This function returns the default printer or class as defined by
1057 the LPDEST or PRINTER environment variables. If these environment
1058 variables are not set, the server default destination is returned.
1059 Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a>
1060 functions to get the user-defined default printer, as this function does
1061 not support the lpoptions-defined default printer.</p>
1062 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21&nbsp;</span><a name="cupsGetDefault2">cupsGetDefault2</a></h3>
1063 <p class="description">Get the default printer or class for the specified server.</p>
1064 <p class="code">
1065 const char *cupsGetDefault2 (<br>
1066 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http<br>
1067 );</p>
1068 <h4 class="parameters">Parameters</h4>
1069 <dl>
1070 <dt>http</dt>
1071 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1072 </dl>
1073 <h4 class="returnvalue">Return Value</h4>
1074 <p class="description">Default printer or <code>NULL</code></p>
1075 <h4 class="discussion">Discussion</h4>
1076 <p class="discussion">This function returns the default printer or class as defined by
1077 the LPDEST or PRINTER environment variables. If these environment
1078 variables are not set, the server default destination is returned.
1079 Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a>
1080 functions to get the user-defined default printer, as this function does
1081 not support the lpoptions-defined default printer.
1082
1083 </p>
1084 <h3 class="function"><a name="cupsGetDest">cupsGetDest</a></h3>
1085 <p class="description">Get the named destination from the list.</p>
1086 <p class="code">
1087 <a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest (<br>
1088 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1089 &nbsp;&nbsp;&nbsp;&nbsp;const char *instance,<br>
1090 &nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
1091 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
1092 );</p>
1093 <h4 class="parameters">Parameters</h4>
1094 <dl>
1095 <dt>name</dt>
1096 <dd class="description">Destination name or <code>NULL</code> for the default destination</dd>
1097 <dt>instance</dt>
1098 <dd class="description">Instance name or <code>NULL</code></dd>
1099 <dt>num_dests</dt>
1100 <dd class="description">Number of destinations</dd>
1101 <dt>dests</dt>
1102 <dd class="description">Destinations</dd>
1103 </dl>
1104 <h4 class="returnvalue">Return Value</h4>
1105 <p class="description">Destination pointer or <code>NULL</code></p>
1106 <h4 class="discussion">Discussion</h4>
1107 <p class="discussion">Use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a
1108 list of supported destinations for the current user.</p>
1109 <h3 class="function"><a name="cupsGetDests">cupsGetDests</a></h3>
1110 <p class="description">Get the list of destinations from the default server.</p>
1111 <p class="code">
1112 int cupsGetDests (<br>
1113 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dest_t">cups_dest_t</a> **dests<br>
1114 );</p>
1115 <h4 class="parameters">Parameters</h4>
1116 <dl>
1117 <dt>dests</dt>
1118 <dd class="description">Destinations</dd>
1119 </dl>
1120 <h4 class="returnvalue">Return Value</h4>
1121 <p class="description">Number of destinations</p>
1122 <h4 class="discussion">Discussion</h4>
1123 <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
1124 printer-info, printer-is-accepting-jobs, printer-is-shared,
1125 printer-make-and-model, printer-state, printer-state-change-time,
1126 printer-state-reasons, and printer-type attributes as options.<br>
1127 <br>
1128 Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
1129 the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.</p>
1130 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21&nbsp;</span><a name="cupsGetDests2">cupsGetDests2</a></h3>
1131 <p class="description">Get the list of destinations from the specified server.</p>
1132 <p class="code">
1133 int cupsGetDests2 (<br>
1134 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1135 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dest_t">cups_dest_t</a> **dests<br>
1136 );</p>
1137 <h4 class="parameters">Parameters</h4>
1138 <dl>
1139 <dt>http</dt>
1140 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1141 <dt>dests</dt>
1142 <dd class="description">Destinations</dd>
1143 </dl>
1144 <h4 class="returnvalue">Return Value</h4>
1145 <p class="description">Number of destinations</p>
1146 <h4 class="discussion">Discussion</h4>
1147 <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
1148 printer-info, printer-is-accepting-jobs, printer-is-shared,
1149 printer-make-and-model, printer-state, printer-state-change-time,
1150 printer-state-reasons, and printer-type attributes as options.<br>
1151 <br>
1152 Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
1153 the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.
1154
1155 </p>
1156 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.20&nbsp;</span><a name="cupsGetFd">cupsGetFd</a></h3>
1157 <p class="description">Get a file from the server.</p>
1158 <p class="code">
1159 http_status_t cupsGetFd (<br>
1160 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1161 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1162 &nbsp;&nbsp;&nbsp;&nbsp;int fd<br>
1163 );</p>
1164 <h4 class="parameters">Parameters</h4>
1165 <dl>
1166 <dt>http</dt>
1167 <dd class="description">HTTP connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1168 <dt>resource</dt>
1169 <dd class="description">Resource name</dd>
1170 <dt>fd</dt>
1171 <dd class="description">File descriptor</dd>
1172 </dl>
1173 <h4 class="returnvalue">Return Value</h4>
1174 <p class="description">HTTP status</p>
1175 <h4 class="discussion">Discussion</h4>
1176 <p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved.
1177
1178 </p>
1179 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.20&nbsp;</span><a name="cupsGetFile">cupsGetFile</a></h3>
1180 <p class="description">Get a file from the server.</p>
1181 <p class="code">
1182 http_status_t cupsGetFile (<br>
1183 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1184 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1185 &nbsp;&nbsp;&nbsp;&nbsp;const char *filename<br>
1186 );</p>
1187 <h4 class="parameters">Parameters</h4>
1188 <dl>
1189 <dt>http</dt>
1190 <dd class="description">HTTP connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1191 <dt>resource</dt>
1192 <dd class="description">Resource name</dd>
1193 <dt>filename</dt>
1194 <dd class="description">Filename</dd>
1195 </dl>
1196 <h4 class="returnvalue">Return Value</h4>
1197 <p class="description">HTTP status</p>
1198 <h4 class="discussion">Discussion</h4>
1199 <p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved.
1200
1201 </p>
1202 <h3 class="function"><a name="cupsGetJobs">cupsGetJobs</a></h3>
1203 <p class="description">Get the jobs from the default server.</p>
1204 <p class="code">
1205 int cupsGetJobs (<br>
1206 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_job_t">cups_job_t</a> **jobs,<br>
1207 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1208 &nbsp;&nbsp;&nbsp;&nbsp;int myjobs,<br>
1209 &nbsp;&nbsp;&nbsp;&nbsp;int whichjobs<br>
1210 );</p>
1211 <h4 class="parameters">Parameters</h4>
1212 <dl>
1213 <dt>jobs</dt>
1214 <dd class="description">Job data</dd>
1215 <dt>name</dt>
1216 <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for mydest</dd>
1217 <dt>myjobs</dt>
1218 <dd class="description">0 = all users, 1 = mine</dd>
1219 <dt>whichjobs</dt>
1220 <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd>
1221 </dl>
1222 <h4 class="returnvalue">Return Value</h4>
1223 <p class="description">Number of jobs</p>
1224 <h4 class="discussion">Discussion</h4>
1225 <p class="discussion">A &quot;whichjobs&quot; value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
1226 of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
1227 pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
1228 jobs that are stopped, canceled, aborted, or completed.</p>
1229 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21&nbsp;</span><a name="cupsGetJobs2">cupsGetJobs2</a></h3>
1230 <p class="description">Get the jobs from the specified server.</p>
1231 <p class="code">
1232 int cupsGetJobs2 (<br>
1233 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1234 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_job_t">cups_job_t</a> **jobs,<br>
1235 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1236 &nbsp;&nbsp;&nbsp;&nbsp;int myjobs,<br>
1237 &nbsp;&nbsp;&nbsp;&nbsp;int whichjobs<br>
1238 );</p>
1239 <h4 class="parameters">Parameters</h4>
1240 <dl>
1241 <dt>http</dt>
1242 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1243 <dt>jobs</dt>
1244 <dd class="description">Job data</dd>
1245 <dt>name</dt>
1246 <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for mydest</dd>
1247 <dt>myjobs</dt>
1248 <dd class="description">0 = all users, 1 = mine</dd>
1249 <dt>whichjobs</dt>
1250 <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd>
1251 </dl>
1252 <h4 class="returnvalue">Return Value</h4>
1253 <p class="description">Number of jobs</p>
1254 <h4 class="discussion">Discussion</h4>
1255 <p class="discussion">A &quot;whichjobs&quot; value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
1256 of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
1257 pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
1258 jobs that are stopped, canceled, aborted, or completed.
1259
1260 </p>
1261 <h3 class="function"><span class="info">&nbsp;CUPS 1.4&nbsp;</span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3>
1262 <p class="description">Get options for the named destination.</p>
1263 <p class="code">
1264 <a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br>
1265 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1266 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1267 &nbsp;&nbsp;&nbsp;&nbsp;const char *instance<br>
1268 );</p>
1269 <h4 class="parameters">Parameters</h4>
1270 <dl>
1271 <dt>http</dt>
1272 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1273 <dt>name</dt>
1274 <dd class="description">Destination name or <code>NULL</code></dd>
1275 <dt>instance</dt>
1276 <dd class="description">Instance name or <code>NULL</code></dd>
1277 </dl>
1278 <h4 class="returnvalue">Return Value</h4>
1279 <p class="description">Destination or <code>NULL</code></p>
1280 <h4 class="discussion">Discussion</h4>
1281 <p class="discussion">This function is optimized for retrieving a single destination and should
1282 be used instead of <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you either
1283 know the name of the destination or want to print to the default destination.
1284 If <code>NULL</code> is returned, the destination does not exist or there is no
1285 default destination.<br>
1286 <br>
1287 If &quot;http&quot; is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print
1288 server will be used.<br>
1289 <br>
1290 If &quot;name&quot; is <code>NULL</code>, the default printer for the current user will be
1291 returned.<br>
1292 <br>
1293 The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a
1294 &quot;num_dests&quot; value of 1.
1295
1296 </p>
1297 <h3 class="function"><a name="cupsGetOption">cupsGetOption</a></h3>
1298 <p class="description">Get an option value.</p>
1299 <p class="code">
1300 const char *cupsGetOption (<br>
1301 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1302 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1303 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> *options<br>
1304 );</p>
1305 <h4 class="parameters">Parameters</h4>
1306 <dl>
1307 <dt>name</dt>
1308 <dd class="description">Name of option</dd>
1309 <dt>num_options</dt>
1310 <dd class="description">Number of options</dd>
1311 <dt>options</dt>
1312 <dd class="description">Options</dd>
1313 </dl>
1314 <h4 class="returnvalue">Return Value</h4>
1315 <p class="description">Option value or <code>NULL</code></p>
1316 <h3 class="function"><a name="cupsGetPPD">cupsGetPPD</a></h3>
1317 <p class="description">Get the PPD file for a printer on the default server.</p>
1318 <p class="code">
1319 const char *cupsGetPPD (<br>
1320 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
1321 );</p>
1322 <h4 class="parameters">Parameters</h4>
1323 <dl>
1324 <dt>name</dt>
1325 <dd class="description">Printer name</dd>
1326 </dl>
1327 <h4 class="returnvalue">Return Value</h4>
1328 <p class="description">Filename for PPD file</p>
1329 <h4 class="discussion">Discussion</h4>
1330 <p class="discussion">For classes, <code>cupsGetPPD</code> returns the PPD file for the first printer
1331 in the class.</p>
1332 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21&nbsp;</span><a name="cupsGetPPD2">cupsGetPPD2</a></h3>
1333 <p class="description">Get the PPD file for a printer from the specified server.</p>
1334 <p class="code">
1335 const char *cupsGetPPD2 (<br>
1336 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1337 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
1338 );</p>
1339 <h4 class="parameters">Parameters</h4>
1340 <dl>
1341 <dt>http</dt>
1342 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1343 <dt>name</dt>
1344 <dd class="description">Printer name</dd>
1345 </dl>
1346 <h4 class="returnvalue">Return Value</h4>
1347 <p class="description">Filename for PPD file</p>
1348 <h4 class="discussion">Discussion</h4>
1349 <p class="discussion">For classes, <code>cupsGetPPD2</code> returns the PPD file for the first printer
1350 in the class.
1351
1352 </p>
1353 <h3 class="function"><a name="cupsGetPPD3">cupsGetPPD3</a></h3>
1354 <p class="description">Get the PPD file for a printer on the specified
1355 server if it has changed.</p>
1356 <p class="code">
1357 http_status_t cupsGetPPD3 (<br>
1358 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1359 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1360 &nbsp;&nbsp;&nbsp;&nbsp;time_t *modtime,<br>
1361 &nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
1362 &nbsp;&nbsp;&nbsp;&nbsp;size_t bufsize<br>
1363 );</p>
1364 <h4 class="parameters">Parameters</h4>
1365 <dl>
1366 <dt>http</dt>
1367 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1368 <dt>name</dt>
1369 <dd class="description">Printer name</dd>
1370 <dt>modtime</dt>
1371 <dd class="description">Modification time</dd>
1372 <dt>buffer</dt>
1373 <dd class="description">Filename buffer</dd>
1374 <dt>bufsize</dt>
1375 <dd class="description">Size of filename buffer</dd>
1376 </dl>
1377 <h4 class="returnvalue">Return Value</h4>
1378 <p class="description">HTTP status</p>
1379 <h4 class="discussion">Discussion</h4>
1380 <p class="discussion">The &quot;modtime&quot; parameter contains the modification time of any
1381 locally-cached content and is updated with the time from the PPD file on
1382 the server.<br>
1383 <br>
1384 The &quot;buffer&quot; parameter contains the local PPD filename.  If it contains
1385 the empty string, a new temporary file is created, otherwise the existing
1386 file will be overwritten as needed.<br>
1387 <br>
1388 On success, <code>HTTP_OK</code> is returned for a new PPD file and
1389 <code>HTTP_NOT_MODIFIED</code> if the existing PPD file is up-to-date.  Any other
1390 status is an error.<br>
1391 <br>
1392 For classes, <code>cupsGetPPD3</code> returns the PPD file for the first printer
1393 in the class.</p>
1394 <h3 class="function"><a name="cupsGetPassword">cupsGetPassword</a></h3>
1395 <p class="description">Get a password from the user.</p>
1396 <p class="code">
1397 const char *cupsGetPassword (<br>
1398 &nbsp;&nbsp;&nbsp;&nbsp;const char *prompt<br>
1399 );</p>
1400 <h4 class="parameters">Parameters</h4>
1401 <dl>
1402 <dt>prompt</dt>
1403 <dd class="description">Prompt string</dd>
1404 </dl>
1405 <h4 class="returnvalue">Return Value</h4>
1406 <p class="description">Password</p>
1407 <h4 class="discussion">Discussion</h4>
1408 <p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
1409 user does not provide a password.</p>
1410 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="cupsGetPrinters">cupsGetPrinters</a></h3>
1411 <p class="description">Get a list of printers from the default server.</p>
1412 <p class="code">
1413 int cupsGetPrinters (<br>
1414 &nbsp;&nbsp;&nbsp;&nbsp;char ***printers<br>
1415 );</p>
1416 <h4 class="parameters">Parameters</h4>
1417 <dl>
1418 <dt>printers</dt>
1419 <dd class="description">Printers</dd>
1420 </dl>
1421 <h4 class="returnvalue">Return Value</h4>
1422 <p class="description">Number of printers</p>
1423 <h4 class="discussion">Discussion</h4>
1424 <p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
1425
1426 </p>
1427 <h3 class="function"><span class="info">&nbsp;CUPS 1.3&nbsp;</span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3>
1428 <p class="description">Get an available PPD file from the server.</p>
1429 <p class="code">
1430 char *cupsGetServerPPD (<br>
1431 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1432 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
1433 );</p>
1434 <h4 class="parameters">Parameters</h4>
1435 <dl>
1436 <dt>http</dt>
1437 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1438 <dt>name</dt>
1439 <dd class="description">Name of PPD file (&quot;ppd-name&quot;)</dd>
1440 </dl>
1441 <h4 class="returnvalue">Return Value</h4>
1442 <p class="description">Name of PPD file or <code>NULL</code> on error</p>
1443 <h4 class="discussion">Discussion</h4>
1444 <p class="discussion">This function returns the named PPD file from the server.  The
1445 list of available PPDs is provided by the IPP <code>CUPS_GET_PPDS</code>
1446 operation.<br>
1447 <br>
1448 You must remove (unlink) the PPD file when you are finished with
1449 it. The PPD filename is stored in a static location that will be
1450 overwritten on the next call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a>, <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>,
1451 or <a href="#cupsGetServerPPD"><code>cupsGetServerPPD</code></a>.
1452
1453 </p>
1454 <h3 class="function"><a name="cupsLangDefault">cupsLangDefault</a></h3>
1455 <p class="description">Return the default language.</p>
1456 <p class="code">
1457 cups_lang_t *cupsLangDefault (void);</p>
1458 <h4 class="returnvalue">Return Value</h4>
1459 <p class="description">Language data</p>
1460 <h3 class="function"><a name="cupsLangEncoding">cupsLangEncoding</a></h3>
1461 <p class="description">Return the character encoding (us-ascii, etc.)
1462 for the given language.</p>
1463 <p class="code">
1464 const char *cupsLangEncoding (<br>
1465 &nbsp;&nbsp;&nbsp;&nbsp;cups_lang_t *lang<br>
1466 );</p>
1467 <h4 class="parameters">Parameters</h4>
1468 <dl>
1469 <dt>lang</dt>
1470 <dd class="description">Language data</dd>
1471 </dl>
1472 <h4 class="returnvalue">Return Value</h4>
1473 <p class="description">Character encoding</p>
1474 <h3 class="function"><a name="cupsLangFlush">cupsLangFlush</a></h3>
1475 <p class="description">Flush all language data out of the cache.</p>
1476 <p class="code">
1477 void cupsLangFlush (void);</p>
1478 <h3 class="function"><a name="cupsLangFree">cupsLangFree</a></h3>
1479 <p class="description">Free language data.</p>
1480 <p class="code">
1481 void cupsLangFree (<br>
1482 &nbsp;&nbsp;&nbsp;&nbsp;cups_lang_t *lang<br>
1483 );</p>
1484 <h4 class="parameters">Parameters</h4>
1485 <dl>
1486 <dt>lang</dt>
1487 <dd class="description">Language to free</dd>
1488 </dl>
1489 <h4 class="discussion">Discussion</h4>
1490 <p class="discussion">This does not actually free anything; use <a href="#cupsLangFlush"><code>cupsLangFlush</code></a> for that.</p>
1491 <h3 class="function"><a name="cupsLangGet">cupsLangGet</a></h3>
1492 <p class="description">Get a language.</p>
1493 <p class="code">
1494 cups_lang_t *cupsLangGet (<br>
1495 &nbsp;&nbsp;&nbsp;&nbsp;const char *language<br>
1496 );</p>
1497 <h4 class="parameters">Parameters</h4>
1498 <dl>
1499 <dt>language</dt>
1500 <dd class="description">Language or locale</dd>
1501 </dl>
1502 <h4 class="returnvalue">Return Value</h4>
1503 <p class="description">Language data</p>
1504 <h3 class="function"><a name="cupsLastError">cupsLastError</a></h3>
1505 <p class="description">Return the last IPP status code.</p>
1506 <p class="code">
1507 ipp_status_t cupsLastError (void);</p>
1508 <h4 class="returnvalue">Return Value</h4>
1509 <p class="description">IPP status code from last request</p>
1510 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsLastErrorString">cupsLastErrorString</a></h3>
1511 <p class="description">Return the last IPP status-message.</p>
1512 <p class="code">
1513 const char *cupsLastErrorString (void);</p>
1514 <h4 class="returnvalue">Return Value</h4>
1515 <p class="description">status-message text from last request</p>
1516 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsNotifySubject">cupsNotifySubject</a></h3>
1517 <p class="description">Return the subject for the given notification message.</p>
1518 <p class="code">
1519 char *cupsNotifySubject (<br>
1520 &nbsp;&nbsp;&nbsp;&nbsp;cups_lang_t *lang,<br>
1521 &nbsp;&nbsp;&nbsp;&nbsp;ipp_t *event<br>
1522 );</p>
1523 <h4 class="parameters">Parameters</h4>
1524 <dl>
1525 <dt>lang</dt>
1526 <dd class="description">Language data</dd>
1527 <dt>event</dt>
1528 <dd class="description">Event data</dd>
1529 </dl>
1530 <h4 class="returnvalue">Return Value</h4>
1531 <p class="description">Subject string or <code>NULL</code></p>
1532 <h4 class="discussion">Discussion</h4>
1533 <p class="discussion">The returned string must be freed by the caller using free().
1534
1535 </p>
1536 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsNotifyText">cupsNotifyText</a></h3>
1537 <p class="description">Return the text for the given notification message.</p>
1538 <p class="code">
1539 char *cupsNotifyText (<br>
1540 &nbsp;&nbsp;&nbsp;&nbsp;cups_lang_t *lang,<br>
1541 &nbsp;&nbsp;&nbsp;&nbsp;ipp_t *event<br>
1542 );</p>
1543 <h4 class="parameters">Parameters</h4>
1544 <dl>
1545 <dt>lang</dt>
1546 <dd class="description">Language data</dd>
1547 <dt>event</dt>
1548 <dd class="description">Event data</dd>
1549 </dl>
1550 <h4 class="returnvalue">Return Value</h4>
1551 <p class="description">Message text or <code>NULL</code></p>
1552 <h4 class="discussion">Discussion</h4>
1553 <p class="discussion">The returned string must be freed by the caller using <code>free</code>.
1554
1555 </p>
1556 <h3 class="function"><a name="cupsParseOptions">cupsParseOptions</a></h3>
1557 <p class="description">Parse options from a command-line argument.</p>
1558 <p class="code">
1559 int cupsParseOptions (<br>
1560 &nbsp;&nbsp;&nbsp;&nbsp;const char *arg,<br>
1561 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1562 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> **options<br>
1563 );</p>
1564 <h4 class="parameters">Parameters</h4>
1565 <dl>
1566 <dt>arg</dt>
1567 <dd class="description">Argument to parse</dd>
1568 <dt>num_options</dt>
1569 <dd class="description">Number of options</dd>
1570 <dt>options</dt>
1571 <dd class="description">Options found</dd>
1572 </dl>
1573 <h4 class="returnvalue">Return Value</h4>
1574 <p class="description">Number of options found</p>
1575 <h4 class="discussion">Discussion</h4>
1576 <p class="discussion">This function converts space-delimited name/value pairs according
1577 to the PAPI text option ABNF specification. Collection values
1578 (&quot;name={a=... b=... c=...}&quot;) are stored with the curley brackets
1579 intact - use <code>cupsParseOptions</code> on the value to extract the
1580 collection attributes.</p>
1581 <h3 class="function"><a name="cupsPrintFile">cupsPrintFile</a></h3>
1582 <p class="description">Print a file to a printer or class on the default server.</p>
1583 <p class="code">
1584 int cupsPrintFile (<br>
1585 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1586 &nbsp;&nbsp;&nbsp;&nbsp;const char *filename,<br>
1587 &nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
1588 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1589 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> *options<br>
1590 );</p>
1591 <h4 class="parameters">Parameters</h4>
1592 <dl>
1593 <dt>name</dt>
1594 <dd class="description">Printer or class name</dd>
1595 <dt>filename</dt>
1596 <dd class="description">File to print</dd>
1597 <dt>title</dt>
1598 <dd class="description">Title of job</dd>
1599 <dt>num_options</dt>
1600 <dd class="description">Number of options</dd>
1601 <dt>options</dt>
1602 <dd class="description">Options</dd>
1603 </dl>
1604 <h4 class="returnvalue">Return Value</h4>
1605 <p class="description">Job ID or 0 on error</p>
1606 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21&nbsp;</span><a name="cupsPrintFile2">cupsPrintFile2</a></h3>
1607 <p class="description">Print a file to a printer or class on the specified
1608 server.</p>
1609 <p class="code">
1610 int cupsPrintFile2 (<br>
1611 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1612 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1613 &nbsp;&nbsp;&nbsp;&nbsp;const char *filename,<br>
1614 &nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
1615 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1616 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> *options<br>
1617 );</p>
1618 <h4 class="parameters">Parameters</h4>
1619 <dl>
1620 <dt>http</dt>
1621 <dd class="description">HTTP connection</dd>
1622 <dt>name</dt>
1623 <dd class="description">Printer or class name</dd>
1624 <dt>filename</dt>
1625 <dd class="description">File to print</dd>
1626 <dt>title</dt>
1627 <dd class="description">Title of job</dd>
1628 <dt>num_options</dt>
1629 <dd class="description">Number of options</dd>
1630 <dt>options</dt>
1631 <dd class="description">Options</dd>
1632 </dl>
1633 <h4 class="returnvalue">Return Value</h4>
1634 <p class="description">Job ID or 0 on error</p>
1635 <h3 class="function"><a name="cupsPrintFiles">cupsPrintFiles</a></h3>
1636 <p class="description">Print one or more files to a printer or class on the
1637 default server.</p>
1638 <p class="code">
1639 int cupsPrintFiles (<br>
1640 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1641 &nbsp;&nbsp;&nbsp;&nbsp;int num_files,<br>
1642 &nbsp;&nbsp;&nbsp;&nbsp;const char **files,<br>
1643 &nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
1644 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1645 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> *options<br>
1646 );</p>
1647 <h4 class="parameters">Parameters</h4>
1648 <dl>
1649 <dt>name</dt>
1650 <dd class="description">Printer or class name</dd>
1651 <dt>num_files</dt>
1652 <dd class="description">Number of files</dd>
1653 <dt>files</dt>
1654 <dd class="description">File(s) to print</dd>
1655 <dt>title</dt>
1656 <dd class="description">Title of job</dd>
1657 <dt>num_options</dt>
1658 <dd class="description">Number of options</dd>
1659 <dt>options</dt>
1660 <dd class="description">Options</dd>
1661 </dl>
1662 <h4 class="returnvalue">Return Value</h4>
1663 <p class="description">Job ID or 0 on error</p>
1664 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21&nbsp;</span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3>
1665 <p class="description">Print one or more files to a printer or class on the
1666 specified server.</p>
1667 <p class="code">
1668 int cupsPrintFiles2 (<br>
1669 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1670 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1671 &nbsp;&nbsp;&nbsp;&nbsp;int num_files,<br>
1672 &nbsp;&nbsp;&nbsp;&nbsp;const char **files,<br>
1673 &nbsp;&nbsp;&nbsp;&nbsp;const char *title,<br>
1674 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1675 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> *options<br>
1676 );</p>
1677 <h4 class="parameters">Parameters</h4>
1678 <dl>
1679 <dt>http</dt>
1680 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1681 <dt>name</dt>
1682 <dd class="description">Printer or class name</dd>
1683 <dt>num_files</dt>
1684 <dd class="description">Number of files</dd>
1685 <dt>files</dt>
1686 <dd class="description">File(s) to print</dd>
1687 <dt>title</dt>
1688 <dd class="description">Title of job</dd>
1689 <dt>num_options</dt>
1690 <dd class="description">Number of options</dd>
1691 <dt>options</dt>
1692 <dd class="description">Options</dd>
1693 </dl>
1694 <h4 class="returnvalue">Return Value</h4>
1695 <p class="description">Job ID or 0 on error</p>
1696 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.20&nbsp;</span><a name="cupsPutFd">cupsPutFd</a></h3>
1697 <p class="description">Put a file on the server.</p>
1698 <p class="code">
1699 http_status_t cupsPutFd (<br>
1700 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1701 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1702 &nbsp;&nbsp;&nbsp;&nbsp;int fd<br>
1703 );</p>
1704 <h4 class="parameters">Parameters</h4>
1705 <dl>
1706 <dt>http</dt>
1707 <dd class="description">HTTP connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1708 <dt>resource</dt>
1709 <dd class="description">Resource name</dd>
1710 <dt>fd</dt>
1711 <dd class="description">File descriptor</dd>
1712 </dl>
1713 <h4 class="returnvalue">Return Value</h4>
1714 <p class="description">HTTP status</p>
1715 <h4 class="discussion">Discussion</h4>
1716 <p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored
1717 successfully.
1718
1719 </p>
1720 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.20&nbsp;</span><a name="cupsPutFile">cupsPutFile</a></h3>
1721 <p class="description">Put a file on the server.</p>
1722 <p class="code">
1723 http_status_t cupsPutFile (<br>
1724 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1725 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1726 &nbsp;&nbsp;&nbsp;&nbsp;const char *filename<br>
1727 );</p>
1728 <h4 class="parameters">Parameters</h4>
1729 <dl>
1730 <dt>http</dt>
1731 <dd class="description">HTTP connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1732 <dt>resource</dt>
1733 <dd class="description">Resource name</dd>
1734 <dt>filename</dt>
1735 <dd class="description">Filename</dd>
1736 </dl>
1737 <h4 class="returnvalue">Return Value</h4>
1738 <p class="description">HTTP status</p>
1739 <h4 class="discussion">Discussion</h4>
1740 <p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored
1741 successfully.
1742
1743 </p>
1744 <h3 class="function"><span class="info">&nbsp;CUPS 1.3&nbsp;</span><a name="cupsRemoveDest">cupsRemoveDest</a></h3>
1745 <p class="description">Remove a destination from the destination list.</p>
1746 <p class="code">
1747 int cupsRemoveDest (<br>
1748 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1749 &nbsp;&nbsp;&nbsp;&nbsp;const char *instance,<br>
1750 &nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
1751 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dest_t">cups_dest_t</a> **dests<br>
1752 );</p>
1753 <h4 class="parameters">Parameters</h4>
1754 <dl>
1755 <dt>name</dt>
1756 <dd class="description">Destination name</dd>
1757 <dt>instance</dt>
1758 <dd class="description">Instance name or <code>NULL</code></dd>
1759 <dt>num_dests</dt>
1760 <dd class="description">Number of destinations</dd>
1761 <dt>dests</dt>
1762 <dd class="description">Destinations</dd>
1763 </dl>
1764 <h4 class="returnvalue">Return Value</h4>
1765 <p class="description">New number of destinations</p>
1766 <h4 class="discussion">Discussion</h4>
1767 <p class="discussion">Removing a destination/instance does not delete the class or printer
1768 queue, merely the lpoptions for that destination/instance.  Use the
1769 <a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new
1770 options for the user.
1771
1772 </p>
1773 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsRemoveOption">cupsRemoveOption</a></h3>
1774 <p class="description">Remove an option from an option array.</p>
1775 <p class="code">
1776 int cupsRemoveOption (<br>
1777 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1778 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1779 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> **options<br>
1780 );</p>
1781 <h4 class="parameters">Parameters</h4>
1782 <dl>
1783 <dt>name</dt>
1784 <dd class="description">Option name</dd>
1785 <dt>num_options</dt>
1786 <dd class="description">Current number of options</dd>
1787 <dt>options</dt>
1788 <dd class="description">Options</dd>
1789 </dl>
1790 <h4 class="returnvalue">Return Value</h4>
1791 <p class="description">New number of options</p>
1792 <h3 class="function"><a name="cupsServer">cupsServer</a></h3>
1793 <p class="description">Return the hostname/address of the default server.</p>
1794 <p class="code">
1795 const char *cupsServer (void);</p>
1796 <h4 class="returnvalue">Return Value</h4>
1797 <p class="description">Server name</p>
1798 <h4 class="discussion">Discussion</h4>
1799 <p class="discussion">The returned value can be a fully-qualified hostname, a numeric
1800 IPv4 or IPv6 address, or a domain socket pathname.</p>
1801 <h3 class="function"><span class="info">&nbsp;CUPS 1.3&nbsp;</span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
1802 <p class="description">Set the default destination.</p>
1803 <p class="code">
1804 void cupsSetDefaultDest (<br>
1805 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1806 &nbsp;&nbsp;&nbsp;&nbsp;const char *instance,<br>
1807 &nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
1808 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
1809 );</p>
1810 <h4 class="parameters">Parameters</h4>
1811 <dl>
1812 <dt>name</dt>
1813 <dd class="description">Destination name</dd>
1814 <dt>instance</dt>
1815 <dd class="description">Instance name or <code>NULL</code></dd>
1816 <dt>num_dests</dt>
1817 <dd class="description">Number of destinations</dd>
1818 <dt>dests</dt>
1819 <dd class="description">Destinations</dd>
1820 </dl>
1821 <h3 class="function"><a name="cupsSetDests">cupsSetDests</a></h3>
1822 <p class="description">Save the list of destinations for the default server.</p>
1823 <p class="code">
1824 void cupsSetDests (<br>
1825 &nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
1826 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
1827 );</p>
1828 <h4 class="parameters">Parameters</h4>
1829 <dl>
1830 <dt>num_dests</dt>
1831 <dd class="description">Number of destinations</dd>
1832 <dt>dests</dt>
1833 <dd class="description">Destinations</dd>
1834 </dl>
1835 <h4 class="discussion">Discussion</h4>
1836 <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
1837 as root and ~/.cups/lpoptions when run as a normal user.</p>
1838 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21&nbsp;</span><a name="cupsSetDests2">cupsSetDests2</a></h3>
1839 <p class="description">Save the list of destinations for the specified server.</p>
1840 <p class="code">
1841 int cupsSetDests2 (<br>
1842 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1843 &nbsp;&nbsp;&nbsp;&nbsp;int num_dests,<br>
1844 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dest_t">cups_dest_t</a> *dests<br>
1845 );</p>
1846 <h4 class="parameters">Parameters</h4>
1847 <dl>
1848 <dt>http</dt>
1849 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1850 <dt>num_dests</dt>
1851 <dd class="description">Number of destinations</dd>
1852 <dt>dests</dt>
1853 <dd class="description">Destinations</dd>
1854 </dl>
1855 <h4 class="returnvalue">Return Value</h4>
1856 <p class="description">0 on success, -1 on error</p>
1857 <h4 class="discussion">Discussion</h4>
1858 <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
1859 as root and ~/.cups/lpoptions when run as a normal user.
1860
1861 </p>
1862 <h3 class="function"><a name="cupsSetEncryption">cupsSetEncryption</a></h3>
1863 <p class="description">Set the encryption preference.</p>
1864 <p class="code">
1865 void cupsSetEncryption (<br>
1866 &nbsp;&nbsp;&nbsp;&nbsp;http_encryption_t e<br>
1867 );</p>
1868 <h4 class="parameters">Parameters</h4>
1869 <dl>
1870 <dt>e</dt>
1871 <dd class="description">New encryption preference</dd>
1872 </dl>
1873 <h3 class="function"><a name="cupsSetPasswordCB">cupsSetPasswordCB</a></h3>
1874 <p class="description">Set the password callback for CUPS.</p>
1875 <p class="code">
1876 void cupsSetPasswordCB (<br>
1877 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_password_cb_t">cups_password_cb_t</a> cb<br>
1878 );</p>
1879 <h4 class="parameters">Parameters</h4>
1880 <dl>
1881 <dt>cb</dt>
1882 <dd class="description">Callback function</dd>
1883 </dl>
1884 <h4 class="discussion">Discussion</h4>
1885 <p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback.</p>
1886 <h3 class="function"><a name="cupsSetServer">cupsSetServer</a></h3>
1887 <p class="description">Set the default server name.</p>
1888 <p class="code">
1889 void cupsSetServer (<br>
1890 &nbsp;&nbsp;&nbsp;&nbsp;const char *server<br>
1891 );</p>
1892 <h4 class="parameters">Parameters</h4>
1893 <dl>
1894 <dt>server</dt>
1895 <dd class="description">Server name</dd>
1896 </dl>
1897 <h4 class="discussion">Discussion</h4>
1898 <p class="discussion">The &quot;server&quot; string can be a fully-qualified hostname, a numeric
1899 IPv4 or IPv6 address, or a domain socket pathname. Pass <code>NULL</code> to
1900 restore the default server name.</p>
1901 <h3 class="function"><a name="cupsSetUser">cupsSetUser</a></h3>
1902 <p class="description">Set the default user name.</p>
1903 <p class="code">
1904 void cupsSetUser (<br>
1905 &nbsp;&nbsp;&nbsp;&nbsp;const char *user<br>
1906 );</p>
1907 <h4 class="parameters">Parameters</h4>
1908 <dl>
1909 <dt>user</dt>
1910 <dd class="description">User name</dd>
1911 </dl>
1912 <h4 class="discussion">Discussion</h4>
1913 <p class="discussion">Pass <code>NULL</code> to restore the default user name.</p>
1914 <h3 class="function"><span class="info">&nbsp;CUPS 1.4&nbsp;</span><a name="cupsStartDocument">cupsStartDocument</a></h3>
1915 <p class="description">Add a document to a job created with cupsCreateJob().</p>
1916 <p class="code">
1917 http_status_t cupsStartDocument (<br>
1918 &nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
1919 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1920 &nbsp;&nbsp;&nbsp;&nbsp;int job_id,<br>
1921 &nbsp;&nbsp;&nbsp;&nbsp;const char *docname,<br>
1922 &nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
1923 &nbsp;&nbsp;&nbsp;&nbsp;int last_document<br>
1924 );</p>
1925 <h4 class="parameters">Parameters</h4>
1926 <dl>
1927 <dt>http</dt>
1928 <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd>
1929 <dt>name</dt>
1930 <dd class="description">Printer or class name</dd>
1931 <dt>job_id</dt>
1932 <dd class="description">Job ID from <a href="#cupsCreateJob"><code>cupsCreateJob</code></a></dd>
1933 <dt>docname</dt>
1934 <dd class="description">Name of document</dd>
1935 <dt>format</dt>
1936 <dd class="description">MIME type or <code>CUPS_FORMAT_foo</code></dd>
1937 <dt>last_document</dt>
1938 <dd class="description">1 for last document in job, 0 otherwise</dd>
1939 </dl>
1940 <h4 class="returnvalue">Return Value</h4>
1941 <p class="description">HTTP status of request</p>
1942 <h4 class="discussion">Discussion</h4>
1943 <p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write data for the document and
1944 <a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> to finish the document and get the submission status.<br>
1945 <br>
1946 The MIME type constants <code>CUPS_FORMAT_AUTO</code>, <code>CUPS_FORMAT_PDF</code>,
1947 <code>CUPS_FORMAT_POSTSCRIPT</code>, <code>CUPS_FORMAT_RAW</code>, and
1948 <code>CUPS_FORMAT_TEXT</code> are provided for the &quot;format&quot; argument, although
1949 any supported MIME type string can be supplied.
1950
1951 </p>
1952 <h3 class="function"><a name="cupsTempFd">cupsTempFd</a></h3>
1953 <p class="description">Creates a temporary file.</p>
1954 <p class="code">
1955 int cupsTempFd (<br>
1956 &nbsp;&nbsp;&nbsp;&nbsp;char *filename,<br>
1957 &nbsp;&nbsp;&nbsp;&nbsp;int len<br>
1958 );</p>
1959 <h4 class="parameters">Parameters</h4>
1960 <dl>
1961 <dt>filename</dt>
1962 <dd class="description">Pointer to buffer</dd>
1963 <dt>len</dt>
1964 <dd class="description">Size of buffer</dd>
1965 </dl>
1966 <h4 class="returnvalue">Return Value</h4>
1967 <p class="description">New file descriptor or -1 on error</p>
1968 <h4 class="discussion">Discussion</h4>
1969 <p class="discussion">The temporary filename is returned in the filename buffer.
1970 The temporary file is opened for reading and writing.</p>
1971 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="cupsTempFile">cupsTempFile</a></h3>
1972 <p class="description">Generates a temporary filename.</p>
1973 <p class="code">
1974 char *cupsTempFile (<br>
1975 &nbsp;&nbsp;&nbsp;&nbsp;char *filename,<br>
1976 &nbsp;&nbsp;&nbsp;&nbsp;int len<br>
1977 );</p>
1978 <h4 class="parameters">Parameters</h4>
1979 <dl>
1980 <dt>filename</dt>
1981 <dd class="description">Pointer to buffer</dd>
1982 <dt>len</dt>
1983 <dd class="description">Size of buffer</dd>
1984 </dl>
1985 <h4 class="returnvalue">Return Value</h4>
1986 <p class="description">Filename or NULL on error</p>
1987 <h4 class="discussion">Discussion</h4>
1988 <p class="discussion">The temporary filename is returned in the filename buffer.
1989 This function is deprecated - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or
1990 <a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead.
1991
1992 </p>
1993 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsTempFile2">cupsTempFile2</a></h3>
1994 <p class="description">Creates a temporary CUPS file.</p>
1995 <p class="code">
1996 cups_file_t *cupsTempFile2 (<br>
1997 &nbsp;&nbsp;&nbsp;&nbsp;char *filename,<br>
1998 &nbsp;&nbsp;&nbsp;&nbsp;int len<br>
1999 );</p>
2000 <h4 class="parameters">Parameters</h4>
2001 <dl>
2002 <dt>filename</dt>
2003 <dd class="description">Pointer to buffer</dd>
2004 <dt>len</dt>
2005 <dd class="description">Size of buffer</dd>
2006 </dl>
2007 <h4 class="returnvalue">Return Value</h4>
2008 <p class="description">CUPS file or NULL on error</p>
2009 <h4 class="discussion">Discussion</h4>
2010 <p class="discussion">The temporary filename is returned in the filename buffer.
2011 The temporary file is opened for writing.
2012
2013 </p>
2014 <h3 class="function"><a name="cupsUser">cupsUser</a></h3>
2015 <p class="description">Return the current user's name.</p>
2016 <p class="code">
2017 const char *cupsUser (void);</p>
2018 <h4 class="returnvalue">Return Value</h4>
2019 <p class="description">User name</p>
2020 <h2 class="title"><a name="TYPES">Data Types</a></h2>
2021 <h3 class="typedef"><a name="cups_dest_t">cups_dest_t</a></h3>
2022 <p class="description">Destination</p>
2023 <p class="code">
2024 typedef struct <a href="#cups_dest_s">cups_dest_s</a> cups_dest_t;
2025 </p>
2026 <h3 class="typedef"><a name="cups_job_t">cups_job_t</a></h3>
2027 <p class="description">Job</p>
2028 <p class="code">
2029 typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t;
2030 </p>
2031 <h3 class="typedef"><a name="cups_option_t">cups_option_t</a></h3>
2032 <p class="description">Printer Options</p>
2033 <p class="code">
2034 typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t;
2035 </p>
2036 <h3 class="typedef"><a name="cups_password_cb_t">cups_password_cb_t</a></h3>
2037 <p class="description">Password callback</p>
2038 <p class="code">
2039 typedef const char *(*cups_password_cb_t)(const char *);
2040 </p>
2041 <h3 class="typedef"><a name="cups_ptype_t">cups_ptype_t</a></h3>
2042 <p class="description">Printer type/capability bits</p>
2043 <p class="code">
2044 typedef unsigned cups_ptype_t;
2045 </p>
2046 <h2 class="title"><a name="STRUCTURES">Structures</a></h2>
2047 <h3 class="struct"><a name="cups_dest_s">cups_dest_s</a></h3>
2048 <p class="description">Destination</p>
2049 <p class="code">struct cups_dest_s {<br>
2050 &nbsp;&nbsp;&nbsp;&nbsp;char *name, *instance;<br>
2051 &nbsp;&nbsp;&nbsp;&nbsp;int is_default;<br>
2052 &nbsp;&nbsp;&nbsp;&nbsp;int num_options;<br>
2053 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_option_t">cups_option_t</a> *options;<br>
2054 };</p>
2055 <h4 class="members">Members</h4>
2056 <dl>
2057 <dt>instance </dt>
2058 <dd class="description">Local instance name or NULL</dd>
2059 <dt>is_default </dt>
2060 <dd class="description">Is this printer the default?</dd>
2061 <dt>num_options </dt>
2062 <dd class="description">Number of options</dd>
2063 <dt>options </dt>
2064 <dd class="description">Options</dd>
2065 </dl>
2066 <h3 class="struct"><a name="cups_job_s">cups_job_s</a></h3>
2067 <p class="description">Job</p>
2068 <p class="code">struct cups_job_s {<br>
2069 &nbsp;&nbsp;&nbsp;&nbsp;time_t completed_time;<br>
2070 &nbsp;&nbsp;&nbsp;&nbsp;time_t creation_time;<br>
2071 &nbsp;&nbsp;&nbsp;&nbsp;char *dest;<br>
2072 &nbsp;&nbsp;&nbsp;&nbsp;char *format;<br>
2073 &nbsp;&nbsp;&nbsp;&nbsp;int id;<br>
2074 &nbsp;&nbsp;&nbsp;&nbsp;int priority;<br>
2075 &nbsp;&nbsp;&nbsp;&nbsp;time_t processing_time;<br>
2076 &nbsp;&nbsp;&nbsp;&nbsp;int size;<br>
2077 &nbsp;&nbsp;&nbsp;&nbsp;ipp_jstate_t state;<br>
2078 &nbsp;&nbsp;&nbsp;&nbsp;char *title;<br>
2079 &nbsp;&nbsp;&nbsp;&nbsp;char *user;<br>
2080 };</p>
2081 <h4 class="members">Members</h4>
2082 <dl>
2083 <dt>completed_time </dt>
2084 <dd class="description">Time the job was completed</dd>
2085 <dt>creation_time </dt>
2086 <dd class="description">Time the job was created</dd>
2087 <dt>dest </dt>
2088 <dd class="description">Printer or class name</dd>
2089 <dt>format </dt>
2090 <dd class="description">Document format</dd>
2091 <dt>id </dt>
2092 <dd class="description">The job ID</dd>
2093 <dt>priority </dt>
2094 <dd class="description">Priority (1-100)</dd>
2095 <dt>processing_time </dt>
2096 <dd class="description">Time the job was processed</dd>
2097 <dt>size </dt>
2098 <dd class="description">Size in kilobytes</dd>
2099 <dt>state </dt>
2100 <dd class="description">Job state</dd>
2101 <dt>title </dt>
2102 <dd class="description">Title/job name</dd>
2103 <dt>user </dt>
2104 <dd class="description">User the submitted the job</dd>
2105 </dl>
2106 <h3 class="struct"><a name="cups_option_s">cups_option_s</a></h3>
2107 <p class="description">Printer Options</p>
2108 <p class="code">struct cups_option_s {<br>
2109 &nbsp;&nbsp;&nbsp;&nbsp;char *name;<br>
2110 &nbsp;&nbsp;&nbsp;&nbsp;char *value;<br>
2111 };</p>
2112 <h4 class="members">Members</h4>
2113 <dl>
2114 <dt>name </dt>
2115 <dd class="description">Name of option</dd>
2116 <dt>value </dt>
2117 <dd class="description">Value of option</dd>
2118 </dl>
2119 <h2 class="title"><a name="ENUMERATIONS">Constants</a></h2>
2120 <h3 class="enumeration"><a name="cups_ptype_e">cups_ptype_e</a></h3>
2121 <p class="description">Printer type/capability bit constants</p>
2122 <h4 class="constants">Constants</h4>
2123 <dl>
2124 <dt>CUPS_PRINTER_AUTHENTICATED <span class="info">&nbsp;CUPS 1.2&nbsp;</span></dt>
2125 <dd class="description">Printer requires authentication </dd>
2126 <dt>CUPS_PRINTER_BIND </dt>
2127 <dd class="description">Can bind output</dd>
2128 <dt>CUPS_PRINTER_BW </dt>
2129 <dd class="description">Can do B&amp;W printing</dd>
2130 <dt>CUPS_PRINTER_CLASS </dt>
2131 <dd class="description">Printer class</dd>
2132 <dt>CUPS_PRINTER_COLLATE </dt>
2133 <dd class="description">Can collage copies</dd>
2134 <dt>CUPS_PRINTER_COLOR </dt>
2135 <dd class="description">Can do color printing</dd>
2136 <dt>CUPS_PRINTER_COMMANDS <span class="info">&nbsp;CUPS 1.2&nbsp;</span></dt>
2137 <dd class="description">Printer supports maintenance commands </dd>
2138 <dt>CUPS_PRINTER_COPIES </dt>
2139 <dd class="description">Can do copies</dd>
2140 <dt>CUPS_PRINTER_COVER </dt>
2141 <dd class="description">Can cover output</dd>
2142 <dt>CUPS_PRINTER_DEFAULT </dt>
2143 <dd class="description">Default printer on network</dd>
2144 <dt>CUPS_PRINTER_DELETE <span class="info">&nbsp;CUPS 1.2&nbsp;</span></dt>
2145 <dd class="description">Delete printer </dd>
2146 <dt>CUPS_PRINTER_DISCOVERED <span class="info">&nbsp;CUPS 1.3&nbsp;</span></dt>
2147 <dd class="description">Printer was automatically discovered and added </dd>
2148 <dt>CUPS_PRINTER_DUPLEX </dt>
2149 <dd class="description">Can do duplexing</dd>
2150 <dt>CUPS_PRINTER_FAX </dt>
2151 <dd class="description">Fax queue</dd>
2152 <dt>CUPS_PRINTER_IMPLICIT </dt>
2153 <dd class="description">Implicit class</dd>
2154 <dt>CUPS_PRINTER_LARGE </dt>
2155 <dd class="description">Can do D/E/A1/A0</dd>
2156 <dt>CUPS_PRINTER_LOCAL </dt>
2157 <dd class="description">Local printer or class</dd>
2158 <dt>CUPS_PRINTER_MEDIUM </dt>
2159 <dd class="description">Can do Tabloid/B/C/A3/A2</dd>
2160 <dt>CUPS_PRINTER_NOT_SHARED <span class="info">&nbsp;CUPS 1.2&nbsp;</span></dt>
2161 <dd class="description">Printer is not shared </dd>
2162 <dt>CUPS_PRINTER_PUNCH </dt>
2163 <dd class="description">Can punch output</dd>
2164 <dt>CUPS_PRINTER_REJECTING </dt>
2165 <dd class="description">Printer is rejecting jobs</dd>
2166 <dt>CUPS_PRINTER_REMOTE </dt>
2167 <dd class="description">Remote printer or class</dd>
2168 <dt>CUPS_PRINTER_SMALL </dt>
2169 <dd class="description">Can do Letter/Legal/A4</dd>
2170 <dt>CUPS_PRINTER_SORT </dt>
2171 <dd class="description">Can sort output</dd>
2172 <dt>CUPS_PRINTER_STAPLE </dt>
2173 <dd class="description">Can staple output</dd>
2174 <dt>CUPS_PRINTER_VARIABLE </dt>
2175 <dd class="description">Can do variable sizes</dd>
2176 </dl>
2177 </div>
2178 </body>
2179 </html>