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