doc/help/api-cups.html

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