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