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