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