doc/help/api-cups.html

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