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