doc/help/api-cups.html

   1 <!doctype html>
   2 <html>
   3 <!-- SECTION: Programming -->
   4   <head>
   5     <title>CUPS API</title>
   6     <meta name="keywords" content="Programming">
   7     <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
   8     <meta name="creator" content="Mini-XML v2.11">
   9     <meta name="author" content="Unknown">
  10     <meta name="copyright" content="Unknown">
  11     <style type="text/css"><!--
  12 BODY {
  13   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  14 }
  15
  16 H1, H2, H3, H4, H5, H6, P, TD, TH {
  17   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  18 }
  19
  20 KBD {
  21   font-family: monaco, courier, monospace;
  22   font-weight: bold;
  23 }
  24
  25 PRE {
  26   font-family: monaco, courier, monospace;
  27 }
  28
  29 PRE.command {
  30   border: dotted thin #7f7f7f;
  31   margin-left: 36pt;
  32   padding: 10px;
  33 }
  34
  35 P.compact {
  36   margin: 0;
  37 }
  38
  39 P.example {
  40   font-style: italic;
  41   margin-left: 36pt;
  42 }
  43
  44 DL.man DD {
  45   margin-left: 5em;
  46 }
  47
  48 DL.man DT {
  49   margin-left: 0;
  50 }
  51
  52 PRE.man {
  53   margin: 0;
  54 }
  55
  56 PRE.example {
  57   background: #eeeeee;
  58   border: dotted thin #999999;
  59   margin-left: 36pt;
  60   padding: 10pt;
  61 }
  62
  63 PRE.command EM, PRE.example EM {
  64   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  65 }
  66
  67 P.command {
  68   font-family: monaco, courier, monospace;
  69   margin-left: 36pt;
  70 }
  71
  72 P.formula {
  73   font-style: italic;
  74   margin-left: 36pt;
  75 }
  76
  77 BLOCKQUOTE {
  78   background: #eeeeee;
  79   border: solid thin #999999;
  80   padding: 10pt;
  81 }
  82
  83 A IMG {
  84   border: none;
  85 }
  86
  87 A:link:hover IMG {
  88   background: #f0f0f0;
  89   border-radius: 10px;
  90   -moz-border-radius: 10px;
  91 }
  92
  93 A:link, A:visited {
  94   font-weight: inherit;
  95   text-decoration: none;
  96 }
  97
  98 A:link:hover, A:visited:hover, A:active {
  99   text-decoration: underline;
 100 }
 101
 102 SUB, SUP {
 103   font-size: 50%;
 104 }
 105
 106 TR.data, TD.data, TR.data TD {
 107   margin-top: 10pt;
 108   padding: 5pt;
 109   border-bottom: solid 1pt #999999;
 110 }
 111
 112 TR.data TH {
 113   border-bottom: solid 1pt #999999;
 114   padding-top: 10pt;
 115   padding-left: 5pt;
 116   text-align: left;
 117 }
 118
 119 DIV.table TABLE {
 120   border: solid thin #999999;
 121   border-collapse: collapse;
 122   border-spacing: 0;
 123   margin-left: auto;
 124   margin-right: auto;
 125 }
 126
 127 DIV.table CAPTION {
 128   caption-side: top;
 129   font-size: 120%;
 130   font-style: italic;
 131   font-weight: bold;
 132   margin-left: auto;
 133   margin-right: auto;
 134 }
 135
 136 DIV.table TABLE TD {
 137   border: solid thin #cccccc;
 138   padding-top: 5pt;
 139 }
 140
 141 DIV.table TABLE TH {
 142   background: #cccccc;
 143   border: none;
 144   border-bottom: solid thin #999999;
 145 }
 146
 147 DIV.figure TABLE {
 148   margin-left: auto;
 149   margin-right: auto;
 150 }
 151
 152 DIV.figure CAPTION {
 153   caption-side: bottom;
 154   font-size: 120%;
 155   font-style: italic;
 156   font-weight: bold;
 157   margin-left: auto;
 158   margin-right: auto;
 159 }
 160
 161 TH.label {
 162   text-align: right;
 163   vertical-align: top;
 164 }
 165
 166 TH.sublabel {
 167   text-align: right;
 168   font-weight: normal;
 169 }
 170
 171 HR {
 172   border: solid thin;
 173 }
 174
 175 SPAN.info {
 176   background: black;
 177   border: thin solid black;
 178   color: white;
 179   font-size: 80%;
 180   font-style: italic;
 181   font-weight: bold;
 182   white-space: nowrap;
 183 }
 184
 185 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 186   float: right;
 187   font-size: 100%;
 188 }
 189
 190 H1.title {
 191 }
 192
 193 H2.title, H3.title {
 194   border-bottom: solid 2pt #000000;
 195 }
 196
 197 DIV.indent, TABLE.indent {
 198   margin-top: 2em;
 199   margin-left: auto;
 200   margin-right: auto;
 201   width: 90%;
 202 }
 203
 204 TABLE.indent {
 205   border-collapse: collapse;
 206 }
 207
 208 TABLE.indent TD, TABLE.indent TH {
 209   padding: 0;
 210 }
 211
 212 TABLE.list {
 213   border-collapse: collapse;
 214   margin-left: auto;
 215   margin-right: auto;
 216   width: 90%;
 217 }
 218
 219 TABLE.list TH {
 220   background: white;
 221   border-bottom: solid thin #cccccc;
 222   color: #444444;
 223   padding-top: 10pt;
 224   padding-left: 5pt;
 225   text-align: left;
 226   vertical-align: bottom;
 227   white-space: nowrap;
 228 }
 229
 230 TABLE.list TH A {
 231   color: #4444cc;
 232 }
 233
 234 TABLE.list TD {
 235   border-bottom: solid thin #eeeeee;
 236   padding-top: 5pt;
 237   padding-left: 5pt;
 238 }
 239
 240 TABLE.list TR:nth-child(even) {
 241   background: #f8f8f8;
 242 }
 243
 244 TABLE.list TR:nth-child(odd) {
 245   background: #f4f4f4;
 246 }
 247
 248 DT {
 249   margin-left: 36pt;
 250   margin-top: 12pt;
 251 }
 252
 253 DD {
 254   margin-left: 54pt;
 255 }
 256
 257 DL.category DT {
 258   font-weight: bold;
 259 }
 260
 261 P.summary {
 262   margin-left: 36pt;
 263   font-family: monaco, courier, monospace;
 264 }
 265
 266 DIV.summary TABLE {
 267   border: solid thin #999999;
 268   border-collapse: collapse;
 269   border-spacing: 0;
 270   margin: 10px;
 271 }
 272
 273 DIV.summary TABLE TD, DIV.summary TABLE TH {
 274   border: solid thin #999999;
 275   padding: 5px;
 276   text-align: left;
 277   vertical-align: top;
 278 }
 279
 280 DIV.summary TABLE THEAD TH {
 281   background: #eeeeee;
 282 }
 283
 284 /* API documentation styles... */
 285 div.body h1 {
 286   margin: 0;
 287 }
 288 div.body h2 {
 289   margin-top: 1.5em;
 290 }
 291 div.body h3, div.body h4, div.body h5 {
 292   margin-bottom: 0.5em;
 293   margin-top: 1.5em;
 294 }
 295 .class, .enumeration, .function, .struct, .typedef, .union {
 296   border-bottom: solid thin #999999;
 297   margin-bottom: 0;
 298   margin-top: 2em;
 299 }
 300 .description {
 301   margin-top: 0.5em;
 302 }
 303 code, p.code, pre, ul.code li {
 304   font-family: monaco, courier, monospace;
 305   font-size: 90%;
 306 }
 307 ul.code, ul.contents, ul.subcontents {
 308   list-style-type: none;
 309   margin: 0;
 310   padding-left: 0;
 311 }
 312 ul.code li {
 313   margin: 0;
 314 }
 315 ul.contents > li {
 316   margin-top: 1em;
 317 }
 318 ul.contents li ul.code, ul.contents li ul.subcontents {
 319   padding-left: 2em;
 320 }
 321 div.body dl {
 322   margin-left: 0;
 323   margin-top: 0;
 324 }
 325 div.body dt {
 326   font-style: italic;
 327   margin-left: 0;
 328   margin-top: 0;
 329 }
 330 div.body dd {
 331   margin-bottom: 0.5em;
 332 }
 333
 334 /* This is just for the HTML files generated with the framedhelp target */
 335 div.contents {
 336   background: #e8e8e8;
 337   border: solid thin black;
 338   padding: 10px;
 339 }
 340 div.contents h1 {
 341   font-size: 110%;
 342 }
 343 div.contents h2 {
 344   font-size: 100%;
 345 }
 346 div.contents ul.contents {
 347   font-size: 80%;
 348 }
 349 div.contents ul.subcontents li {
 350   margin-left: 1em;
 351   text-indent: -1em;
 352 }
 353 --></style>
 354   </head>
 355   <body>
 356 <!--
 357   CUPS API header for CUPS.
 358
 359   Copyright 2008-2011 by Apple Inc.
 360
 361   These coded instructions, statements, and computer programs are the
 362   property of Apple Inc. and are protected by Federal copyright
 363   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 364   which should have been included with this file.  If this file is
 365   file is missing or damaged, see the license at "http://www.cups.org/".
 366 -->
 367
 368 <h1 class='title'>CUPS API</h1>
 369
 370 <div class='summary'><table summary='General Information'>
 371 <thead>
 372 <tr>
 373         <th>Header</th>
 374         <th>cups/cups.h</th>
 375 </tr>
 376 </thead>
 377 <tbody>
 378 <tr>
 379         <th>Library</th>
 380         <td>-lcups</td>
 381 </tr>
 382 <tr>
 383         <th>See Also</th>
 384         <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br>
 385         Programming: <a href='api-array.html' target='_top'>Array API</a><br>
 386         Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
 387         Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br>
 388         Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
 389         Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
 390         Programming: <a href='api-raster.html' target='_top'>Raster API</a></td>
 391 </tr>
 392 </tbody>
 393 </table></div>
 394     <div class="contents">
 395       <h2 class="title">Contents</h2>
 396       <ul class="contents">
 397         <li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
 398           <li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li>
 399           <li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li>
 400           <li><a href="#OPTIONS">Options</a></li>
 401           <li><a href="#PRINT_JOBS">Print Jobs</a></li>
 402           <li><a href="#ERROR_HANDLING">Error Handling</a></li>
 403           <li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li>
 404         </ul></li>
 405         <li><a href="#FUNCTIONS">Functions</a><ul class="subcontents">
 406           <li><a href="#cupsAddDest">cupsAddDest</a></li>
 407           <li><a href="#cupsAddOption">cupsAddOption</a></li>
 408           <li><a href="#cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></li>
 409           <li><a href="#cupsAdminExportSamba">cupsAdminExportSamba</a></li>
 410           <li><a href="#cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></li>
 411           <li><a href="#cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></li>
 412           <li><a href="#cupsCancelDestJob">cupsCancelDestJob</a></li>
 413           <li><a href="#cupsCancelJob">cupsCancelJob</a></li>
 414           <li><a href="#cupsCancelJob2">cupsCancelJob2</a></li>
 415           <li><a href="#cupsCheckDestSupported">cupsCheckDestSupported</a></li>
 416           <li><a href="#cupsCloseDestJob">cupsCloseDestJob</a></li>
 417           <li><a href="#cupsConnectDest">cupsConnectDest</a></li>
 418           <li><a href="#cupsConnectDestBlock">cupsConnectDestBlock</a></li>
 419           <li><a href="#cupsCopyDest">cupsCopyDest</a></li>
 420           <li><a href="#cupsCopyDestConflicts">cupsCopyDestConflicts</a></li>
 421           <li><a href="#cupsCopyDestInfo">cupsCopyDestInfo</a></li>
 422           <li><a href="#cupsCreateDestJob">cupsCreateDestJob</a></li>
 423           <li><a href="#cupsCreateJob">cupsCreateJob</a></li>
 424           <li><a href="#cupsEncryption">cupsEncryption</a></li>
 425           <li><a href="#cupsEnumDests">cupsEnumDests</a></li>
 426           <li><a href="#cupsEnumDestsBlock">cupsEnumDestsBlock</a></li>
 427           <li><a href="#cupsFindDestDefault">cupsFindDestDefault</a></li>
 428           <li><a href="#cupsFindDestReady">cupsFindDestReady</a></li>
 429           <li><a href="#cupsFindDestSupported">cupsFindDestSupported</a></li>
 430           <li><a href="#cupsFinishDestDocument">cupsFinishDestDocument</a></li>
 431           <li><a href="#cupsFinishDocument">cupsFinishDocument</a></li>
 432           <li><a href="#cupsFreeDestInfo">cupsFreeDestInfo</a></li>
 433           <li><a href="#cupsFreeDests">cupsFreeDests</a></li>
 434           <li><a href="#cupsFreeJobs">cupsFreeJobs</a></li>
 435           <li><a href="#cupsFreeOptions">cupsFreeOptions</a></li>
 436           <li><a href="#cupsGetClasses">cupsGetClasses</a></li>
 437           <li><a href="#cupsGetDefault">cupsGetDefault</a></li>
 438           <li><a href="#cupsGetDefault2">cupsGetDefault2</a></li>
 439           <li><a href="#cupsGetDest">cupsGetDest</a></li>
 440           <li><a href="#cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></li>
 441           <li><a href="#cupsGetDestMediaByName">cupsGetDestMediaByName</a></li>
 442           <li><a href="#cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></li>
 443           <li><a href="#cupsGetDestMediaCount">cupsGetDestMediaCount</a></li>
 444           <li><a href="#cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></li>
 445           <li><a href="#cupsGetDestWithURI">cupsGetDestWithURI</a></li>
 446           <li><a href="#cupsGetDests">cupsGetDests</a></li>
 447           <li><a href="#cupsGetDests2">cupsGetDests2</a></li>
 448           <li><a href="#cupsGetJobs">cupsGetJobs</a></li>
 449           <li><a href="#cupsGetJobs2">cupsGetJobs2</a></li>
 450           <li><a href="#cupsGetNamedDest">cupsGetNamedDest</a></li>
 451           <li><a href="#cupsGetOption">cupsGetOption</a></li>
 452           <li><a href="#cupsGetPassword">cupsGetPassword</a></li>
 453           <li><a href="#cupsGetPassword2">cupsGetPassword2</a></li>
 454           <li><a href="#cupsGetPrinters">cupsGetPrinters</a></li>
 455           <li><a href="#cupsLangDefault">cupsLangDefault</a></li>
 456           <li><a href="#cupsLangEncoding">cupsLangEncoding</a></li>
 457           <li><a href="#cupsLangFlush">cupsLangFlush</a></li>
 458           <li><a href="#cupsLangFree">cupsLangFree</a></li>
 459           <li><a href="#cupsLangGet">cupsLangGet</a></li>
 460           <li><a href="#cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></li>
 461           <li><a href="#cupsLocalizeDestOption">cupsLocalizeDestOption</a></li>
 462           <li><a href="#cupsLocalizeDestValue">cupsLocalizeDestValue</a></li>
 463           <li><a href="#cupsNotifySubject">cupsNotifySubject</a></li>
 464           <li><a href="#cupsNotifyText">cupsNotifyText</a></li>
 465           <li><a href="#cupsParseOptions">cupsParseOptions</a></li>
 466           <li><a href="#cupsPrintFile">cupsPrintFile</a></li>
 467           <li><a href="#cupsPrintFile2">cupsPrintFile2</a></li>
 468           <li><a href="#cupsPrintFiles">cupsPrintFiles</a></li>
 469           <li><a href="#cupsPrintFiles2">cupsPrintFiles2</a></li>
 470           <li><a href="#cupsRemoveDest">cupsRemoveDest</a></li>
 471           <li><a href="#cupsRemoveOption">cupsRemoveOption</a></li>
 472           <li><a href="#cupsServer">cupsServer</a></li>
 473           <li><a href="#cupsSetClientCertCB">cupsSetClientCertCB</a></li>
 474           <li><a href="#cupsSetCredentials">cupsSetCredentials</a></li>
 475           <li><a href="#cupsSetDefaultDest">cupsSetDefaultDest</a></li>
 476           <li><a href="#cupsSetDests">cupsSetDests</a></li>
 477           <li><a href="#cupsSetDests2">cupsSetDests2</a></li>
 478           <li><a href="#cupsSetEncryption">cupsSetEncryption</a></li>
 479           <li><a href="#cupsSetPasswordCB">cupsSetPasswordCB</a></li>
 480           <li><a href="#cupsSetPasswordCB2">cupsSetPasswordCB2</a></li>
 481           <li><a href="#cupsSetServer">cupsSetServer</a></li>
 482           <li><a href="#cupsSetServerCertCB">cupsSetServerCertCB</a></li>
 483           <li><a href="#cupsSetUser">cupsSetUser</a></li>
 484           <li><a href="#cupsSetUserAgent">cupsSetUserAgent</a></li>
 485           <li><a href="#cupsStartDestDocument">cupsStartDestDocument</a></li>
 486           <li><a href="#cupsStartDocument">cupsStartDocument</a></li>
 487           <li><a href="#cupsTempFd">cupsTempFd</a></li>
 488           <li><a href="#cupsTempFile">cupsTempFile</a></li>
 489           <li><a href="#cupsTempFile2">cupsTempFile2</a></li>
 490           <li><a href="#cupsUser">cupsUser</a></li>
 491           <li><a href="#cupsUserAgent">cupsUserAgent</a></li>
 492           <li><a href="#pwgFormatSizeName">pwgFormatSizeName</a></li>
 493           <li><a href="#pwgInitSize">pwgInitSize</a></li>
 494           <li><a href="#pwgMediaForLegacy">pwgMediaForLegacy</a></li>
 495           <li><a href="#pwgMediaForPPD">pwgMediaForPPD</a></li>
 496           <li><a href="#pwgMediaForPWG">pwgMediaForPWG</a></li>
 497           <li><a href="#pwgMediaForSize">pwgMediaForSize</a></li>
 498         </ul></li>
 499         <li><a href="#TYPES">Data Types</a><ul class="subcontents">
 500           <li><a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a></li>
 501           <li><a href="#cups_dest_block_t">cups_dest_block_t</a></li>
 502           <li><a href="#cups_dest_cb_t">cups_dest_cb_t</a></li>
 503           <li><a href="#cups_dest_t">cups_dest_t</a></li>
 504           <li><a href="#cups_dinfo_t">cups_dinfo_t</a></li>
 505           <li><a href="#cups_job_t">cups_job_t</a></li>
 506           <li><a href="#cups_option_t">cups_option_t</a></li>
 507           <li><a href="#cups_password_cb2_t">cups_password_cb2_t</a></li>
 508           <li><a href="#cups_password_cb_t">cups_password_cb_t</a></li>
 509           <li><a href="#cups_ptype_t">cups_ptype_t</a></li>
 510           <li><a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a></li>
 511           <li><a href="#cups_size_t">cups_size_t</a></li>
 512           <li><a href="#pwg_map_t">pwg_map_t</a></li>
 513           <li><a href="#pwg_media_t">pwg_media_t</a></li>
 514           <li><a href="#pwg_size_t">pwg_size_t</a></li>
 515         </ul></li>
 516         <li><a href="#STRUCTURES">Structures</a><ul class="subcontents">
 517           <li><a href="#cups_dest_s">cups_dest_s</a></li>
 518           <li><a href="#cups_job_s">cups_job_s</a></li>
 519           <li><a href="#cups_option_s">cups_option_s</a></li>
 520           <li><a href="#cups_size_s">cups_size_s</a></li>
 521           <li><a href="#pollfd">pollfd</a></li>
 522           <li><a href="#pwg_map_s">pwg_map_s</a></li>
 523           <li><a href="#pwg_media_s">pwg_media_s</a></li>
 524           <li><a href="#pwg_size_s">pwg_size_s</a></li>
 525         </ul></li>
 526         <li><a href="#VARIABLES">Variables</a><ul class="subcontents">
 527           <li><a href="#CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></li>
 528         </ul></li>
 529         <li><a href="#ENUMERATIONS">Enumerations</a><ul class="subcontents">
 530           <li><a href="#cups_ptype_e">cups_ptype_e</a></li>
 531         </ul></li>
 532       </ul>
 533     </div>
 534     <div class="body">
 535 <!--
 536   API introduction for CUPS.
 537
 538   Copyright 2007-2013 by Apple Inc.
 539   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 540
 541   These coded instructions, statements, and computer programs are the
 542   property of Apple Inc. and are protected by Federal copyright
 543   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 544   which should have been included with this file.  If this file is
 545   file is missing or damaged, see the license at "http://www.cups.org/".
 546 -->
 547
 548 <h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
 549
 550 <p>The CUPS API provides the convenience functions needed to support
 551 applications, filters, printer drivers, and backends that need to interface
 552 with the CUPS scheduler.</p>
 553
 554 <h3><a name='CLIENTS_AND_SERVERS'>Clients and Servers</a></h3>
 555
 556 <p>CUPS is based on the Internet Printing Protocol ("IPP"), which allows
 557 clients (applications) to communicate with a server (the scheduler) to get a
 558 list of printers, send print jobs, and so forth. You identify which server
 559 you want to communicate with using a pointer to the opaque structure
 560 <code>http_t</code>. All of the examples in this document use the
 561 <code>CUPS_HTTP_DEFAULT</code> constant, referring to the default connection
 562 to the scheduler. The <a href='api-httpipp.html' target='_top'>HTTP and IPP
 563 APIs</a> document provides more information on server connections.</p>
 564
 565 <h3><a name='PRINTERS_AND_CLASSES'>Printers and Classes</a></h3>
 566
 567 <p>Printers and classes (collections of printers) are accessed through
 568 the <a href="#cups_dest_t"><code>cups_dest_t</code></a> structure which
 569 includes the name (<code>name</code>), instance (<code>instance</code> -
 570 a way of selecting certain saved options/settings), and the options and
 571 attributes associated with that destination (<code>num_options</code> and
 572 <code>options</code>). Destinations are created using the
 573 <a href="#cupsGetDests"><code>cupsGetDests</code></a> function and freed
 574 using the <a href='#cupsFreeDests'><code>cupsFreeDests</code></a> function.
 575 The <a href='#cupsGetDest'><code>cupsGetDest</code></a> function finds a
 576 specific destination for printing:</p>
 577
 578 <pre class='example'>
 579 #include &lt;cups/cups.h&gt;
 580
 581 <a href='#cups_dest_t'>cups_dest_t</a> *dests;
 582 int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&amp;dests);
 583 <a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests);
 584
 585 /* do something with dest */
 586
 587 <a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
 588 </pre>
 589
 590 <p>Passing <code>NULL</code> to
 591 <a href='#cupsGetDest'><code>cupsGetDest</code></a> for the destination name
 592 will return the default destination. Similarly, passing a <code>NULL</code>
 593 instance will return the default instance for that destination.</p>
 594
 595 <div class='table'><table summary='Table 1: Printer Attributes' width='80%'>
 596 <caption>Table 1: <a name='TABLE1'>Printer Attributes</a></caption>
 597 <thead>
 598 <tr>
 599         <th>Attribute Name</th>
 600         <th>Description</th>
 601 </tr>
 602 </thead>
 603 <tbody>
 604 <tr>
 605         <td>"auth-info-required"</td>
 606         <td>The type of authentication required for printing to this
 607         destination: "none", "username,password", "domain,username,password",
 608         or "negotiate" (Kerberos)</td>
 609 </tr>
 610 <tr>
 611         <td>"printer-info"</td>
 612         <td>The human-readable description of the destination such as "My
 613         Laser Printer".</td>
 614 </tr>
 615 <tr>
 616         <td>"printer-is-accepting-jobs"</td>
 617         <td>"true" if the destination is accepting new jobs, "false" if
 618         not.</td>
 619 </tr>
 620 <tr>
 621         <td>"printer-is-shared"</td>
 622         <td>"true" if the destination is being shared with other computers,
 623         "false" if not.</td>
 624 </tr>
 625 <tr>
 626         <td>"printer-location"</td>
 627         <td>The human-readable location of the destination such as "Lab 4".</td>
 628 </tr>
 629 <tr>
 630         <td>"printer-make-and-model"</td>
 631         <td>The human-readable make and model of the destination such as "HP
 632         LaserJet 4000 Series".</td>
 633 </tr>
 634 <tr>
 635         <td>"printer-state"</td>
 636         <td>"3" if the destination is idle, "4" if the destination is printing
 637         a job, and "5" if the destination is stopped.</td>
 638 </tr>
 639 <tr>
 640         <td>"printer-state-change-time"</td>
 641         <td>The UNIX time when the destination entered the current state.</td>
 642 </tr>
 643 <tr>
 644         <td>"printer-state-reasons"</td>
 645         <td>Additional comma-delimited state keywords for the destination
 646         such as "media-tray-empty-error" and "toner-low-warning".</td>
 647 </tr>
 648 <tr>
 649         <td>"printer-type"</td>
 650         <td>The <a href='#cups_printer_t'><code>cups_printer_t</code></a>
 651         value associated with the destination.</td>
 652 </tr>
 653 </tbody>
 654 </table></div>
 655
 656 <h3><a name='OPTIONS'>Options</a></h3>
 657
 658 <p>Options are stored in arrays of
 659 <a href='#cups_option_t'><code>cups_option_t</code></a> structures. Each
 660 option has a name (<code>name</code>) and value (<code>value</code>)
 661 associated with it. The <a href='#cups_dest_t'><code>cups_dest_t</code></a>
 662 <code>num_options</code> and <code>options</code> members contain the
 663 default options for a particular destination, along with several informational
 664 attributes about the destination as shown in <a href='#TABLE1'>Table 1</a>.
 665 The <a href='#cupsGetOption'><code>cupsGetOption</code></a> function gets
 666 the value for the named option. For example, the following code lists the
 667 available destinations and their human-readable descriptions:</p>
 668
 669 <pre class='example'>
 670 #include &lt;cups/cups.h&gt;
 671
 672 <a href='#cups_dest_t'>cups_dest_t</a> *dests;
 673 int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&amp;dests);
 674 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 675 int i;
 676 const char *value;
 677
 678 for (i = num_dests, dest = dests; i > 0; i --, dest ++)
 679   if (dest->instance == NULL)
 680   {
 681     value = <a href='#cupsGetOption'>cupsGetOption</a>("printer-info", dest->num_options, dest->options);
 682     printf("%s (%s)\n", dest->name, value ? value : "no description");
 683   }
 684
 685 <a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
 686 </pre>
 687
 688 <p>You can create your own option arrays using the
 689 <a href='#cupsAddOption'><code>cupsAddOption</code></a> function, which
 690 adds a single named option to an array:</p>
 691
 692 <pre class='example'>
 693 #include &lt;cups/cups.h&gt;
 694
 695 int num_options = 0;
 696 <a href='#cups_option_t'>cups_option_t</a> *options = NULL;
 697
 698 /* The returned num_options value is updated as needed */
 699 num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "value", num_options, &amp;options);
 700
 701 /* This adds a second option value */
 702 num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &amp;options);
 703
 704 /* This replaces the first option we added */
 705 num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &amp;options);
 706 </pre>
 707
 708 <p>Use a <code>for</code> loop to copy the options from a destination:</p>
 709
 710 <pre class='example'>
 711 #include &lt;cups/cups.h&gt;
 712
 713 int i;
 714 int num_options = 0;
 715 <a href='#cups_option_t'>cups_option_t</a> *options = NULL;
 716 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 717
 718 for (i = 0; i &lt; dest->num_options; i ++)
 719   num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value,
 720                               num_options, &amp;options);
 721 </pre>
 722
 723 <p>Use the <a href='#cupsFreeOptions'><code>cupsFreeOptions</code></a>
 724 function to free the options array when you are done using it:</p>
 725
 726 <pre class='example'>
 727 <a href='#cupsFreeOptions'>cupsFreeOptions</a>(num_options, options);
 728 </pre>
 729
 730 <h3><a name='PRINT_JOBS'>Print Jobs</a></h3>
 731
 732 <p>Print jobs are identified by a locally-unique job ID number from 1 to
 733 2<sup>31</sup>-1 and have options and one or more files for printing to a
 734 single destination. The <a href='#cupsPrintFile'><code>cupsPrintFile</code></a>
 735 function creates a new job with one file. The following code prints the CUPS
 736 test page file:</p>
 737
 738 <pre class='example'>
 739 #include &lt;cups/cups.h&gt;
 740
 741 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 742 int num_options;
 743 <a href='#cups_option_t'>cups_option_t</a> *options;
 744 int job_id;
 745
 746 /* Print a single file */
 747 job_id = <a href='#cupsPrintFile'>cupsPrintFile</a>(dest->name, "/usr/share/cups/data/testprint.ps",
 748                         "Test Print", num_options, options);
 749 </pre>
 750
 751 <p>The <a href='#cupsPrintFiles'><code>cupsPrintFiles</code></a> function
 752 creates a job with multiple files. The files are provided in a
 753 <code>char *</code> array:</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 num_options;
 760 <a href='#cups_option_t'>cups_option_t</a> *options;
 761 int job_id;
 762 char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" };
 763
 764 /* Print three files */
 765 job_id = <a href='#cupsPrintFiles'>cupsPrintFiles</a>(dest->name, 3, files, "Test Print", num_options, options);
 766 </pre>
 767
 768 <p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a>
 769 function creates a new job with no files in it. Files are added using the
 770 <a href='#cupsStartDocument'><code>cupsStartDocument</code></a>,
 771 <a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>,
 772 and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions.
 773 The following example creates a job with 10 text files for printing:</p>
 774
 775 <pre class='example'>
 776 #include &lt;cups/cups.h&gt;
 777
 778 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 779 int num_options;
 780 <a href='#cups_option_t'>cups_option_t</a> *options;
 781 int job_id;
 782 int i;
 783 char buffer[1024];
 784
 785 /* Create the job */
 786 job_id = <a href='#cupsCreateJob'>cupsCreateJob</a>(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files",
 787                        num_options, options);
 788
 789 /* If the job is created, add 10 files */
 790 if (job_id > 0)
 791 {
 792   for (i = 1; i &lt;= 10; i ++)
 793   {
 794     snprintf(buffer, sizeof(buffer), "file%d.txt", i);
 795
 796     <a href='#cupsStartDocument'>cupsStartDocument</a>(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer,
 797                       CUPS_FORMAT_TEXT, i == 10);
 798
 799     snprintf(buffer, sizeof(buffer),
 800              "File %d\n"
 801              "\n"
 802              "One fish,\n"
 803              "Two fish,\n
 804              "Red fish,\n
 805              "Blue fish\n", i);
 806
 807     /* cupsWriteRequestData can be called as many times as needed */
 808     <a href='#cupsWriteRequestData'>cupsWriteRequestData</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));
 809
 810     <a href='#cupsFinishDocument'>cupsFinishDocument</a>(CUPS_HTTP_DEFAULT, dest->name);
 811   }
 812 }
 813 </pre>
 814
 815 <p>Once you have created a job, you can monitor its status using the
 816 <a href='#cupsGetJobs'><code>cupsGetJobs</code></a> function, which returns
 817 an array of <a href='#cups_job_t'><code>cups_job_t</code></a> structures.
 818 Each contains the job ID (<code>id</code>), destination name
 819 (<code>dest</code>), title (<code>title</code>), and other information
 820 associated with the job. The job array is freed using the
 821 <a href='#cupsFreeJobs'><code>cupsFreeJobs</code></a> function. The following
 822 example monitors a specific job ID, showing the current job state once every
 823 5 seconds until the job is completed:</p>
 824
 825 <pre class='example'>
 826 #include &lt;cups/cups.h&gt;
 827
 828 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 829 int job_id;
 830 int num_jobs;
 831 <a href='#cups_job_t'>cups_job_t</a> *jobs;
 832 int i;
 833 ipp_jstate_t job_state = IPP_JOB_PENDING;
 834
 835 while (job_state &lt; IPP_JOB_STOPPED)
 836 {
 837   /* Get my jobs (1) with any state (-1) */
 838   num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&amp;jobs, dest->name, 1, -1);
 839
 840   /* Loop to find my job */
 841   job_state = IPP_JOB_COMPLETED;
 842
 843   for (i = 0; i &lt; num_jobs; i ++)
 844     if (jobs[i].id == job_id)
 845     {
 846       job_state = jobs[i].state;
 847       break;
 848     }
 849
 850   /* Free the job array */
 851   <a href='#cupsFreeJobs'>cupsFreeJobs</a>(num_jobs, jobs);
 852
 853   /* Show the current state */
 854   switch (job_state)
 855   {
 856     case IPP_JOB_PENDING :
 857         printf("Job %d is pending.\n", job_id);
 858         break;
 859     case IPP_JOB_HELD :
 860         printf("Job %d is held.\n", job_id);
 861         break;
 862     case IPP_JOB_PROCESSING :
 863         printf("Job %d is processing.\n", job_id);
 864         break;
 865     case IPP_JOB_STOPPED :
 866         printf("Job %d is stopped.\n", job_id);
 867         break;
 868     case IPP_JOB_CANCELED :
 869         printf("Job %d is canceled.\n", job_id);
 870         break;
 871     case IPP_JOB_ABORTED :
 872         printf("Job %d is aborted.\n", job_id);
 873         break;
 874     case IPP_JOB_COMPLETED :
 875         printf("Job %d is completed.\n", job_id);
 876         break;
 877   }
 878
 879   /* Sleep if the job is not finished */
 880   if (job_state &lt; IPP_JOB_STOPPED)
 881     sleep(5);
 882 }
 883 </pre>
 884
 885 <p>To cancel a job, use the
 886 <a href='#cupsCancelJob'><code>cupsCancelJob</code></a> function with the
 887 job ID:</p>
 888
 889 <pre class='example'>
 890 #include &lt;cups/cups.h&gt;
 891
 892 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
 893 int job_id;
 894
 895 <a href='#cupsCancelJob'>cupsCancelJob</a>(dest->name, job_id);
 896 </pre>
 897
 898 <h3><a name='ERROR_HANDLING'>Error Handling</a></h3>
 899
 900 <p>If any of the CUPS API printing functions returns an error, the reason for
 901 that error can be found by calling the
 902 <a href='#cupsLastError'><code>cupsLastError</code></a> and
 903 <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> functions.
 904 <a href='#cupsLastError'><code>cupsLastError</code></a> returns the last IPP
 905 error code
 906 (<a href='api-httpipp.html#ipp_status_t'><code>ipp_status_t</code></a>)
 907 that was encountered, while
 908 <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> returns
 909 a (localized) human-readable string that can be shown to the user. For example,
 910 if any of the job creation functions returns a job ID of 0, you can use
 911 <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> to show
 912 the reason why the job could not be created:</p>
 913
 914 <pre class='example'>
 915 #include &lt;cups/cups.h&gt;
 916
 917 int job_id;
 918
 919 if (job_id == 0)
 920   puts(cupsLastErrorString());
 921 </pre>
 922
 923 <h3><a name='PASSWORDS_AND_AUTHENTICATION'>Passwords and Authentication</a></h3>
 924
 925 <p>CUPS supports authentication of any request, including submission of print
 926 jobs. The default mechanism for getting the username and password is to use the
 927 login user and a password from the console.</p>
 928
 929 <p>To support other types of applications, in particular Graphical User
 930 Interfaces ("GUIs"), the CUPS API provides functions to set the default
 931 username and to register a callback function that returns a password string.</p>
 932
 933 <p>The <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a>
 934 function is used to set a password callback in your program. Only one
 935 function can be used at any time.</p>
 936
 937 <p>The <a href="#cupsSetUser"><code>cupsSetUser</code></a> function sets the
 938 current username for authentication. This function can be called by your
 939 password callback function to change the current username as needed.</p>
 940
 941 <p>The following example shows a simple password callback that gets a
 942 username and password from the user:</p>
 943
 944 <pre class='example'>
 945 #include &lt;cups/cups.h&gt;
 946
 947 const char *
 948 my_password_cb(const char *prompt)
 949 {
 950   char  user[65];
 951
 952
 953   puts(prompt);
 954
 955   /* Get a username from the user */
 956   printf("Username: ");
 957   if (fgets(user, sizeof(user), stdin) == NULL)
 958     return (NULL);
 959
 960   /* Strip the newline from the string and set the user */
 961   user[strlen(user) - 1] = '\0';
 962
 963   <a href='#cupsSetUser'>cupsSetUser</a>(user);
 964
 965   /* Use getpass() to ask for the password... */
 966   return (getpass("Password: "));
 967 }
 968
 969 <a href='#cupsSetPasswordCB'>cupsSetPasswordCB</a>(my_password_cb);
 970 </pre>
 971
 972 <p>Similarly, a GUI could display the prompt string in a window with input
 973 fields for the username and password. The username should default to the
 974 string returned by the <a href="#cupsUser"><code>cupsUser</code></a>
 975 function.</p>
 976       <h2 class="title"><a id="FUNCTIONS">Functions</a></h2>
 977 <h3 class="function"><a id="cupsAddDest">cupsAddDest</a></h3>
 978         <p class="description">Add a destination to the list of destinations.</p>
 979 <p class="code">
 980 int cupsAddDest (<br />
 981 &#160;&#160;&#160;&#160;const char *name,<br />
 982 &#160;&#160;&#160;&#160;const char *instance,<br />
 983 &#160;&#160;&#160;&#160;int num_dests,<br />
 984 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> **dests<br />
 985 );</p>
 986 <h4 class="parameters">Parameters</h4>
 987 <dl>
 988 <dt>name</dt>
 989         <dd class="description">Destination name</dd>
 990 <dt>instance</dt>
 991         <dd class="description">Instance name or <code>NULL</code> for none/primary</dd>
 992 <dt>num_dests</dt>
 993         <dd class="description">Number of destinations</dd>
 994 <dt>dests</dt>
 995         <dd class="description">Destinations</dd>
 996 </dl>
 997 <h4 class="returnvalue">Return Value</h4>
 998         <p class="description">New number of destinations</p>
 999 <h4 class="discussion">Discussion</h4>
1000         <p class="discussion">This function cannot be used to add a new class or printer queue,
1001 it only adds a new container of saved options for the named
1002 destination or instance.<br>
1003 <br>
1004 If the named destination already exists, the destination list is
1005 returned unchanged.  Adding a new instance of a destination creates
1006 a copy of that destination's options.<br>
1007 <br>
1008 Use the <a href="#cupsSaveDests"><code>cupsSaveDests</code></a> function to save the updated list of
1009 destinations to the user's lpoptions file.</p>
1010 <h3 class="function"><a id="cupsAddOption">cupsAddOption</a></h3>
1011         <p class="description">Add an option to an option array.</p>
1012 <p class="code">
1013 int cupsAddOption (<br />
1014 &#160;&#160;&#160;&#160;const char *name,<br />
1015 &#160;&#160;&#160;&#160;const char *value,<br />
1016 &#160;&#160;&#160;&#160;int num_options,<br />
1017 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> **options<br />
1018 );</p>
1019 <h4 class="parameters">Parameters</h4>
1020 <dl>
1021 <dt>name</dt>
1022         <dd class="description">Name of option</dd>
1023 <dt>value</dt>
1024         <dd class="description">Value of option</dd>
1025 <dt>num_options</dt>
1026         <dd class="description">Number of options</dd>
1027 <dt>options</dt>
1028         <dd class="description">Pointer to options</dd>
1029 </dl>
1030 <h4 class="returnvalue">Return Value</h4>
1031         <p class="description">Number of options</p>
1032 <h4 class="discussion">Discussion</h4>
1033         <p class="discussion">New option arrays can be initialized simply by passing 0 for the
1034 &quot;num_options&quot; parameter.</p>
1035 <h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3>
1036         <p class="description">Create the Windows PPD file for a printer.</p>
1037 <p class="code">
1038 char *cupsAdminCreateWindowsPPD (<br />
1039 &#160;&#160;&#160;&#160;http_t *http,<br />
1040 &#160;&#160;&#160;&#160;const char *dest,<br />
1041 &#160;&#160;&#160;&#160;char *buffer,<br />
1042 &#160;&#160;&#160;&#160;int bufsize<br />
1043 );</p>
1044 <h4 class="parameters">Parameters</h4>
1045 <dl>
1046 <dt>http</dt>
1047         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1048 <dt>dest</dt>
1049         <dd class="description">Printer or class</dd>
1050 <dt>buffer</dt>
1051         <dd class="description">Filename buffer</dd>
1052 <dt>bufsize</dt>
1053         <dd class="description">Size of filename buffer</dd>
1054 </dl>
1055 <h4 class="returnvalue">Return Value</h4>
1056         <p class="description">PPD file or NULL</p>
1057 <h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsAdminExportSamba">cupsAdminExportSamba</a></h3>
1058         <p class="description">Export a printer to Samba.</p>
1059 <p class="code">
1060 int cupsAdminExportSamba (<br />
1061 &#160;&#160;&#160;&#160;const char *dest,<br />
1062 &#160;&#160;&#160;&#160;const char *ppd,<br />
1063 &#160;&#160;&#160;&#160;const char *samba_server,<br />
1064 &#160;&#160;&#160;&#160;const char *samba_user,<br />
1065 &#160;&#160;&#160;&#160;const char *samba_password,<br />
1066 &#160;&#160;&#160;&#160;FILE *logfile<br />
1067 );</p>
1068 <h4 class="parameters">Parameters</h4>
1069 <dl>
1070 <dt>dest</dt>
1071         <dd class="description">Destination to export</dd>
1072 <dt>ppd</dt>
1073         <dd class="description">PPD file</dd>
1074 <dt>samba_server</dt>
1075         <dd class="description">Samba server</dd>
1076 <dt>samba_user</dt>
1077         <dd class="description">Samba username</dd>
1078 <dt>samba_password</dt>
1079         <dd class="description">Samba password</dd>
1080 <dt>logfile</dt>
1081         <dd class="description">Log file, if any</dd>
1082 </dl>
1083 <h4 class="returnvalue">Return Value</h4>
1084         <p class="description">1 on success, 0 on failure</p>
1085 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3>
1086         <p class="description">Get settings from the server.</p>
1087 <p class="code">
1088 int cupsAdminGetServerSettings (<br />
1089 &#160;&#160;&#160;&#160;http_t *http,<br />
1090 &#160;&#160;&#160;&#160;int *num_settings,<br />
1091 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> **settings<br />
1092 );</p>
1093 <h4 class="parameters">Parameters</h4>
1094 <dl>
1095 <dt>http</dt>
1096         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1097 <dt>num_settings</dt>
1098         <dd class="description">Number of settings</dd>
1099 <dt>settings</dt>
1100         <dd class="description">Settings</dd>
1101 </dl>
1102 <h4 class="returnvalue">Return Value</h4>
1103         <p class="description">1 on success, 0 on failure</p>
1104 <h4 class="discussion">Discussion</h4>
1105         <p class="discussion">The returned settings should be freed with cupsFreeOptions() when
1106 you are done with them.
1107
1108 </p>
1109 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3>
1110         <p class="description">Set settings on the server.</p>
1111 <p class="code">
1112 int cupsAdminSetServerSettings (<br />
1113 &#160;&#160;&#160;&#160;http_t *http,<br />
1114 &#160;&#160;&#160;&#160;int num_settings,<br />
1115 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *settings<br />
1116 );</p>
1117 <h4 class="parameters">Parameters</h4>
1118 <dl>
1119 <dt>http</dt>
1120         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1121 <dt>num_settings</dt>
1122         <dd class="description">Number of settings</dd>
1123 <dt>settings</dt>
1124         <dd class="description">Settings</dd>
1125 </dl>
1126 <h4 class="returnvalue">Return Value</h4>
1127         <p class="description">1 on success, 0 on failure</p>
1128 <h3 class="function"><a id="cupsCancelDestJob">cupsCancelDestJob</a></h3>
1129         <p class="description">Include necessary headers...</p>
1130 <p class="code">
1131 ipp_status_t cupsCancelDestJob (<br />
1132 &#160;&#160;&#160;&#160;http_t *http,<br />
1133 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1134 &#160;&#160;&#160;&#160;int job_id<br />
1135 );</p>
1136 <h4 class="parameters">Parameters</h4>
1137 <dl>
1138 <dt>http</dt>
1139         <dd class="description">Connection to destination</dd>
1140 <dt>dest</dt>
1141         <dd class="description">Destination</dd>
1142 <dt>job_id</dt>
1143         <dd class="description">Job ID</dd>
1144 </dl>
1145 <h4 class="returnvalue">Return Value</h4>
1146         <p class="description">Cancel a job on a destination.</p>
1147         <p class="discussion">The &quot;job_id&quot; is the number returned by cupsCreateDestJob.<br>
1148 <br>
1149 Returns <code>IPP_STATUS_OK</code> on success and
1150 <code>IPP_STATUS_ERRPR_NOT_AUTHORIZED</code> or
1151 <code>IPP_STATUS_ERROR_FORBIDDEN</code> on failure.
1152
1153 </p>
1154 <h3 class="function"><a id="cupsCancelJob">cupsCancelJob</a></h3>
1155         <p class="description">Cancel a print job on the default server.</p>
1156 <p class="code">
1157 int cupsCancelJob (<br />
1158 &#160;&#160;&#160;&#160;const char *name,<br />
1159 &#160;&#160;&#160;&#160;int job_id<br />
1160 );</p>
1161 <h4 class="parameters">Parameters</h4>
1162 <dl>
1163 <dt>name</dt>
1164         <dd class="description">Name of printer or class</dd>
1165 <dt>job_id</dt>
1166         <dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd>
1167 </dl>
1168 <h4 class="returnvalue">Return Value</h4>
1169         <p class="description">1 on success, 0 on failure</p>
1170 <h4 class="discussion">Discussion</h4>
1171         <p class="discussion">Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code>
1172 to cancel the current job on the named destination.<br>
1173 <br>
1174 Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get
1175 the cause of any failure.</p>
1176 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsCancelJob2">cupsCancelJob2</a></h3>
1177         <p class="description">Cancel or purge a print job.</p>
1178 <p class="code">
1179 ipp_status_t cupsCancelJob2 (<br />
1180 &#160;&#160;&#160;&#160;http_t *http,<br />
1181 &#160;&#160;&#160;&#160;const char *name,<br />
1182 &#160;&#160;&#160;&#160;int job_id,<br />
1183 &#160;&#160;&#160;&#160;int purge<br />
1184 );</p>
1185 <h4 class="parameters">Parameters</h4>
1186 <dl>
1187 <dt>http</dt>
1188         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1189 <dt>name</dt>
1190         <dd class="description">Name of printer or class</dd>
1191 <dt>job_id</dt>
1192         <dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd>
1193 <dt>purge</dt>
1194         <dd class="description">1 to purge, 0 to cancel</dd>
1195 </dl>
1196 <h4 class="returnvalue">Return Value</h4>
1197         <p class="description">IPP status</p>
1198 <h4 class="discussion">Discussion</h4>
1199         <p class="discussion">Canceled jobs remain in the job history while purged jobs are removed
1200 from the job history.<br>
1201 <br>
1202 Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code>
1203 to cancel the current job on the named destination.<br>
1204 <br>
1205 Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get
1206 the cause of any failure.
1207
1208 </p>
1209 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCheckDestSupported">cupsCheckDestSupported</a></h3>
1210         <p class="description">Check that the option and value are supported
1211 by the destination.</p>
1212 <p class="code">
1213 int cupsCheckDestSupported (<br />
1214 &#160;&#160;&#160;&#160;http_t *http,<br />
1215 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1216 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
1217 &#160;&#160;&#160;&#160;const char *option,<br />
1218 &#160;&#160;&#160;&#160;const char *value<br />
1219 );</p>
1220 <h4 class="parameters">Parameters</h4>
1221 <dl>
1222 <dt>http</dt>
1223         <dd class="description">Connection to destination</dd>
1224 <dt>dest</dt>
1225         <dd class="description">Destination</dd>
1226 <dt>dinfo</dt>
1227         <dd class="description">Destination information</dd>
1228 <dt>option</dt>
1229         <dd class="description">Option</dd>
1230 <dt>value</dt>
1231         <dd class="description">Value</dd>
1232 </dl>
1233 <h4 class="returnvalue">Return Value</h4>
1234         <p class="description">1 if supported, 0 otherwise</p>
1235 <h4 class="discussion">Discussion</h4>
1236         <p class="discussion">Returns 1 if supported, 0 otherwise.
1237
1238 </p>
1239 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCloseDestJob">cupsCloseDestJob</a></h3>
1240         <p class="description">Close a job and start printing.</p>
1241 <p class="code">
1242 ipp_status_t cupsCloseDestJob (<br />
1243 &#160;&#160;&#160;&#160;http_t *http,<br />
1244 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1245 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br />
1246 &#160;&#160;&#160;&#160;int job_id<br />
1247 );</p>
1248 <h4 class="parameters">Parameters</h4>
1249 <dl>
1250 <dt>http</dt>
1251         <dd class="description">Connection to destination</dd>
1252 <dt>dest</dt>
1253         <dd class="description">Destination</dd>
1254 <dt>info</dt>
1255         <dd class="description">Destination information</dd>
1256 <dt>job_id</dt>
1257         <dd class="description">Job ID</dd>
1258 </dl>
1259 <h4 class="returnvalue">Return Value</h4>
1260         <p class="description">IPP status code</p>
1261 <h4 class="discussion">Discussion</h4>
1262         <p class="discussion">Use when the last call to cupsStartDocument passed 0 for &quot;last_document&quot;.
1263 &quot;job_id&quot; is the job ID returned by cupsCreateDestJob. Returns <code>IPP_STATUS_OK</code>
1264 on success.
1265
1266 </p>
1267 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsConnectDest">cupsConnectDest</a></h3>
1268         <p class="description">Connect to the server for a destination.</p>
1269 <p class="code">
1270 http_t *cupsConnectDest (<br />
1271 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1272 &#160;&#160;&#160;&#160;unsigned flags,<br />
1273 &#160;&#160;&#160;&#160;int msec,<br />
1274 &#160;&#160;&#160;&#160;int *cancel,<br />
1275 &#160;&#160;&#160;&#160;char *resource,<br />
1276 &#160;&#160;&#160;&#160;size_t resourcesize,<br />
1277 &#160;&#160;&#160;&#160;<a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br />
1278 &#160;&#160;&#160;&#160;void *user_data<br />
1279 );</p>
1280 <h4 class="parameters">Parameters</h4>
1281 <dl>
1282 <dt>dest</dt>
1283         <dd class="description">Destination</dd>
1284 <dt>flags</dt>
1285         <dd class="description">Connection flags</dd>
1286 <dt>msec</dt>
1287         <dd class="description">Timeout in milliseconds</dd>
1288 <dt>cancel</dt>
1289         <dd class="description">Pointer to &quot;cancel&quot; variable</dd>
1290 <dt>resource</dt>
1291         <dd class="description">Resource buffer</dd>
1292 <dt>resourcesize</dt>
1293         <dd class="description">Size of resource buffer</dd>
1294 <dt>cb</dt>
1295         <dd class="description">Callback function</dd>
1296 <dt>user_data</dt>
1297         <dd class="description">User data pointer</dd>
1298 </dl>
1299 <h4 class="returnvalue">Return Value</h4>
1300         <p class="description">Connection to server or <code>NULL</code></p>
1301 <h4 class="discussion">Discussion</h4>
1302         <p class="discussion">Connect to the destination, returning a new http_t connection object and
1303 optionally the resource path to use for the destination.  These calls will
1304 block until a connection is made, the timeout expires, the integer pointed
1305 to by &quot;cancel&quot; is non-zero, or the callback function (or block) returns 0,
1306 The caller is responsible for calling httpClose() on the returned object.
1307
1308 </p>
1309 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsConnectDestBlock">cupsConnectDestBlock</a></h3>
1310         <p class="description">Connect to the server for a destination.</p>
1311 <p class="code">
1312 http_t *cupsConnectDestBlock (<br />
1313 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1314 &#160;&#160;&#160;&#160;unsigned flags,<br />
1315 &#160;&#160;&#160;&#160;int msec,<br />
1316 &#160;&#160;&#160;&#160;int *cancel,<br />
1317 &#160;&#160;&#160;&#160;char *resource,<br />
1318 &#160;&#160;&#160;&#160;size_t resourcesize,<br />
1319 &#160;&#160;&#160;&#160;<a href="#cups_dest_block_t">cups_dest_block_t</a> block<br />
1320 );</p>
1321 <h4 class="parameters">Parameters</h4>
1322 <dl>
1323 <dt>dest</dt>
1324         <dd class="description">Destination</dd>
1325 <dt>flags</dt>
1326         <dd class="description">Connection flags</dd>
1327 <dt>msec</dt>
1328         <dd class="description">Timeout in milliseconds</dd>
1329 <dt>cancel</dt>
1330         <dd class="description">Pointer to &quot;cancel&quot; variable</dd>
1331 <dt>resource</dt>
1332         <dd class="description">Resource buffer</dd>
1333 <dt>resourcesize</dt>
1334         <dd class="description">Size of resource buffer</dd>
1335 <dt>block</dt>
1336         <dd class="description">Callback block</dd>
1337 </dl>
1338 <h4 class="returnvalue">Return Value</h4>
1339         <p class="description">Connection to server or <code>NULL</code></p>
1340 <h4 class="discussion">Discussion</h4>
1341         <p class="discussion">Connect to the destination, returning a new http_t connection object and
1342 optionally the resource path to use for the destination.  These calls will
1343 block until a connection is made, the timeout expires, the integer pointed
1344 to by &quot;cancel&quot; is non-zero, or the callback function (or block) returns 0,
1345 The caller is responsible for calling httpClose() on the returned object.
1346
1347 </p>
1348 <h3 class="function"><a id="cupsCopyDest">cupsCopyDest</a></h3>
1349         <p class="description">Callback block</p>
1350 <p class="code">
1351 int cupsCopyDest (<br />
1352 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1353 &#160;&#160;&#160;&#160;int num_dests,<br />
1354 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> **dests<br />
1355 );</p>
1356 <h4 class="parameters">Parameters</h4>
1357 <dl>
1358 <dt>dest</dt>
1359 <dt>num_dests</dt>
1360 <dt>dests</dt>
1361 </dl>
1362 <h4 class="returnvalue">Return Value</h4>
1363         <p class="description">Copy a destination.</p>
1364         <p class="discussion">Make a copy of the destination to an array of destinations (or just a single
1365 copy) - for use with the cupsEnumDests* functions. The caller is responsible
1366 for calling cupsFreeDests() on the returned object(s).
1367
1368 </p>
1369 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCopyDestConflicts">cupsCopyDestConflicts</a></h3>
1370         <p class="description">Get conflicts and resolutions for a new
1371 option/value pair.</p>
1372 <p class="code">
1373 int cupsCopyDestConflicts (<br />
1374 &#160;&#160;&#160;&#160;http_t *http,<br />
1375 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1376 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
1377 &#160;&#160;&#160;&#160;int num_options,<br />
1378 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options,<br />
1379 &#160;&#160;&#160;&#160;const char *new_option,<br />
1380 &#160;&#160;&#160;&#160;const char *new_value,<br />
1381 &#160;&#160;&#160;&#160;int *num_conflicts,<br />
1382 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> **conflicts,<br />
1383 &#160;&#160;&#160;&#160;int *num_resolved,<br />
1384 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> **resolved<br />
1385 );</p>
1386 <h4 class="parameters">Parameters</h4>
1387 <dl>
1388 <dt>http</dt>
1389         <dd class="description">Connection to destination</dd>
1390 <dt>dest</dt>
1391         <dd class="description">Destination</dd>
1392 <dt>dinfo</dt>
1393         <dd class="description">Destination information</dd>
1394 <dt>num_options</dt>
1395         <dd class="description">Number of current options</dd>
1396 <dt>options</dt>
1397         <dd class="description">Current options</dd>
1398 <dt>new_option</dt>
1399         <dd class="description">New option</dd>
1400 <dt>new_value</dt>
1401         <dd class="description">New value</dd>
1402 <dt>num_conflicts</dt>
1403         <dd class="description">Number of conflicting options</dd>
1404 <dt>conflicts</dt>
1405         <dd class="description">Conflicting options</dd>
1406 <dt>num_resolved</dt>
1407         <dd class="description">Number of options to resolve</dd>
1408 <dt>resolved</dt>
1409         <dd class="description">Resolved options</dd>
1410 </dl>
1411 <h4 class="returnvalue">Return Value</h4>
1412         <p class="description">1 if there is a conflict, 0 if none, -1 on error</p>
1413 <h4 class="discussion">Discussion</h4>
1414         <p class="discussion">&quot;num_options&quot; and &quot;options&quot; represent the currently selected options by the
1415 user.  &quot;new_option&quot; and &quot;new_value&quot; are the setting the user has just
1416 changed.<br>
1417 <br>
1418 Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if
1419 there was an unrecoverable error such as a resolver loop.<br>
1420 <br>
1421 If &quot;num_conflicts&quot; and &quot;conflicts&quot; are not <code>NULL</code>, they are set to
1422 contain the list of conflicting option/value pairs.  Similarly, if
1423 &quot;num_resolved&quot; and &quot;resolved&quot; are not <code>NULL</code> they will be set to the
1424 list of changes needed to resolve the conflict.<br>
1425 <br>
1426 If cupsCopyDestConflicts returns 1 but &quot;num_resolved&quot; and &quot;resolved&quot; are set
1427 to 0 and <code>NULL</code>, respectively, then the conflict cannot be resolved.
1428
1429 </p>
1430 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCopyDestInfo">cupsCopyDestInfo</a></h3>
1431         <p class="description">Get the supported values/capabilities for the
1432 destination.</p>
1433 <p class="code">
1434 <a href="#cups_dinfo_t">cups_dinfo_t</a> *cupsCopyDestInfo (<br />
1435 &#160;&#160;&#160;&#160;http_t *http,<br />
1436 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest<br />
1437 );</p>
1438 <h4 class="parameters">Parameters</h4>
1439 <dl>
1440 <dt>http</dt>
1441         <dd class="description">Connection to destination</dd>
1442 <dt>dest</dt>
1443         <dd class="description">Destination</dd>
1444 </dl>
1445 <h4 class="returnvalue">Return Value</h4>
1446         <p class="description">Destination information</p>
1447 <h4 class="discussion">Discussion</h4>
1448         <p class="discussion">The caller is responsible for calling <a href="#cupsFreeDestInfo"><code>cupsFreeDestInfo</code></a> on the return
1449 value. <code>NULL</code> is returned on error.
1450
1451 </p>
1452 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCreateDestJob">cupsCreateDestJob</a></h3>
1453         <p class="description">Create a job on a destination.</p>
1454 <p class="code">
1455 ipp_status_t cupsCreateDestJob (<br />
1456 &#160;&#160;&#160;&#160;http_t *http,<br />
1457 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1458 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br />
1459 &#160;&#160;&#160;&#160;int *job_id,<br />
1460 &#160;&#160;&#160;&#160;const char *title,<br />
1461 &#160;&#160;&#160;&#160;int num_options,<br />
1462 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options<br />
1463 );</p>
1464 <h4 class="parameters">Parameters</h4>
1465 <dl>
1466 <dt>http</dt>
1467         <dd class="description">Connection to destination</dd>
1468 <dt>dest</dt>
1469         <dd class="description">Destination</dd>
1470 <dt>info</dt>
1471         <dd class="description">Destination information</dd>
1472 <dt>job_id</dt>
1473         <dd class="description">Job ID or 0 on error</dd>
1474 <dt>title</dt>
1475         <dd class="description">Job name</dd>
1476 <dt>num_options</dt>
1477         <dd class="description">Number of job options</dd>
1478 <dt>options</dt>
1479         <dd class="description">Job options</dd>
1480 </dl>
1481 <h4 class="returnvalue">Return Value</h4>
1482         <p class="description">IPP status code</p>
1483 <h4 class="discussion">Discussion</h4>
1484         <p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success, saving the job ID
1485 in the variable pointed to by &quot;job_id&quot;.
1486
1487 </p>
1488 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsCreateJob">cupsCreateJob</a></h3>
1489         <p class="description">Create an empty job for streaming.</p>
1490 <p class="code">
1491 int cupsCreateJob (<br />
1492 &#160;&#160;&#160;&#160;http_t *http,<br />
1493 &#160;&#160;&#160;&#160;const char *name,<br />
1494 &#160;&#160;&#160;&#160;const char *title,<br />
1495 &#160;&#160;&#160;&#160;int num_options,<br />
1496 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options<br />
1497 );</p>
1498 <h4 class="parameters">Parameters</h4>
1499 <dl>
1500 <dt>http</dt>
1501         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1502 <dt>name</dt>
1503         <dd class="description">Destination name</dd>
1504 <dt>title</dt>
1505         <dd class="description">Title of job</dd>
1506 <dt>num_options</dt>
1507         <dd class="description">Number of options</dd>
1508 <dt>options</dt>
1509         <dd class="description">Options</dd>
1510 </dl>
1511 <h4 class="returnvalue">Return Value</h4>
1512         <p class="description">Job ID or 0 on error</p>
1513 <h4 class="discussion">Discussion</h4>
1514         <p class="discussion">Use this function when you want to stream print data using the
1515 <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>, <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a>, and
1516 <a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> functions.  If you have one or more files to
1517 print, use the <a href="#cupsPrintFile2"><code>cupsPrintFile2</code></a> or <a href="#cupsPrintFiles2"><code>cupsPrintFiles2</code></a> function
1518 instead.
1519
1520 </p>
1521 <h3 class="function"><a id="cupsEncryption">cupsEncryption</a></h3>
1522         <p class="description">Get the current encryption settings.</p>
1523 <p class="code">
1524 http_encryption_t cupsEncryption (void);</p>
1525 <h4 class="returnvalue">Return Value</h4>
1526         <p class="description">Encryption settings</p>
1527 <h4 class="discussion">Discussion</h4>
1528         <p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
1529 environment variable, then the ~/.cups/client.conf file, and finally the
1530 /etc/cups/client.conf file. If not set, the default is
1531 <code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br>
1532 <br>
1533 Note: The current encryption setting is tracked separately for each thread
1534 in a program. Multi-threaded programs that override the setting via the
1535 <a href="#cupsSetEncryption"><code>cupsSetEncryption</code></a> function need to do so in each thread for the same
1536 setting to be used.</p>
1537 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsEnumDests">cupsEnumDests</a></h3>
1538         <p class="description">Enumerate available destinations with a callback function.</p>
1539 <p class="code">
1540 int cupsEnumDests (<br />
1541 &#160;&#160;&#160;&#160;unsigned flags,<br />
1542 &#160;&#160;&#160;&#160;int msec,<br />
1543 &#160;&#160;&#160;&#160;int *cancel,<br />
1544 &#160;&#160;&#160;&#160;<a href="#cups_ptype_t">cups_ptype_t</a> type,<br />
1545 &#160;&#160;&#160;&#160;<a href="#cups_ptype_t">cups_ptype_t</a> mask,<br />
1546 &#160;&#160;&#160;&#160;<a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br />
1547 &#160;&#160;&#160;&#160;void *user_data<br />
1548 );</p>
1549 <h4 class="parameters">Parameters</h4>
1550 <dl>
1551 <dt>flags</dt>
1552         <dd class="description">Enumeration flags</dd>
1553 <dt>msec</dt>
1554         <dd class="description">Timeout in milliseconds,
1555 -1 for indefinite</dd>
1556 <dt>cancel</dt>
1557         <dd class="description">Pointer to &quot;cancel&quot; variable</dd>
1558 <dt>type</dt>
1559         <dd class="description">Printer type bits</dd>
1560 <dt>mask</dt>
1561         <dd class="description">Mask for printer type bits</dd>
1562 <dt>cb</dt>
1563         <dd class="description">Callback function</dd>
1564 <dt>user_data</dt>
1565         <dd class="description">User data</dd>
1566 </dl>
1567 <h4 class="returnvalue">Return Value</h4>
1568         <p class="description">1 on success, 0 on failure</p>
1569 <h4 class="discussion">Discussion</h4>
1570         <p class="discussion">Destinations are enumerated from one or more sources. The callback function
1571 receives the <code>user_data</code> pointer, destination name, instance, number of
1572 options, and options which can be used as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a>
1573 function.  The function must return 1 to continue enumeration or 0 to stop.<br>
1574 <br>
1575 Enumeration happens on the current thread and does not return until all
1576 destinations have been enumerated or the callback function returns 0.
1577
1578 </p>
1579 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsEnumDestsBlock">cupsEnumDestsBlock</a></h3>
1580         <p class="description">Enumerate available destinations with a block.</p>
1581 <p class="code">
1582 int cupsEnumDestsBlock (<br />
1583 &#160;&#160;&#160;&#160;unsigned flags,<br />
1584 &#160;&#160;&#160;&#160;int timeout,<br />
1585 &#160;&#160;&#160;&#160;int *cancel,<br />
1586 &#160;&#160;&#160;&#160;<a href="#cups_ptype_t">cups_ptype_t</a> type,<br />
1587 &#160;&#160;&#160;&#160;<a href="#cups_ptype_t">cups_ptype_t</a> mask,<br />
1588 &#160;&#160;&#160;&#160;<a href="#cups_dest_block_t">cups_dest_block_t</a> block<br />
1589 );</p>
1590 <h4 class="parameters">Parameters</h4>
1591 <dl>
1592 <dt>flags</dt>
1593         <dd class="description">Enumeration flags</dd>
1594 <dt>timeout</dt>
1595         <dd class="description">Timeout in milliseconds, 0 for indefinite</dd>
1596 <dt>cancel</dt>
1597         <dd class="description">Pointer to &quot;cancel&quot; variable</dd>
1598 <dt>type</dt>
1599         <dd class="description">Printer type bits</dd>
1600 <dt>mask</dt>
1601         <dd class="description">Mask for printer type bits</dd>
1602 <dt>block</dt>
1603         <dd class="description">Block</dd>
1604 </dl>
1605 <h4 class="returnvalue">Return Value</h4>
1606         <p class="description">1 on success, 0 on failure</p>
1607 <h4 class="discussion">Discussion</h4>
1608         <p class="discussion">Destinations are enumerated from one or more sources. The block receives the
1609 destination name, instance, number of options, and options which can be used
1610 as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> function.  The block must return 1 to
1611 continue enumeration or 0 to stop.<br>
1612 <br>
1613 Enumeration happens on the current thread and does not return until all
1614 destinations have been enumerated or the block returns 0.
1615
1616 </p>
1617 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsFindDestDefault">cupsFindDestDefault</a></h3>
1618         <p class="description">Find the default value(s) for the given option.</p>
1619 <p class="code">
1620 ipp_attribute_t *cupsFindDestDefault (<br />
1621 &#160;&#160;&#160;&#160;http_t *http,<br />
1622 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1623 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
1624 &#160;&#160;&#160;&#160;const char *option<br />
1625 );</p>
1626 <h4 class="parameters">Parameters</h4>
1627 <dl>
1628 <dt>http</dt>
1629         <dd class="description">Connection to destination</dd>
1630 <dt>dest</dt>
1631         <dd class="description">Destination</dd>
1632 <dt>dinfo</dt>
1633         <dd class="description">Destination information</dd>
1634 <dt>option</dt>
1635         <dd class="description">Option/attribute name</dd>
1636 </dl>
1637 <h4 class="returnvalue">Return Value</h4>
1638         <p class="description">Default attribute or <code>NULL</code> for none</p>
1639 <h4 class="discussion">Discussion</h4>
1640         <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
1641 <code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
1642 <code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
1643 <code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
1644 functions to inspect the default value(s) as needed.
1645
1646 </p>
1647 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsFindDestReady">cupsFindDestReady</a></h3>
1648         <p class="description">Find the default value(s) for the given option.</p>
1649 <p class="code">
1650 ipp_attribute_t *cupsFindDestReady (<br />
1651 &#160;&#160;&#160;&#160;http_t *http,<br />
1652 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1653 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
1654 &#160;&#160;&#160;&#160;const char *option<br />
1655 );</p>
1656 <h4 class="parameters">Parameters</h4>
1657 <dl>
1658 <dt>http</dt>
1659         <dd class="description">Connection to destination</dd>
1660 <dt>dest</dt>
1661         <dd class="description">Destination</dd>
1662 <dt>dinfo</dt>
1663         <dd class="description">Destination information</dd>
1664 <dt>option</dt>
1665         <dd class="description">Option/attribute name</dd>
1666 </dl>
1667 <h4 class="returnvalue">Return Value</h4>
1668         <p class="description">Default attribute or <code>NULL</code> for none</p>
1669 <h4 class="discussion">Discussion</h4>
1670         <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
1671 <code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
1672 <code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
1673 <code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
1674 functions to inspect the default value(s) as needed.
1675
1676 </p>
1677 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsFindDestSupported">cupsFindDestSupported</a></h3>
1678         <p class="description">Find the default value(s) for the given option.</p>
1679 <p class="code">
1680 ipp_attribute_t *cupsFindDestSupported (<br />
1681 &#160;&#160;&#160;&#160;http_t *http,<br />
1682 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1683 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
1684 &#160;&#160;&#160;&#160;const char *option<br />
1685 );</p>
1686 <h4 class="parameters">Parameters</h4>
1687 <dl>
1688 <dt>http</dt>
1689         <dd class="description">Connection to destination</dd>
1690 <dt>dest</dt>
1691         <dd class="description">Destination</dd>
1692 <dt>dinfo</dt>
1693         <dd class="description">Destination information</dd>
1694 <dt>option</dt>
1695         <dd class="description">Option/attribute name</dd>
1696 </dl>
1697 <h4 class="returnvalue">Return Value</h4>
1698         <p class="description">Default attribute or <code>NULL</code> for none</p>
1699 <h4 class="discussion">Discussion</h4>
1700         <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
1701 <code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
1702 <code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
1703 <code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
1704 functions to inspect the default value(s) as needed.
1705
1706 </p>
1707 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsFinishDestDocument">cupsFinishDestDocument</a></h3>
1708         <p class="description">Finish the current document.</p>
1709 <p class="code">
1710 ipp_status_t cupsFinishDestDocument (<br />
1711 &#160;&#160;&#160;&#160;http_t *http,<br />
1712 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1713 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *info<br />
1714 );</p>
1715 <h4 class="parameters">Parameters</h4>
1716 <dl>
1717 <dt>http</dt>
1718         <dd class="description">Connection to destination</dd>
1719 <dt>dest</dt>
1720         <dd class="description">Destination</dd>
1721 <dt>info</dt>
1722         <dd class="description">Destination information</dd>
1723 </dl>
1724 <h4 class="returnvalue">Return Value</h4>
1725         <p class="description">Status of document submission</p>
1726 <h4 class="discussion">Discussion</h4>
1727         <p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success.
1728
1729 </p>
1730 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsFinishDocument">cupsFinishDocument</a></h3>
1731         <p class="description">Finish sending a document.</p>
1732 <p class="code">
1733 ipp_status_t cupsFinishDocument (<br />
1734 &#160;&#160;&#160;&#160;http_t *http,<br />
1735 &#160;&#160;&#160;&#160;const char *name<br />
1736 );</p>
1737 <h4 class="parameters">Parameters</h4>
1738 <dl>
1739 <dt>http</dt>
1740         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1741 <dt>name</dt>
1742         <dd class="description">Destination name</dd>
1743 </dl>
1744 <h4 class="returnvalue">Return Value</h4>
1745         <p class="description">Status of document submission</p>
1746 <h4 class="discussion">Discussion</h4>
1747         <p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>.
1748
1749 </p>
1750 <h3 class="function"><a id="cupsFreeDestInfo">cupsFreeDestInfo</a></h3>
1751         <p class="description">Free destination information obtained using
1752 <a href="#cupsCopyDestInfo"><code>cupsCopyDestInfo</code></a>.</p>
1753 <p class="code">
1754 void cupsFreeDestInfo (<br />
1755 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo<br />
1756 );</p>
1757 <h4 class="parameters">Parameters</h4>
1758 <dl>
1759 <dt>dinfo</dt>
1760         <dd class="description">Destination information</dd>
1761 </dl>
1762 <h3 class="function"><a id="cupsFreeDests">cupsFreeDests</a></h3>
1763         <p class="description">Free the memory used by the list of destinations.</p>
1764 <p class="code">
1765 void cupsFreeDests (<br />
1766 &#160;&#160;&#160;&#160;int num_dests,<br />
1767 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dests<br />
1768 );</p>
1769 <h4 class="parameters">Parameters</h4>
1770 <dl>
1771 <dt>num_dests</dt>
1772         <dd class="description">Number of destinations</dd>
1773 <dt>dests</dt>
1774         <dd class="description">Destinations</dd>
1775 </dl>
1776 <h3 class="function"><a id="cupsFreeJobs">cupsFreeJobs</a></h3>
1777         <p class="description">Free memory used by job data.</p>
1778 <p class="code">
1779 void cupsFreeJobs (<br />
1780 &#160;&#160;&#160;&#160;int num_jobs,<br />
1781 &#160;&#160;&#160;&#160;<a href="#cups_job_t">cups_job_t</a> *jobs<br />
1782 );</p>
1783 <h4 class="parameters">Parameters</h4>
1784 <dl>
1785 <dt>num_jobs</dt>
1786         <dd class="description">Number of jobs</dd>
1787 <dt>jobs</dt>
1788         <dd class="description">Jobs</dd>
1789 </dl>
1790 <h3 class="function"><a id="cupsFreeOptions">cupsFreeOptions</a></h3>
1791         <p class="description">Free all memory used by options.</p>
1792 <p class="code">
1793 void cupsFreeOptions (<br />
1794 &#160;&#160;&#160;&#160;int num_options,<br />
1795 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options<br />
1796 );</p>
1797 <h4 class="parameters">Parameters</h4>
1798 <dl>
1799 <dt>num_options</dt>
1800         <dd class="description">Number of options</dd>
1801 <dt>options</dt>
1802         <dd class="description">Pointer to options</dd>
1803 </dl>
1804 <h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsGetClasses">cupsGetClasses</a></h3>
1805         <p class="description">Get a list of printer classes from the default server.</p>
1806 <p class="code">
1807 int cupsGetClasses (<br />
1808 &#160;&#160;&#160;&#160;char ***classes<br />
1809 );</p>
1810 <h4 class="parameters">Parameters</h4>
1811 <dl>
1812 <dt>classes</dt>
1813         <dd class="description">Classes</dd>
1814 </dl>
1815 <h4 class="returnvalue">Return Value</h4>
1816         <p class="description">Number of classes</p>
1817 <h4 class="discussion">Discussion</h4>
1818         <p class="discussion">This function is deprecated and no longer returns a list of printer
1819 classes - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
1820
1821 </p>
1822 <h3 class="function"><a id="cupsGetDefault">cupsGetDefault</a></h3>
1823         <p class="description">Get the default printer or class for the default server.</p>
1824 <p class="code">
1825 const char *cupsGetDefault (void);</p>
1826 <h4 class="returnvalue">Return Value</h4>
1827         <p class="description">Default printer or <code>NULL</code></p>
1828 <h4 class="discussion">Discussion</h4>
1829         <p class="discussion">This function returns the default printer or class as defined by
1830 the LPDEST or PRINTER environment variables. If these environment
1831 variables are not set, the server default destination is returned.
1832 Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a>
1833 functions to get the user-defined default printer, as this function does
1834 not support the lpoptions-defined default printer.</p>
1835 <h3 class="function"><span class="info">&#160;CUPS 1.1.21/macOS 10.4&#160;</span><a id="cupsGetDefault2">cupsGetDefault2</a></h3>
1836         <p class="description">Get the default printer or class for the specified server.</p>
1837 <p class="code">
1838 const char *cupsGetDefault2 (<br />
1839 &#160;&#160;&#160;&#160;http_t *http<br />
1840 );</p>
1841 <h4 class="parameters">Parameters</h4>
1842 <dl>
1843 <dt>http</dt>
1844         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1845 </dl>
1846 <h4 class="returnvalue">Return Value</h4>
1847         <p class="description">Default printer or <code>NULL</code></p>
1848 <h4 class="discussion">Discussion</h4>
1849         <p class="discussion">This function returns the default printer or class as defined by
1850 the LPDEST or PRINTER environment variables. If these environment
1851 variables are not set, the server default destination is returned.
1852 Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a>
1853 functions to get the user-defined default printer, as this function does
1854 not support the lpoptions-defined default printer.
1855
1856 </p>
1857 <h3 class="function"><a id="cupsGetDest">cupsGetDest</a></h3>
1858         <p class="description">Get the named destination from the list.</p>
1859 <p class="code">
1860 <a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest (<br />
1861 &#160;&#160;&#160;&#160;const char *name,<br />
1862 &#160;&#160;&#160;&#160;const char *instance,<br />
1863 &#160;&#160;&#160;&#160;int num_dests,<br />
1864 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dests<br />
1865 );</p>
1866 <h4 class="parameters">Parameters</h4>
1867 <dl>
1868 <dt>name</dt>
1869         <dd class="description">Destination name or <code>NULL</code> for the default destination</dd>
1870 <dt>instance</dt>
1871         <dd class="description">Instance name or <code>NULL</code></dd>
1872 <dt>num_dests</dt>
1873         <dd class="description">Number of destinations</dd>
1874 <dt>dests</dt>
1875         <dd class="description">Destinations</dd>
1876 </dl>
1877 <h4 class="returnvalue">Return Value</h4>
1878         <p class="description">Destination pointer or <code>NULL</code></p>
1879 <h4 class="discussion">Discussion</h4>
1880         <p class="discussion">Use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a
1881 list of supported destinations for the current user.</p>
1882 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></h3>
1883         <p class="description">Get a media name, dimension, and margins for a
1884 specific size.</p>
1885 <p class="code">
1886 int cupsGetDestMediaByIndex (<br />
1887 &#160;&#160;&#160;&#160;http_t *http,<br />
1888 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1889 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
1890 &#160;&#160;&#160;&#160;int n,<br />
1891 &#160;&#160;&#160;&#160;unsigned flags,<br />
1892 &#160;&#160;&#160;&#160;<a href="#cups_size_t">cups_size_t</a> *size<br />
1893 );</p>
1894 <h4 class="parameters">Parameters</h4>
1895 <dl>
1896 <dt>http</dt>
1897         <dd class="description">Connection to destination</dd>
1898 <dt>dest</dt>
1899         <dd class="description">Destination</dd>
1900 <dt>dinfo</dt>
1901         <dd class="description">Destination information</dd>
1902 <dt>n</dt>
1903         <dd class="description">Media size number (0-based)</dd>
1904 <dt>flags</dt>
1905         <dd class="description">Media flags</dd>
1906 <dt>size</dt>
1907         <dd class="description">Media size information</dd>
1908 </dl>
1909 <h4 class="returnvalue">Return Value</h4>
1910         <p class="description">1 on success, 0 on failure</p>
1911 <h4 class="discussion">Discussion</h4>
1912         <p class="discussion">The <code>flags</code> parameter determines which set of media are indexed.  For
1913 example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will get the Nth
1914 borderless size supported by the printer.
1915
1916 </p>
1917 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsGetDestMediaByName">cupsGetDestMediaByName</a></h3>
1918         <p class="description">Get media names, dimensions, and margins.</p>
1919 <p class="code">
1920 int cupsGetDestMediaByName (<br />
1921 &#160;&#160;&#160;&#160;http_t *http,<br />
1922 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1923 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
1924 &#160;&#160;&#160;&#160;const char *media,<br />
1925 &#160;&#160;&#160;&#160;unsigned flags,<br />
1926 &#160;&#160;&#160;&#160;<a href="#cups_size_t">cups_size_t</a> *size<br />
1927 );</p>
1928 <h4 class="parameters">Parameters</h4>
1929 <dl>
1930 <dt>http</dt>
1931         <dd class="description">Connection to destination</dd>
1932 <dt>dest</dt>
1933         <dd class="description">Destination</dd>
1934 <dt>dinfo</dt>
1935         <dd class="description">Destination information</dd>
1936 <dt>media</dt>
1937         <dd class="description">Media name</dd>
1938 <dt>flags</dt>
1939         <dd class="description">Media matching flags</dd>
1940 <dt>size</dt>
1941         <dd class="description">Media size information</dd>
1942 </dl>
1943 <h4 class="returnvalue">Return Value</h4>
1944         <p class="description">1 on match, 0 on failure</p>
1945 <h4 class="discussion">Discussion</h4>
1946         <p class="discussion">The &quot;media&quot; string is a PWG media name.  &quot;Flags&quot; provides some matching
1947 guidance (multiple flags can be combined):<br>
1948 <br>
1949 CUPS_MEDIA_FLAGS_DEFAULT    = find the closest size supported by the printer,
1950 CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
1951 CUPS_MEDIA_FLAGS_DUPLEX     = find a size compatible with 2-sided printing,
1952 CUPS_MEDIA_FLAGS_EXACT      = find an exact match for the size, and
1953 CUPS_MEDIA_FLAGS_READY      = if the printer supports media sensing, find the
1954 size amongst the &quot;ready&quot; media.<br>
1955 <br>
1956 The matching result (if any) is returned in the &quot;cups_size_t&quot; structure.<br>
1957 <br>
1958 Returns 1 when there is a match and 0 if there is not a match.
1959
1960 </p>
1961 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></h3>
1962         <p class="description">Get media names, dimensions, and margins.</p>
1963 <p class="code">
1964 int cupsGetDestMediaBySize (<br />
1965 &#160;&#160;&#160;&#160;http_t *http,<br />
1966 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
1967 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
1968 &#160;&#160;&#160;&#160;int width,<br />
1969 &#160;&#160;&#160;&#160;int length,<br />
1970 &#160;&#160;&#160;&#160;unsigned flags,<br />
1971 &#160;&#160;&#160;&#160;<a href="#cups_size_t">cups_size_t</a> *size<br />
1972 );</p>
1973 <h4 class="parameters">Parameters</h4>
1974 <dl>
1975 <dt>http</dt>
1976         <dd class="description">Connection to destination</dd>
1977 <dt>dest</dt>
1978         <dd class="description">Destination</dd>
1979 <dt>dinfo</dt>
1980         <dd class="description">Destination information</dd>
1981 <dt>width</dt>
1982         <dd class="description">Media width in hundredths of
1983 of millimeters</dd>
1984 <dt>length</dt>
1985         <dd class="description">Media length in hundredths of
1986 of millimeters</dd>
1987 <dt>flags</dt>
1988         <dd class="description">Media matching flags</dd>
1989 <dt>size</dt>
1990         <dd class="description">Media size information</dd>
1991 </dl>
1992 <h4 class="returnvalue">Return Value</h4>
1993         <p class="description">1 on match, 0 on failure</p>
1994 <h4 class="discussion">Discussion</h4>
1995         <p class="discussion">&quot;Width&quot; and &quot;length&quot; are the dimensions in hundredths of millimeters.
1996 &quot;Flags&quot; provides some matching guidance (multiple flags can be combined):<br>
1997 <br>
1998 CUPS_MEDIA_FLAGS_DEFAULT    = find the closest size supported by the printer,
1999 CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
2000 CUPS_MEDIA_FLAGS_DUPLEX     = find a size compatible with 2-sided printing,
2001 CUPS_MEDIA_FLAGS_EXACT      = find an exact match for the size, and
2002 CUPS_MEDIA_FLAGS_READY      = if the printer supports media sensing, find the
2003 size amongst the &quot;ready&quot; media.<br>
2004 <br>
2005 The matching result (if any) is returned in the &quot;cups_size_t&quot; structure.<br>
2006 <br>
2007 Returns 1 when there is a match and 0 if there is not a match.
2008
2009 </p>
2010 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsGetDestMediaCount">cupsGetDestMediaCount</a></h3>
2011         <p class="description">Get the number of sizes supported by a
2012 destination.</p>
2013 <p class="code">
2014 int cupsGetDestMediaCount (<br />
2015 &#160;&#160;&#160;&#160;http_t *http,<br />
2016 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
2017 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
2018 &#160;&#160;&#160;&#160;unsigned flags<br />
2019 );</p>
2020 <h4 class="parameters">Parameters</h4>
2021 <dl>
2022 <dt>http</dt>
2023         <dd class="description">Connection to destination</dd>
2024 <dt>dest</dt>
2025         <dd class="description">Destination</dd>
2026 <dt>dinfo</dt>
2027         <dd class="description">Destination information</dd>
2028 <dt>flags</dt>
2029         <dd class="description">Media flags</dd>
2030 </dl>
2031 <h4 class="returnvalue">Return Value</h4>
2032         <p class="description">Number of sizes</p>
2033 <h4 class="discussion">Discussion</h4>
2034         <p class="discussion">The <code>flags</code> parameter determines the set of media sizes that are
2035 counted.  For example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return
2036 the number of borderless sizes.
2037
2038 </p>
2039 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></h3>
2040         <p class="description">Get the default size for a destination.</p>
2041 <p class="code">
2042 int cupsGetDestMediaDefault (<br />
2043 &#160;&#160;&#160;&#160;http_t *http,<br />
2044 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
2045 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
2046 &#160;&#160;&#160;&#160;unsigned flags,<br />
2047 &#160;&#160;&#160;&#160;<a href="#cups_size_t">cups_size_t</a> *size<br />
2048 );</p>
2049 <h4 class="parameters">Parameters</h4>
2050 <dl>
2051 <dt>http</dt>
2052         <dd class="description">Connection to destination</dd>
2053 <dt>dest</dt>
2054         <dd class="description">Destination</dd>
2055 <dt>dinfo</dt>
2056         <dd class="description">Destination information</dd>
2057 <dt>flags</dt>
2058         <dd class="description">Media flags</dd>
2059 <dt>size</dt>
2060         <dd class="description">Media size information</dd>
2061 </dl>
2062 <h4 class="returnvalue">Return Value</h4>
2063         <p class="description">1 on success, 0 on failure</p>
2064 <h4 class="discussion">Discussion</h4>
2065         <p class="discussion">The <code>flags</code> parameter determines which default size is returned.  For
2066 example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return the default
2067 borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
2068
2069 </p>
2070 <h3 class="function"><span class="info">&#160;CUPS 2.0/macOS 10.10&#160;</span><a id="cupsGetDestWithURI">cupsGetDestWithURI</a></h3>
2071         <p class="description">Get a destination associated with a URI.</p>
2072 <p class="code">
2073 <a href="#cups_dest_t">cups_dest_t</a> *cupsGetDestWithURI (<br />
2074 &#160;&#160;&#160;&#160;const char *name,<br />
2075 &#160;&#160;&#160;&#160;const char *uri<br />
2076 );</p>
2077 <h4 class="parameters">Parameters</h4>
2078 <dl>
2079 <dt>name</dt>
2080         <dd class="description">Desired printer name or <code>NULL</code></dd>
2081 <dt>uri</dt>
2082         <dd class="description">URI for the printer</dd>
2083 </dl>
2084 <h4 class="returnvalue">Return Value</h4>
2085         <p class="description">Destination or <code>NULL</code></p>
2086 <h4 class="discussion">Discussion</h4>
2087         <p class="discussion">&quot;name&quot; is the desired name for the printer. If <code>NULL</code>, a name will be
2088 created using the URI.<br>
2089 <br>
2090 &quot;uri&quot; is the &quot;ipp&quot; or &quot;ipps&quot; URI for the printer.
2091
2092 </p>
2093 <h3 class="function"><a id="cupsGetDests">cupsGetDests</a></h3>
2094         <p class="description">Get the list of destinations from the default server.</p>
2095 <p class="code">
2096 int cupsGetDests (<br />
2097 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> **dests<br />
2098 );</p>
2099 <h4 class="parameters">Parameters</h4>
2100 <dl>
2101 <dt>dests</dt>
2102         <dd class="description">Destinations</dd>
2103 </dl>
2104 <h4 class="returnvalue">Return Value</h4>
2105         <p class="description">Number of destinations</p>
2106 <h4 class="discussion">Discussion</h4>
2107         <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
2108 printer-info, printer-is-accepting-jobs, printer-is-shared,
2109 printer-make-and-model, printer-state, printer-state-change-time,
2110 printer-state-reasons, and printer-type attributes as options.  CUPS 1.4
2111 adds the marker-change-time, marker-colors, marker-high-levels,
2112 marker-levels, marker-low-levels, marker-message, marker-names,
2113 marker-types, and printer-commands attributes as well.<br>
2114 <br>
2115 Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
2116 the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.</p>
2117 <h3 class="function"><span class="info">&#160;CUPS 1.1.21/macOS 10.4&#160;</span><a id="cupsGetDests2">cupsGetDests2</a></h3>
2118         <p class="description">Get the list of destinations from the specified server.</p>
2119 <p class="code">
2120 int cupsGetDests2 (<br />
2121 &#160;&#160;&#160;&#160;http_t *http,<br />
2122 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> **dests<br />
2123 );</p>
2124 <h4 class="parameters">Parameters</h4>
2125 <dl>
2126 <dt>http</dt>
2127         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
2128 <dt>dests</dt>
2129         <dd class="description">Destinations</dd>
2130 </dl>
2131 <h4 class="returnvalue">Return Value</h4>
2132         <p class="description">Number of destinations</p>
2133 <h4 class="discussion">Discussion</h4>
2134         <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
2135 printer-info, printer-is-accepting-jobs, printer-is-shared,
2136 printer-make-and-model, printer-state, printer-state-change-time,
2137 printer-state-reasons, and printer-type attributes as options.  CUPS 1.4
2138 adds the marker-change-time, marker-colors, marker-high-levels,
2139 marker-levels, marker-low-levels, marker-message, marker-names,
2140 marker-types, and printer-commands attributes as well.<br>
2141 <br>
2142 Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
2143 the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.
2144
2145 </p>
2146 <h3 class="function"><a id="cupsGetJobs">cupsGetJobs</a></h3>
2147         <p class="description">Get the jobs from the default server.</p>
2148 <p class="code">
2149 int cupsGetJobs (<br />
2150 &#160;&#160;&#160;&#160;<a href="#cups_job_t">cups_job_t</a> **jobs,<br />
2151 &#160;&#160;&#160;&#160;const char *name,<br />
2152 &#160;&#160;&#160;&#160;int myjobs,<br />
2153 &#160;&#160;&#160;&#160;int whichjobs<br />
2154 );</p>
2155 <h4 class="parameters">Parameters</h4>
2156 <dl>
2157 <dt>jobs</dt>
2158         <dd class="description">Job data</dd>
2159 <dt>name</dt>
2160         <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd>
2161 <dt>myjobs</dt>
2162         <dd class="description">0 = all users, 1 = mine</dd>
2163 <dt>whichjobs</dt>
2164         <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd>
2165 </dl>
2166 <h4 class="returnvalue">Return Value</h4>
2167         <p class="description">Number of jobs</p>
2168 <h4 class="discussion">Discussion</h4>
2169         <p class="discussion">A &quot;whichjobs&quot; value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
2170 of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
2171 pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
2172 jobs that are stopped, canceled, aborted, or completed.</p>
2173 <h3 class="function"><span class="info">&#160;CUPS 1.1.21/macOS 10.4&#160;</span><a id="cupsGetJobs2">cupsGetJobs2</a></h3>
2174         <p class="description">Get the jobs from the specified server.</p>
2175 <p class="code">
2176 int cupsGetJobs2 (<br />
2177 &#160;&#160;&#160;&#160;http_t *http,<br />
2178 &#160;&#160;&#160;&#160;<a href="#cups_job_t">cups_job_t</a> **jobs,<br />
2179 &#160;&#160;&#160;&#160;const char *name,<br />
2180 &#160;&#160;&#160;&#160;int myjobs,<br />
2181 &#160;&#160;&#160;&#160;int whichjobs<br />
2182 );</p>
2183 <h4 class="parameters">Parameters</h4>
2184 <dl>
2185 <dt>http</dt>
2186         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
2187 <dt>jobs</dt>
2188         <dd class="description">Job data</dd>
2189 <dt>name</dt>
2190         <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd>
2191 <dt>myjobs</dt>
2192         <dd class="description">0 = all users, 1 = mine</dd>
2193 <dt>whichjobs</dt>
2194         <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd>
2195 </dl>
2196 <h4 class="returnvalue">Return Value</h4>
2197         <p class="description">Number of jobs</p>
2198 <h4 class="discussion">Discussion</h4>
2199         <p class="discussion">A &quot;whichjobs&quot; value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
2200 of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
2201 pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
2202 jobs that are stopped, canceled, aborted, or completed.
2203
2204 </p>
2205 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsGetNamedDest">cupsGetNamedDest</a></h3>
2206         <p class="description">Get options for the named destination.</p>
2207 <p class="code">
2208 <a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br />
2209 &#160;&#160;&#160;&#160;http_t *http,<br />
2210 &#160;&#160;&#160;&#160;const char *name,<br />
2211 &#160;&#160;&#160;&#160;const char *instance<br />
2212 );</p>
2213 <h4 class="parameters">Parameters</h4>
2214 <dl>
2215 <dt>http</dt>
2216         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
2217 <dt>name</dt>
2218         <dd class="description">Destination name or <code>NULL</code> for the default destination</dd>
2219 <dt>instance</dt>
2220         <dd class="description">Instance name or <code>NULL</code></dd>
2221 </dl>
2222 <h4 class="returnvalue">Return Value</h4>
2223         <p class="description">Destination or <code>NULL</code></p>
2224 <h4 class="discussion">Discussion</h4>
2225         <p class="discussion">This function is optimized for retrieving a single destination and should
2226 be used instead of <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you either
2227 know the name of the destination or want to print to the default destination.
2228 If <code>NULL</code> is returned, the destination does not exist or there is no
2229 default destination.<br>
2230 <br>
2231 If &quot;http&quot; is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print
2232 server will be used.<br>
2233 <br>
2234 If &quot;name&quot; is <code>NULL</code>, the default printer for the current user will be
2235 returned.<br>
2236 <br>
2237 The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a
2238 &quot;num_dests&quot; value of 1.
2239
2240 </p>
2241 <h3 class="function"><a id="cupsGetOption">cupsGetOption</a></h3>
2242         <p class="description">Get an option value.</p>
2243 <p class="code">
2244 const char *cupsGetOption (<br />
2245 &#160;&#160;&#160;&#160;const char *name,<br />
2246 &#160;&#160;&#160;&#160;int num_options,<br />
2247 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options<br />
2248 );</p>
2249 <h4 class="parameters">Parameters</h4>
2250 <dl>
2251 <dt>name</dt>
2252         <dd class="description">Name of option</dd>
2253 <dt>num_options</dt>
2254         <dd class="description">Number of options</dd>
2255 <dt>options</dt>
2256         <dd class="description">Options</dd>
2257 </dl>
2258 <h4 class="returnvalue">Return Value</h4>
2259         <p class="description">Option value or <code>NULL</code></p>
2260 <h3 class="function"><a id="cupsGetPassword">cupsGetPassword</a></h3>
2261         <p class="description">Get a password from the user.</p>
2262 <p class="code">
2263 const char *cupsGetPassword (<br />
2264 &#160;&#160;&#160;&#160;const char *prompt<br />
2265 );</p>
2266 <h4 class="parameters">Parameters</h4>
2267 <dl>
2268 <dt>prompt</dt>
2269         <dd class="description">Prompt string</dd>
2270 </dl>
2271 <h4 class="returnvalue">Return Value</h4>
2272         <p class="description">Password</p>
2273 <h4 class="discussion">Discussion</h4>
2274         <p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
2275 user does not provide a password.<br>
2276 <br>
2277 Note: The current password callback function is tracked separately for each
2278 thread in a program. Multi-threaded programs that override the setting via
2279 the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to
2280 do so in each thread for the same function to be used.</p>
2281 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsGetPassword2">cupsGetPassword2</a></h3>
2282         <p class="description">Get a password from the user using the advanced
2283 password callback.</p>
2284 <p class="code">
2285 const char *cupsGetPassword2 (<br />
2286 &#160;&#160;&#160;&#160;const char *prompt,<br />
2287 &#160;&#160;&#160;&#160;http_t *http,<br />
2288 &#160;&#160;&#160;&#160;const char *method,<br />
2289 &#160;&#160;&#160;&#160;const char *resource<br />
2290 );</p>
2291 <h4 class="parameters">Parameters</h4>
2292 <dl>
2293 <dt>prompt</dt>
2294         <dd class="description">Prompt string</dd>
2295 <dt>http</dt>
2296         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
2297 <dt>method</dt>
2298         <dd class="description">Request method (&quot;GET&quot;, &quot;POST&quot;, &quot;PUT&quot;)</dd>
2299 <dt>resource</dt>
2300         <dd class="description">Resource path</dd>
2301 </dl>
2302 <h4 class="returnvalue">Return Value</h4>
2303         <p class="description">Password</p>
2304 <h4 class="discussion">Discussion</h4>
2305         <p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
2306 user does not provide a password.<br>
2307 <br>
2308 Note: The current password callback function is tracked separately for each
2309 thread in a program. Multi-threaded programs that override the setting via
2310 the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to
2311 do so in each thread for the same function to be used.
2312
2313 </p>
2314 <h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsGetPrinters">cupsGetPrinters</a></h3>
2315         <p class="description">Get a list of printers from the default server.</p>
2316 <p class="code">
2317 int cupsGetPrinters (<br />
2318 &#160;&#160;&#160;&#160;char ***printers<br />
2319 );</p>
2320 <h4 class="parameters">Parameters</h4>
2321 <dl>
2322 <dt>printers</dt>
2323         <dd class="description">Printers</dd>
2324 </dl>
2325 <h4 class="returnvalue">Return Value</h4>
2326         <p class="description">Number of printers</p>
2327 <h4 class="discussion">Discussion</h4>
2328         <p class="discussion">This function is deprecated and no longer returns a list of printers - use
2329 <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead.
2330
2331 </p>
2332 <h3 class="function"><a id="cupsLangDefault">cupsLangDefault</a></h3>
2333         <p class="description">Return the default language.</p>
2334 <p class="code">
2335 cups_lang_t *cupsLangDefault (void);</p>
2336 <h4 class="returnvalue">Return Value</h4>
2337         <p class="description">Language data</p>
2338 <h3 class="function"><a id="cupsLangEncoding">cupsLangEncoding</a></h3>
2339         <p class="description">Return the character encoding (us-ascii, etc.)
2340 for the given language.</p>
2341 <p class="code">
2342 const char *cupsLangEncoding (<br />
2343 &#160;&#160;&#160;&#160;cups_lang_t *lang<br />
2344 );</p>
2345 <h4 class="parameters">Parameters</h4>
2346 <dl>
2347 <dt>lang</dt>
2348         <dd class="description">Language data</dd>
2349 </dl>
2350 <h4 class="returnvalue">Return Value</h4>
2351         <p class="description">Character encoding</p>
2352 <h3 class="function"><a id="cupsLangFlush">cupsLangFlush</a></h3>
2353         <p class="description">Flush all language data out of the cache.</p>
2354 <p class="code">
2355 void cupsLangFlush (void);</p>
2356 <h3 class="function"><a id="cupsLangFree">cupsLangFree</a></h3>
2357         <p class="description">Free language data.</p>
2358 <p class="code">
2359 void cupsLangFree (<br />
2360 &#160;&#160;&#160;&#160;cups_lang_t *lang<br />
2361 );</p>
2362 <h4 class="parameters">Parameters</h4>
2363 <dl>
2364 <dt>lang</dt>
2365         <dd class="description">Language to free</dd>
2366 </dl>
2367 <h4 class="discussion">Discussion</h4>
2368         <p class="discussion">This does not actually free anything; use <a href="#cupsLangFlush"><code>cupsLangFlush</code></a> for that.</p>
2369 <h3 class="function"><a id="cupsLangGet">cupsLangGet</a></h3>
2370         <p class="description">Get a language.</p>
2371 <p class="code">
2372 cups_lang_t *cupsLangGet (<br />
2373 &#160;&#160;&#160;&#160;const char *language<br />
2374 );</p>
2375 <h4 class="parameters">Parameters</h4>
2376 <dl>
2377 <dt>language</dt>
2378         <dd class="description">Language or locale</dd>
2379 </dl>
2380 <h4 class="returnvalue">Return Value</h4>
2381         <p class="description">Language data</p>
2382 <h3 class="function"><span class="info">&#160;CUPS 2.0/macOS 10.10&#160;</span><a id="cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></h3>
2383         <p class="description">Get the localized string for a destination media
2384 size.</p>
2385 <p class="code">
2386 const char *cupsLocalizeDestMedia (<br />
2387 &#160;&#160;&#160;&#160;http_t *http,<br />
2388 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
2389 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
2390 &#160;&#160;&#160;&#160;unsigned flags,<br />
2391 &#160;&#160;&#160;&#160;<a href="#cups_size_t">cups_size_t</a> *size<br />
2392 );</p>
2393 <h4 class="parameters">Parameters</h4>
2394 <dl>
2395 <dt>http</dt>
2396         <dd class="description">Connection to destination</dd>
2397 <dt>dest</dt>
2398         <dd class="description">Destination</dd>
2399 <dt>dinfo</dt>
2400         <dd class="description">Destination information</dd>
2401 <dt>flags</dt>
2402         <dd class="description">Media flags</dd>
2403 <dt>size</dt>
2404         <dd class="description">Media size</dd>
2405 </dl>
2406 <h4 class="returnvalue">Return Value</h4>
2407         <p class="description">Localized string</p>
2408 <h4 class="discussion">Discussion</h4>
2409         <p class="discussion">The returned string is stored in the destination information and will become
2410 invalid if the destination information is deleted.
2411
2412 </p>
2413 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsLocalizeDestOption">cupsLocalizeDestOption</a></h3>
2414         <p class="description">Get the localized string for a destination
2415 option.</p>
2416 <p class="code">
2417 const char *cupsLocalizeDestOption (<br />
2418 &#160;&#160;&#160;&#160;http_t *http,<br />
2419 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
2420 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
2421 &#160;&#160;&#160;&#160;const char *option<br />
2422 );</p>
2423 <h4 class="parameters">Parameters</h4>
2424 <dl>
2425 <dt>http</dt>
2426         <dd class="description">Connection to destination</dd>
2427 <dt>dest</dt>
2428         <dd class="description">Destination</dd>
2429 <dt>dinfo</dt>
2430         <dd class="description">Destination information</dd>
2431 <dt>option</dt>
2432         <dd class="description">Option to localize</dd>
2433 </dl>
2434 <h4 class="returnvalue">Return Value</h4>
2435         <p class="description">Localized string</p>
2436 <h4 class="discussion">Discussion</h4>
2437         <p class="discussion">The returned string is stored in the destination information and will become
2438 invalid if the destination information is deleted.
2439
2440 </p>
2441 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsLocalizeDestValue">cupsLocalizeDestValue</a></h3>
2442         <p class="description">Get the localized string for a destination
2443 option+value pair.</p>
2444 <p class="code">
2445 const char *cupsLocalizeDestValue (<br />
2446 &#160;&#160;&#160;&#160;http_t *http,<br />
2447 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
2448 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br />
2449 &#160;&#160;&#160;&#160;const char *option,<br />
2450 &#160;&#160;&#160;&#160;const char *value<br />
2451 );</p>
2452 <h4 class="parameters">Parameters</h4>
2453 <dl>
2454 <dt>http</dt>
2455         <dd class="description">Connection to destination</dd>
2456 <dt>dest</dt>
2457         <dd class="description">Destination</dd>
2458 <dt>dinfo</dt>
2459         <dd class="description">Destination information</dd>
2460 <dt>option</dt>
2461         <dd class="description">Option to localize</dd>
2462 <dt>value</dt>
2463         <dd class="description">Value to localize</dd>
2464 </dl>
2465 <h4 class="returnvalue">Return Value</h4>
2466         <p class="description">Localized string</p>
2467 <h4 class="discussion">Discussion</h4>
2468         <p class="discussion">The returned string is stored in the destination information and will become
2469 invalid if the destination information is deleted.
2470
2471 </p>
2472 <h3 class="function"><span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsNotifySubject">cupsNotifySubject</a></h3>
2473         <p class="description">Return the subject for the given notification message.</p>
2474 <p class="code">
2475 char *cupsNotifySubject (<br />
2476 &#160;&#160;&#160;&#160;cups_lang_t *lang,<br />
2477 &#160;&#160;&#160;&#160;ipp_t *event<br />
2478 );</p>
2479 <h4 class="parameters">Parameters</h4>
2480 <dl>
2481 <dt>lang</dt>
2482         <dd class="description">Language data</dd>
2483 <dt>event</dt>
2484         <dd class="description">Event data</dd>
2485 </dl>
2486 <h4 class="returnvalue">Return Value</h4>
2487         <p class="description">Subject string or <code>NULL</code></p>
2488 <h4 class="discussion">Discussion</h4>
2489         <p class="discussion">The returned string must be freed by the caller using <code>free</code>.
2490
2491 </p>
2492 <h3 class="function"><span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsNotifyText">cupsNotifyText</a></h3>
2493         <p class="description">Return the text for the given notification message.</p>
2494 <p class="code">
2495 char *cupsNotifyText (<br />
2496 &#160;&#160;&#160;&#160;cups_lang_t *lang,<br />
2497 &#160;&#160;&#160;&#160;ipp_t *event<br />
2498 );</p>
2499 <h4 class="parameters">Parameters</h4>
2500 <dl>
2501 <dt>lang</dt>
2502         <dd class="description">Language data</dd>
2503 <dt>event</dt>
2504         <dd class="description">Event data</dd>
2505 </dl>
2506 <h4 class="returnvalue">Return Value</h4>
2507         <p class="description">Message text or <code>NULL</code></p>
2508 <h4 class="discussion">Discussion</h4>
2509         <p class="discussion">The returned string must be freed by the caller using <code>free</code>.
2510
2511 </p>
2512 <h3 class="function"><a id="cupsParseOptions">cupsParseOptions</a></h3>
2513         <p class="description">Parse options from a command-line argument.</p>
2514 <p class="code">
2515 int cupsParseOptions (<br />
2516 &#160;&#160;&#160;&#160;const char *arg,<br />
2517 &#160;&#160;&#160;&#160;int num_options,<br />
2518 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> **options<br />
2519 );</p>
2520 <h4 class="parameters">Parameters</h4>
2521 <dl>
2522 <dt>arg</dt>
2523         <dd class="description">Argument to parse</dd>
2524 <dt>num_options</dt>
2525         <dd class="description">Number of options</dd>
2526 <dt>options</dt>
2527         <dd class="description">Options found</dd>
2528 </dl>
2529 <h4 class="returnvalue">Return Value</h4>
2530         <p class="description">Number of options found</p>
2531 <h4 class="discussion">Discussion</h4>
2532         <p class="discussion">This function converts space-delimited name/value pairs according
2533 to the PAPI text option ABNF specification. Collection values
2534 (&quot;name={a=... b=... c=...}&quot;) are stored with the curley brackets
2535 intact - use <code>cupsParseOptions</code> on the value to extract the
2536 collection attributes.</p>
2537 <h3 class="function"><a id="cupsPrintFile">cupsPrintFile</a></h3>
2538         <p class="description">Print a file to a printer or class on the default server.</p>
2539 <p class="code">
2540 int cupsPrintFile (<br />
2541 &#160;&#160;&#160;&#160;const char *name,<br />
2542 &#160;&#160;&#160;&#160;const char *filename,<br />
2543 &#160;&#160;&#160;&#160;const char *title,<br />
2544 &#160;&#160;&#160;&#160;int num_options,<br />
2545 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options<br />
2546 );</p>
2547 <h4 class="parameters">Parameters</h4>
2548 <dl>
2549 <dt>name</dt>
2550         <dd class="description">Destination name</dd>
2551 <dt>filename</dt>
2552         <dd class="description">File to print</dd>
2553 <dt>title</dt>
2554         <dd class="description">Title of job</dd>
2555 <dt>num_options</dt>
2556         <dd class="description">Number of options</dd>
2557 <dt>options</dt>
2558         <dd class="description">Options</dd>
2559 </dl>
2560 <h4 class="returnvalue">Return Value</h4>
2561         <p class="description">Job ID or 0 on error</p>
2562 <h3 class="function"><span class="info">&#160;CUPS 1.1.21/macOS 10.4&#160;</span><a id="cupsPrintFile2">cupsPrintFile2</a></h3>
2563         <p class="description">Print a file to a printer or class on the specified
2564 server.</p>
2565 <p class="code">
2566 int cupsPrintFile2 (<br />
2567 &#160;&#160;&#160;&#160;http_t *http,<br />
2568 &#160;&#160;&#160;&#160;const char *name,<br />
2569 &#160;&#160;&#160;&#160;const char *filename,<br />
2570 &#160;&#160;&#160;&#160;const char *title,<br />
2571 &#160;&#160;&#160;&#160;int num_options,<br />
2572 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options<br />
2573 );</p>
2574 <h4 class="parameters">Parameters</h4>
2575 <dl>
2576 <dt>http</dt>
2577         <dd class="description">Connection to server</dd>
2578 <dt>name</dt>
2579         <dd class="description">Destination name</dd>
2580 <dt>filename</dt>
2581         <dd class="description">File to print</dd>
2582 <dt>title</dt>
2583         <dd class="description">Title of job</dd>
2584 <dt>num_options</dt>
2585         <dd class="description">Number of options</dd>
2586 <dt>options</dt>
2587         <dd class="description">Options</dd>
2588 </dl>
2589 <h4 class="returnvalue">Return Value</h4>
2590         <p class="description">Job ID or 0 on error</p>
2591 <h3 class="function"><a id="cupsPrintFiles">cupsPrintFiles</a></h3>
2592         <p class="description">Print one or more files to a printer or class on the
2593 default server.</p>
2594 <p class="code">
2595 int cupsPrintFiles (<br />
2596 &#160;&#160;&#160;&#160;const char *name,<br />
2597 &#160;&#160;&#160;&#160;int num_files,<br />
2598 &#160;&#160;&#160;&#160;const char **files,<br />
2599 &#160;&#160;&#160;&#160;const char *title,<br />
2600 &#160;&#160;&#160;&#160;int num_options,<br />
2601 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options<br />
2602 );</p>
2603 <h4 class="parameters">Parameters</h4>
2604 <dl>
2605 <dt>name</dt>
2606         <dd class="description">Destination name</dd>
2607 <dt>num_files</dt>
2608         <dd class="description">Number of files</dd>
2609 <dt>files</dt>
2610         <dd class="description">File(s) to print</dd>
2611 <dt>title</dt>
2612         <dd class="description">Title of job</dd>
2613 <dt>num_options</dt>
2614         <dd class="description">Number of options</dd>
2615 <dt>options</dt>
2616         <dd class="description">Options</dd>
2617 </dl>
2618 <h4 class="returnvalue">Return Value</h4>
2619         <p class="description">Job ID or 0 on error</p>
2620 <h3 class="function"><span class="info">&#160;CUPS 1.1.21/macOS 10.4&#160;</span><a id="cupsPrintFiles2">cupsPrintFiles2</a></h3>
2621         <p class="description">Print one or more files to a printer or class on the
2622 specified server.</p>
2623 <p class="code">
2624 int cupsPrintFiles2 (<br />
2625 &#160;&#160;&#160;&#160;http_t *http,<br />
2626 &#160;&#160;&#160;&#160;const char *name,<br />
2627 &#160;&#160;&#160;&#160;int num_files,<br />
2628 &#160;&#160;&#160;&#160;const char **files,<br />
2629 &#160;&#160;&#160;&#160;const char *title,<br />
2630 &#160;&#160;&#160;&#160;int num_options,<br />
2631 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options<br />
2632 );</p>
2633 <h4 class="parameters">Parameters</h4>
2634 <dl>
2635 <dt>http</dt>
2636         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
2637 <dt>name</dt>
2638         <dd class="description">Destination name</dd>
2639 <dt>num_files</dt>
2640         <dd class="description">Number of files</dd>
2641 <dt>files</dt>
2642         <dd class="description">File(s) to print</dd>
2643 <dt>title</dt>
2644         <dd class="description">Title of job</dd>
2645 <dt>num_options</dt>
2646         <dd class="description">Number of options</dd>
2647 <dt>options</dt>
2648         <dd class="description">Options</dd>
2649 </dl>
2650 <h4 class="returnvalue">Return Value</h4>
2651         <p class="description">Job ID or 0 on error</p>
2652 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsRemoveDest">cupsRemoveDest</a></h3>
2653         <p class="description">Remove a destination from the destination list.</p>
2654 <p class="code">
2655 int cupsRemoveDest (<br />
2656 &#160;&#160;&#160;&#160;const char *name,<br />
2657 &#160;&#160;&#160;&#160;const char *instance,<br />
2658 &#160;&#160;&#160;&#160;int num_dests,<br />
2659 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> **dests<br />
2660 );</p>
2661 <h4 class="parameters">Parameters</h4>
2662 <dl>
2663 <dt>name</dt>
2664         <dd class="description">Destination name</dd>
2665 <dt>instance</dt>
2666         <dd class="description">Instance name or <code>NULL</code></dd>
2667 <dt>num_dests</dt>
2668         <dd class="description">Number of destinations</dd>
2669 <dt>dests</dt>
2670         <dd class="description">Destinations</dd>
2671 </dl>
2672 <h4 class="returnvalue">Return Value</h4>
2673         <p class="description">New number of destinations</p>
2674 <h4 class="discussion">Discussion</h4>
2675         <p class="discussion">Removing a destination/instance does not delete the class or printer
2676 queue, merely the lpoptions for that destination/instance.  Use the
2677 <a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new
2678 options for the user.
2679
2680 </p>
2681 <h3 class="function"><span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsRemoveOption">cupsRemoveOption</a></h3>
2682         <p class="description">Remove an option from an option array.</p>
2683 <p class="code">
2684 int cupsRemoveOption (<br />
2685 &#160;&#160;&#160;&#160;const char *name,<br />
2686 &#160;&#160;&#160;&#160;int num_options,<br />
2687 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> **options<br />
2688 );</p>
2689 <h4 class="parameters">Parameters</h4>
2690 <dl>
2691 <dt>name</dt>
2692         <dd class="description">Option name</dd>
2693 <dt>num_options</dt>
2694         <dd class="description">Current number of options</dd>
2695 <dt>options</dt>
2696         <dd class="description">Options</dd>
2697 </dl>
2698 <h4 class="returnvalue">Return Value</h4>
2699         <p class="description">New number of options</p>
2700 <h3 class="function"><a id="cupsServer">cupsServer</a></h3>
2701         <p class="description">Return the hostname/address of the current server.</p>
2702 <p class="code">
2703 const char *cupsServer (void);</p>
2704 <h4 class="returnvalue">Return Value</h4>
2705         <p class="description">Server name</p>
2706 <h4 class="discussion">Discussion</h4>
2707         <p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the
2708 ~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not
2709 set, the default is the local system - either &quot;localhost&quot; or a domain socket
2710 path.<br>
2711 <br>
2712 The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
2713 address, or a domain socket pathname.<br>
2714 <br>
2715 Note: The current server is tracked separately for each thread in a program.
2716 Multi-threaded programs that override the server via the
2717 <a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same
2718 server to be used.</p>
2719 <h3 class="function"><span class="info">&#160;CUPS 1.5/macOS 10.7&#160;</span><a id="cupsSetClientCertCB">cupsSetClientCertCB</a></h3>
2720         <p class="description">Set the client certificate callback.</p>
2721 <p class="code">
2722 void cupsSetClientCertCB (<br />
2723 &#160;&#160;&#160;&#160;<a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a> cb,<br />
2724 &#160;&#160;&#160;&#160;void *user_data<br />
2725 );</p>
2726 <h4 class="parameters">Parameters</h4>
2727 <dl>
2728 <dt>cb</dt>
2729         <dd class="description">Callback function</dd>
2730 <dt>user_data</dt>
2731         <dd class="description">User data pointer</dd>
2732 </dl>
2733 <h4 class="discussion">Discussion</h4>
2734         <p class="discussion">Pass <code>NULL</code> to restore the default callback.<br>
2735 <br>
2736 Note: The current certificate callback is tracked separately for each thread
2737 in a program. Multi-threaded programs that override the callback need to do
2738 so in each thread for the same callback to be used.
2739
2740 </p>
2741 <h3 class="function"><span class="info">&#160;CUPS 1.5/macOS 10.7&#160;</span><a id="cupsSetCredentials">cupsSetCredentials</a></h3>
2742         <p class="description">Set the default credentials to be used for SSL/TLS
2743 connections.</p>
2744 <p class="code">
2745 int cupsSetCredentials (<br />
2746 &#160;&#160;&#160;&#160;cups_array_t *credentials<br />
2747 );</p>
2748 <h4 class="parameters">Parameters</h4>
2749 <dl>
2750 <dt>credentials</dt>
2751         <dd class="description">Array of credentials</dd>
2752 </dl>
2753 <h4 class="returnvalue">Return Value</h4>
2754         <p class="description">Status of call (0 = success)</p>
2755 <h4 class="discussion">Discussion</h4>
2756         <p class="discussion">Note: The default credentials are tracked separately for each thread in a
2757 program. Multi-threaded programs that override the setting need to do so in
2758 each thread for the same setting to be used.
2759
2760 </p>
2761 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
2762         <p class="description">Set the default destination.</p>
2763 <p class="code">
2764 void cupsSetDefaultDest (<br />
2765 &#160;&#160;&#160;&#160;const char *name,<br />
2766 &#160;&#160;&#160;&#160;const char *instance,<br />
2767 &#160;&#160;&#160;&#160;int num_dests,<br />
2768 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dests<br />
2769 );</p>
2770 <h4 class="parameters">Parameters</h4>
2771 <dl>
2772 <dt>name</dt>
2773         <dd class="description">Destination name</dd>
2774 <dt>instance</dt>
2775         <dd class="description">Instance name or <code>NULL</code></dd>
2776 <dt>num_dests</dt>
2777         <dd class="description">Number of destinations</dd>
2778 <dt>dests</dt>
2779         <dd class="description">Destinations</dd>
2780 </dl>
2781 <h3 class="function"><a id="cupsSetDests">cupsSetDests</a></h3>
2782         <p class="description">Save the list of destinations for the default server.</p>
2783 <p class="code">
2784 void cupsSetDests (<br />
2785 &#160;&#160;&#160;&#160;int num_dests,<br />
2786 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dests<br />
2787 );</p>
2788 <h4 class="parameters">Parameters</h4>
2789 <dl>
2790 <dt>num_dests</dt>
2791         <dd class="description">Number of destinations</dd>
2792 <dt>dests</dt>
2793         <dd class="description">Destinations</dd>
2794 </dl>
2795 <h4 class="discussion">Discussion</h4>
2796         <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
2797 as root and ~/.cups/lpoptions when run as a normal user.</p>
2798 <h3 class="function"><span class="info">&#160;CUPS 1.1.21/macOS 10.4&#160;</span><a id="cupsSetDests2">cupsSetDests2</a></h3>
2799         <p class="description">Save the list of destinations for the specified server.</p>
2800 <p class="code">
2801 int cupsSetDests2 (<br />
2802 &#160;&#160;&#160;&#160;http_t *http,<br />
2803 &#160;&#160;&#160;&#160;int num_dests,<br />
2804 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dests<br />
2805 );</p>
2806 <h4 class="parameters">Parameters</h4>
2807 <dl>
2808 <dt>http</dt>
2809         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
2810 <dt>num_dests</dt>
2811         <dd class="description">Number of destinations</dd>
2812 <dt>dests</dt>
2813         <dd class="description">Destinations</dd>
2814 </dl>
2815 <h4 class="returnvalue">Return Value</h4>
2816         <p class="description">0 on success, -1 on error</p>
2817 <h4 class="discussion">Discussion</h4>
2818         <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
2819 as root and ~/.cups/lpoptions when run as a normal user.
2820
2821 </p>
2822 <h3 class="function"><a id="cupsSetEncryption">cupsSetEncryption</a></h3>
2823         <p class="description">Set the encryption preference.</p>
2824 <p class="code">
2825 void cupsSetEncryption (<br />
2826 &#160;&#160;&#160;&#160;http_encryption_t e<br />
2827 );</p>
2828 <h4 class="parameters">Parameters</h4>
2829 <dl>
2830 <dt>e</dt>
2831         <dd class="description">New encryption preference</dd>
2832 </dl>
2833 <h4 class="discussion">Discussion</h4>
2834         <p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
2835 environment variable, then the ~/.cups/client.conf file, and finally the
2836 /etc/cups/client.conf file. If not set, the default is
2837 <code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br>
2838 <br>
2839 Note: The current encryption setting is tracked separately for each thread
2840 in a program. Multi-threaded programs that override the setting need to do
2841 so in each thread for the same setting to be used.</p>
2842 <h3 class="function"><a id="cupsSetPasswordCB">cupsSetPasswordCB</a></h3>
2843         <p class="description">Set the password callback for CUPS.</p>
2844 <p class="code">
2845 void cupsSetPasswordCB (<br />
2846 &#160;&#160;&#160;&#160;<a href="#cups_password_cb_t">cups_password_cb_t</a> cb<br />
2847 );</p>
2848 <h4 class="parameters">Parameters</h4>
2849 <dl>
2850 <dt>cb</dt>
2851         <dd class="description">Callback function</dd>
2852 </dl>
2853 <h4 class="discussion">Discussion</h4>
2854         <p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
2855 reads the password from the console. Programs should call either this
2856 function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
2857 by a program per thread.<br>
2858 <br>
2859 Note: The current password callback is tracked separately for each thread
2860 in a program. Multi-threaded programs that override the callback need to do
2861 so in each thread for the same callback to be used.</p>
2862 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3>
2863         <p class="description">Set the advanced password callback for CUPS.</p>
2864 <p class="code">
2865 void cupsSetPasswordCB2 (<br />
2866 &#160;&#160;&#160;&#160;<a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb,<br />
2867 &#160;&#160;&#160;&#160;void *user_data<br />
2868 );</p>
2869 <h4 class="parameters">Parameters</h4>
2870 <dl>
2871 <dt>cb</dt>
2872         <dd class="description">Callback function</dd>
2873 <dt>user_data</dt>
2874         <dd class="description">User data pointer</dd>
2875 </dl>
2876 <h4 class="discussion">Discussion</h4>
2877         <p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
2878 reads the password from the console. Programs should call either this
2879 function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
2880 by a program per thread.<br>
2881 <br>
2882 Note: The current password callback is tracked separately for each thread
2883 in a program. Multi-threaded programs that override the callback need to do
2884 so in each thread for the same callback to be used.
2885
2886 </p>
2887 <h3 class="function"><a id="cupsSetServer">cupsSetServer</a></h3>
2888         <p class="description">Set the default server name and port.</p>
2889 <p class="code">
2890 void cupsSetServer (<br />
2891 &#160;&#160;&#160;&#160;const char *server<br />
2892 );</p>
2893 <h4 class="parameters">Parameters</h4>
2894 <dl>
2895 <dt>server</dt>
2896         <dd class="description">Server name</dd>
2897 </dl>
2898 <h4 class="discussion">Discussion</h4>
2899         <p class="discussion">The &quot;server&quot; string can be a fully-qualified hostname, a numeric
2900 IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP
2901 addresses can be optionally followed by a colon and port number to override
2902 the default port 631, e.g. &quot;hostname:8631&quot;. Pass <code>NULL</code> to restore the
2903 default server name and port.<br>
2904 <br>
2905 Note: The current server is tracked separately for each thread in a program.
2906 Multi-threaded programs that override the server need to do so in each
2907 thread for the same server to be used.</p>
2908 <h3 class="function"><span class="info">&#160;CUPS 1.5/macOS 10.7&#160;</span><a id="cupsSetServerCertCB">cupsSetServerCertCB</a></h3>
2909         <p class="description">Set the server certificate callback.</p>
2910 <p class="code">
2911 void cupsSetServerCertCB (<br />
2912 &#160;&#160;&#160;&#160;<a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a> cb,<br />
2913 &#160;&#160;&#160;&#160;void *user_data<br />
2914 );</p>
2915 <h4 class="parameters">Parameters</h4>
2916 <dl>
2917 <dt>cb</dt>
2918         <dd class="description">Callback function</dd>
2919 <dt>user_data</dt>
2920         <dd class="description">User data pointer</dd>
2921 </dl>
2922 <h4 class="discussion">Discussion</h4>
2923         <p class="discussion">Pass <code>NULL</code> to restore the default callback.<br>
2924 <br>
2925 Note: The current credentials callback is tracked separately for each thread
2926 in a program. Multi-threaded programs that override the callback need to do
2927 so in each thread for the same callback to be used.
2928
2929 </p>
2930 <h3 class="function"><a id="cupsSetUser">cupsSetUser</a></h3>
2931         <p class="description">Set the default user name.</p>
2932 <p class="code">
2933 void cupsSetUser (<br />
2934 &#160;&#160;&#160;&#160;const char *user<br />
2935 );</p>
2936 <h4 class="parameters">Parameters</h4>
2937 <dl>
2938 <dt>user</dt>
2939         <dd class="description">User name</dd>
2940 </dl>
2941 <h4 class="discussion">Discussion</h4>
2942         <p class="discussion">Pass <code>NULL</code> to restore the default user name.<br>
2943 <br>
2944 Note: The current user name is tracked separately for each thread in a
2945 program. Multi-threaded programs that override the user name need to do so
2946 in each thread for the same user name to be used.</p>
2947 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsSetUserAgent">cupsSetUserAgent</a></h3>
2948         <p class="description">Set the default HTTP User-Agent string.</p>
2949 <p class="code">
2950 void cupsSetUserAgent (<br />
2951 &#160;&#160;&#160;&#160;const char *user_agent<br />
2952 );</p>
2953 <h4 class="parameters">Parameters</h4>
2954 <dl>
2955 <dt>user_agent</dt>
2956         <dd class="description">User-Agent string or <code>NULL</code></dd>
2957 </dl>
2958 <h4 class="discussion">Discussion</h4>
2959         <p class="discussion">Setting the string to NULL forces the default value containing the CUPS
2960 version, IPP version, and operating system version and architecture.
2961
2962 </p>
2963 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsStartDestDocument">cupsStartDestDocument</a></h3>
2964         <p class="description">Start a new document.</p>
2965 <p class="code">
2966 http_status_t cupsStartDestDocument (<br />
2967 &#160;&#160;&#160;&#160;http_t *http,<br />
2968 &#160;&#160;&#160;&#160;<a href="#cups_dest_t">cups_dest_t</a> *dest,<br />
2969 &#160;&#160;&#160;&#160;<a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br />
2970 &#160;&#160;&#160;&#160;int job_id,<br />
2971 &#160;&#160;&#160;&#160;const char *docname,<br />
2972 &#160;&#160;&#160;&#160;const char *format,<br />
2973 &#160;&#160;&#160;&#160;int num_options,<br />
2974 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options,<br />
2975 &#160;&#160;&#160;&#160;int last_document<br />
2976 );</p>
2977 <h4 class="parameters">Parameters</h4>
2978 <dl>
2979 <dt>http</dt>
2980         <dd class="description">Connection to destination</dd>
2981 <dt>dest</dt>
2982         <dd class="description">Destination</dd>
2983 <dt>info</dt>
2984         <dd class="description">Destination information</dd>
2985 <dt>job_id</dt>
2986         <dd class="description">Job ID</dd>
2987 <dt>docname</dt>
2988         <dd class="description">Document name</dd>
2989 <dt>format</dt>
2990         <dd class="description">Document format</dd>
2991 <dt>num_options</dt>
2992         <dd class="description">Number of document options</dd>
2993 <dt>options</dt>
2994         <dd class="description">Document options</dd>
2995 <dt>last_document</dt>
2996         <dd class="description">1 if this is the last document</dd>
2997 </dl>
2998 <h4 class="returnvalue">Return Value</h4>
2999         <p class="description">Status of document creation</p>
3000 <h4 class="discussion">Discussion</h4>
3001         <p class="discussion">&quot;job_id&quot; is the job ID returned by cupsCreateDestJob.  &quot;docname&quot; is the name
3002 of the document/file being printed, &quot;format&quot; is the MIME media type for the
3003 document (see CUPS_FORMAT_xxx constants), and &quot;num_options&quot; and &quot;options&quot;
3004 are the options do be applied to the document. &quot;last_document&quot; should be 1
3005 if this is the last document to be submitted in the job.  Returns
3006 <code>HTTP_CONTINUE</code> on success.
3007
3008 </p>
3009 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsStartDocument">cupsStartDocument</a></h3>
3010         <p class="description">Add a document to a job created with cupsCreateJob().</p>
3011 <p class="code">
3012 http_status_t cupsStartDocument (<br />
3013 &#160;&#160;&#160;&#160;http_t *http,<br />
3014 &#160;&#160;&#160;&#160;const char *name,<br />
3015 &#160;&#160;&#160;&#160;int job_id,<br />
3016 &#160;&#160;&#160;&#160;const char *docname,<br />
3017 &#160;&#160;&#160;&#160;const char *format,<br />
3018 &#160;&#160;&#160;&#160;int last_document<br />
3019 );</p>
3020 <h4 class="parameters">Parameters</h4>
3021 <dl>
3022 <dt>http</dt>
3023         <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
3024 <dt>name</dt>
3025         <dd class="description">Destination name</dd>
3026 <dt>job_id</dt>
3027         <dd class="description">Job ID from <a href="#cupsCreateJob"><code>cupsCreateJob</code></a></dd>
3028 <dt>docname</dt>
3029         <dd class="description">Name of document</dd>
3030 <dt>format</dt>
3031         <dd class="description">MIME type or <code>CUPS_FORMAT_foo</code></dd>
3032 <dt>last_document</dt>
3033         <dd class="description">1 for last document in job, 0 otherwise</dd>
3034 </dl>
3035 <h4 class="returnvalue">Return Value</h4>
3036         <p class="description">HTTP status of request</p>
3037 <h4 class="discussion">Discussion</h4>
3038         <p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write data for the document and
3039 <a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> to finish the document and get the submission status.<br>
3040 <br>
3041 The MIME type constants <code>CUPS_FORMAT_AUTO</code>, <code>CUPS_FORMAT_PDF</code>,
3042 <code>CUPS_FORMAT_POSTSCRIPT</code>, <code>CUPS_FORMAT_RAW</code>, and
3043 <code>CUPS_FORMAT_TEXT</code> are provided for the &quot;format&quot; argument, although
3044 any supported MIME type string can be supplied.
3045
3046 </p>
3047 <h3 class="function"><a id="cupsTempFd">cupsTempFd</a></h3>
3048         <p class="description">Creates a temporary file.</p>
3049 <p class="code">
3050 int cupsTempFd (<br />
3051 &#160;&#160;&#160;&#160;char *filename,<br />
3052 &#160;&#160;&#160;&#160;int len<br />
3053 );</p>
3054 <h4 class="parameters">Parameters</h4>
3055 <dl>
3056 <dt>filename</dt>
3057         <dd class="description">Pointer to buffer</dd>
3058 <dt>len</dt>
3059         <dd class="description">Size of buffer</dd>
3060 </dl>
3061 <h4 class="returnvalue">Return Value</h4>
3062         <p class="description">New file descriptor or -1 on error</p>
3063 <h4 class="discussion">Discussion</h4>
3064         <p class="discussion">The temporary filename is returned in the filename buffer.
3065 The temporary file is opened for reading and writing.</p>
3066 <h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsTempFile">cupsTempFile</a></h3>
3067         <p class="description">Generates a temporary filename.</p>
3068 <p class="code">
3069 char *cupsTempFile (<br />
3070 &#160;&#160;&#160;&#160;char *filename,<br />
3071 &#160;&#160;&#160;&#160;int len<br />
3072 );</p>
3073 <h4 class="parameters">Parameters</h4>
3074 <dl>
3075 <dt>filename</dt>
3076         <dd class="description">Pointer to buffer</dd>
3077 <dt>len</dt>
3078         <dd class="description">Size of buffer</dd>
3079 </dl>
3080 <h4 class="returnvalue">Return Value</h4>
3081         <p class="description">Filename or <code>NULL</code> on error</p>
3082 <h4 class="discussion">Discussion</h4>
3083         <p class="discussion">The temporary filename is returned in the filename buffer.
3084 This function is deprecated and will no longer generate a temporary
3085 filename - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or <a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead.
3086
3087 </p>
3088 <h3 class="function"><span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsTempFile2">cupsTempFile2</a></h3>
3089         <p class="description">Creates a temporary CUPS file.</p>
3090 <p class="code">
3091 cups_file_t *cupsTempFile2 (<br />
3092 &#160;&#160;&#160;&#160;char *filename,<br />
3093 &#160;&#160;&#160;&#160;int len<br />
3094 );</p>
3095 <h4 class="parameters">Parameters</h4>
3096 <dl>
3097 <dt>filename</dt>
3098         <dd class="description">Pointer to buffer</dd>
3099 <dt>len</dt>
3100         <dd class="description">Size of buffer</dd>
3101 </dl>
3102 <h4 class="returnvalue">Return Value</h4>
3103         <p class="description">CUPS file or <code>NULL</code> on error</p>
3104 <h4 class="discussion">Discussion</h4>
3105         <p class="discussion">The temporary filename is returned in the filename buffer.
3106 The temporary file is opened for writing.
3107
3108 </p>
3109 <h3 class="function"><a id="cupsUser">cupsUser</a></h3>
3110         <p class="description">Return the current user's name.</p>
3111 <p class="code">
3112 const char *cupsUser (void);</p>
3113 <h4 class="returnvalue">Return Value</h4>
3114         <p class="description">User name</p>
3115 <h4 class="discussion">Discussion</h4>
3116         <p class="discussion">Note: The current user name is tracked separately for each thread in a
3117 program. Multi-threaded programs that override the user name with the
3118 <a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user
3119 name to be used.</p>
3120 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsUserAgent">cupsUserAgent</a></h3>
3121         <p class="description">Return the default HTTP User-Agent string.</p>
3122 <p class="code">
3123 const char *cupsUserAgent (void);</p>
3124 <h4 class="returnvalue">Return Value</h4>
3125         <p class="description">User-Agent string</p>
3126 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="pwgFormatSizeName">pwgFormatSizeName</a></h3>
3127         <p class="description">Generate a PWG self-describing media size name.</p>
3128 <p class="code">
3129 int pwgFormatSizeName (<br />
3130 &#160;&#160;&#160;&#160;char *keyword,<br />
3131 &#160;&#160;&#160;&#160;size_t keysize,<br />
3132 &#160;&#160;&#160;&#160;const char *prefix,<br />
3133 &#160;&#160;&#160;&#160;const char *name,<br />
3134 &#160;&#160;&#160;&#160;int width,<br />
3135 &#160;&#160;&#160;&#160;int length,<br />
3136 &#160;&#160;&#160;&#160;const char *units<br />
3137 );</p>
3138 <h4 class="parameters">Parameters</h4>
3139 <dl>
3140 <dt>keyword</dt>
3141         <dd class="description">Keyword buffer</dd>
3142 <dt>keysize</dt>
3143         <dd class="description">Size of keyword buffer</dd>
3144 <dt>prefix</dt>
3145         <dd class="description">Prefix for PWG size or <code>NULL</code> for automatic</dd>
3146 <dt>name</dt>
3147         <dd class="description">Size name or <code>NULL</code></dd>
3148 <dt>width</dt>
3149         <dd class="description">Width of page in 2540ths</dd>
3150 <dt>length</dt>
3151         <dd class="description">Length of page in 2540ths</dd>
3152 <dt>units</dt>
3153         <dd class="description">Units - &quot;in&quot;, &quot;mm&quot;, or <code>NULL</code> for automatic</dd>
3154 </dl>
3155 <h4 class="returnvalue">Return Value</h4>
3156         <p class="description">1 on success, 0 on failure</p>
3157 <h4 class="discussion">Discussion</h4>
3158         <p class="discussion">This function generates a PWG self-describing media size name of the form
3159 &quot;prefix_name_WIDTHxLENGTHunits&quot;.  The prefix is typically &quot;custom&quot; or &quot;roll&quot;
3160 for user-supplied sizes but can also be &quot;disc&quot;, &quot;iso&quot;, &quot;jis&quot;, &quot;jpn&quot;, &quot;na&quot;,
3161 &quot;oe&quot;, &quot;om&quot;, &quot;prc&quot;, or &quot;roc&quot;.  A value of <code>NULL</code> automatically chooses
3162 &quot;oe&quot; or &quot;om&quot; depending on the units.<br>
3163 <br>
3164 The size name may only contain lowercase letters, numbers, &quot;-&quot;, and &quot;.&quot;.  If
3165 <code>NULL</code> is passed, the size name will contain the formatted dimensions.<br>
3166 <br>
3167 The width and length are specified in hundredths of millimeters, equivalent
3168 to 1/100000th of a meter or 1/2540th of an inch.  The width, length, and
3169 units used for the generated size name are calculated automatically if the
3170 units string is <code>NULL</code>, otherwise inches (&quot;in&quot;) or millimeters (&quot;mm&quot;)
3171 are used.
3172
3173 </p>
3174 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="pwgInitSize">pwgInitSize</a></h3>
3175         <p class="description">Initialize a pwg_size_t structure using IPP Job Template
3176 attributes.</p>
3177 <p class="code">
3178 int pwgInitSize (<br />
3179 &#160;&#160;&#160;&#160;<a href="#pwg_size_t">pwg_size_t</a> *size,<br />
3180 &#160;&#160;&#160;&#160;ipp_t *job,<br />
3181 &#160;&#160;&#160;&#160;int *margins_set<br />
3182 );</p>
3183 <h4 class="parameters">Parameters</h4>
3184 <dl>
3185 <dt>size</dt>
3186         <dd class="description">Size to initialize</dd>
3187 <dt>job</dt>
3188         <dd class="description">Job template attributes</dd>
3189 <dt>margins_set</dt>
3190         <dd class="description">1 if margins were set, 0 otherwise</dd>
3191 </dl>
3192 <h4 class="returnvalue">Return Value</h4>
3193         <p class="description">1 if size was initialized, 0 otherwise</p>
3194 <h4 class="discussion">Discussion</h4>
3195         <p class="discussion">This function initializes a pwg_size_t structure from an IPP &quot;media&quot; or
3196 &quot;media-col&quot; attribute in the specified IPP message.  0 is returned if neither
3197 attribute is found in the message or the values are not valid.<br>
3198 <br>
3199 The &quot;margins_set&quot; variable is initialized to 1 if any &quot;media-xxx-margin&quot;
3200 member attribute was specified in the &quot;media-col&quot; Job Template attribute,
3201 otherwise it is initialized to 0.
3202
3203 </p>
3204 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="pwgMediaForLegacy">pwgMediaForLegacy</a></h3>
3205         <p class="description">Find a PWG media size by ISO/IPP legacy name.</p>
3206 <p class="code">
3207 <a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForLegacy (<br />
3208 &#160;&#160;&#160;&#160;const char *legacy<br />
3209 );</p>
3210 <h4 class="parameters">Parameters</h4>
3211 <dl>
3212 <dt>legacy</dt>
3213         <dd class="description">Legacy size name</dd>
3214 </dl>
3215 <h4 class="returnvalue">Return Value</h4>
3216         <p class="description">Matching size or NULL</p>
3217 <h4 class="discussion">Discussion</h4>
3218         <p class="discussion">The &quot;name&quot; argument specifies the legacy ISO media size name, for example
3219 &quot;iso-a4&quot; or &quot;na-letter&quot;.
3220
3221 </p>
3222 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="pwgMediaForPPD">pwgMediaForPPD</a></h3>
3223         <p class="description">Find a PWG media size by Adobe PPD name.</p>
3224 <p class="code">
3225 <a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPPD (<br />
3226 &#160;&#160;&#160;&#160;const char *ppd<br />
3227 );</p>
3228 <h4 class="parameters">Parameters</h4>
3229 <dl>
3230 <dt>ppd</dt>
3231         <dd class="description">PPD size name</dd>
3232 </dl>
3233 <h4 class="returnvalue">Return Value</h4>
3234         <p class="description">Matching size or NULL</p>
3235 <h4 class="discussion">Discussion</h4>
3236         <p class="discussion">The &quot;ppd&quot; argument specifies an Adobe page size name as defined in Table B.1
3237 of the Adobe PostScript Printer Description File Format Specification Version
3238 4.3.<br>
3239 <br>
3240 If the name is non-standard, the returned PWG media size is stored in
3241 thread-local storage and is overwritten by each call to the function in the
3242 thread.  Custom names can be of the form &quot;Custom.WIDTHxLENGTH[units]&quot; or
3243 &quot;WIDTHxLENGTH[units]&quot;.
3244
3245 </p>
3246 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="pwgMediaForPWG">pwgMediaForPWG</a></h3>
3247         <p class="description">Find a PWG media size by 5101.1 self-describing name.</p>
3248 <p class="code">
3249 <a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPWG (<br />
3250 &#160;&#160;&#160;&#160;const char *pwg<br />
3251 );</p>
3252 <h4 class="parameters">Parameters</h4>
3253 <dl>
3254 <dt>pwg</dt>
3255         <dd class="description">PWG size name</dd>
3256 </dl>
3257 <h4 class="returnvalue">Return Value</h4>
3258         <p class="description">Matching size or NULL</p>
3259 <h4 class="discussion">Discussion</h4>
3260         <p class="discussion">The &quot;pwg&quot; argument specifies a self-describing media size name of the form
3261 &quot;prefix_name_WIDTHxLENGTHunits&quot; as defined in PWG 5101.1.<br>
3262 <br>
3263 If the name is non-standard, the returned PWG media size is stored in
3264 thread-local storage and is overwritten by each call to the function in the
3265 thread.
3266
3267 </p>
3268 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="pwgMediaForSize">pwgMediaForSize</a></h3>
3269         <p class="description">Get the PWG media size for the given dimensions.</p>
3270 <p class="code">
3271 <a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForSize (<br />
3272 &#160;&#160;&#160;&#160;int width,<br />
3273 &#160;&#160;&#160;&#160;int length<br />
3274 );</p>
3275 <h4 class="parameters">Parameters</h4>
3276 <dl>
3277 <dt>width</dt>
3278         <dd class="description">Width in hundredths of millimeters</dd>
3279 <dt>length</dt>
3280         <dd class="description">Length in hundredths of millimeters</dd>
3281 </dl>
3282 <h4 class="returnvalue">Return Value</h4>
3283         <p class="description">PWG media name</p>
3284 <h4 class="discussion">Discussion</h4>
3285         <p class="discussion">The &quot;width&quot; and &quot;length&quot; are in hundredths of millimeters, equivalent to
3286 1/100000th of a meter or 1/2540th of an inch.<br>
3287 <br>
3288 If the dimensions are non-standard, the returned PWG media size is stored in
3289 thread-local storage and is overwritten by each call to the function in the
3290 thread.
3291
3292 </p>
3293       <h2 class="title"><a id="TYPES">Data Types</a></h2>
3294       <h3 class="typedef"><a id="cups_client_cert_cb_t"><span class="info">&#160;CUPS 1.5/macOS 10.7&#160;</span>cups_client_cert_cb_t</a></h3>
3295         <p class="description">Client credentials callback
3296 </p>
3297       <p class="code">
3298 typedef int (*cups_client_cert_cb_t)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data);
3299 </p>
3300       <h3 class="typedef"><a id="cups_dest_block_t"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span>cups_dest_block_t</a></h3>
3301         <p class="description">Destination enumeration block
3302 </p>
3303       <p class="code">
3304 typedef int (*cups_dest_block_t(unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest);
3305 </p>
3306       <h3 class="typedef"><a id="cups_dest_cb_t"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span>cups_dest_cb_t</a></h3>
3307         <p class="description">Destination enumeration callback
3308 </p>
3309       <p class="code">
3310 typedef int (*cups_dest_cb_t)(void *user_data, unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest);
3311 </p>
3312       <h3 class="typedef"><a id="cups_dest_t">cups_dest_t</a></h3>
3313         <p class="description">Destination</p>
3314       <p class="code">
3315 typedef struct <a href="#cups_dest_s">cups_dest_s</a> cups_dest_t;
3316 </p>
3317       <h3 class="typedef"><a id="cups_dinfo_t"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span>cups_dinfo_t</a></h3>
3318         <p class="description">Destination capability and status
3319 information </p>
3320       <p class="code">
3321 typedef struct _cups_dinfo_s cups_dinfo_t;
3322 </p>
3323       <h3 class="typedef"><a id="cups_job_t">cups_job_t</a></h3>
3324         <p class="description">Job</p>
3325       <p class="code">
3326 typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t;
3327 </p>
3328       <h3 class="typedef"><a id="cups_option_t">cups_option_t</a></h3>
3329         <p class="description">Printer Options</p>
3330       <p class="code">
3331 typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t;
3332 </p>
3333       <h3 class="typedef"><a id="cups_password_cb2_t"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span>cups_password_cb2_t</a></h3>
3334         <p class="description">New password callback
3335 </p>
3336       <p class="code">
3337 typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data);
3338 </p>
3339       <h3 class="typedef"><a id="cups_password_cb_t">cups_password_cb_t</a></h3>
3340         <p class="description">Password callback</p>
3341       <p class="code">
3342 typedef const char *(*cups_password_cb_t)(const char *prompt);
3343 </p>
3344       <h3 class="typedef"><a id="cups_ptype_t">cups_ptype_t</a></h3>
3345         <p class="description">Printer type/capability bits</p>
3346       <p class="code">
3347 typedef unsigned cups_ptype_t;
3348 </p>
3349       <h3 class="typedef"><a id="cups_server_cert_cb_t"><span class="info">&#160;CUPS 1.5/macOS 10.7&#160;</span>cups_server_cert_cb_t</a></h3>
3350         <p class="description">Server credentials callback
3351 </p>
3352       <p class="code">
3353 typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *certs, void *user_data);
3354 </p>
3355       <h3 class="typedef"><a id="cups_size_t"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span>cups_size_t</a></h3>
3356         <p class="description">Media Size </p>
3357       <p class="code">
3358 typedef struct <a href="#cups_size_s">cups_size_s</a> cups_size_t;
3359 </p>
3360       <h3 class="typedef"><a id="pwg_map_t">pwg_map_t</a></h3>
3361         <p class="description">Map element - PPD to/from PWG</p>
3362       <p class="code">
3363 typedef struct <a href="#pwg_map_s">pwg_map_s</a> pwg_map_t;
3364 </p>
3365       <h3 class="typedef"><a id="pwg_media_t">pwg_media_t</a></h3>
3366         <p class="description">Common media size data</p>
3367       <p class="code">
3368 typedef struct <a href="#pwg_media_s">pwg_media_s</a> pwg_media_t;
3369 </p>
3370       <h3 class="typedef"><a id="pwg_size_t">pwg_size_t</a></h3>
3371         <p class="description">Size element - PPD to/from PWG</p>
3372       <p class="code">
3373 typedef struct <a href="#pwg_size_s">pwg_size_s</a> pwg_size_t;
3374 </p>
3375       <h2 class="title"><a id="STRUCTURES">Structures</a></h2>
3376 <h3 class="struct"><a id="cups_dest_s">cups_dest_s</a></h3>
3377         <p class="description">Destination</p>
3378 <p class="code">struct cups_dest_s {<br />
3379 &#160;&#160;&#160;&#160;char *name, *instance;<br />
3380 &#160;&#160;&#160;&#160;int is_default;<br />
3381 &#160;&#160;&#160;&#160;int num_options;<br />
3382 &#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options;<br />
3383 };</p>
3384 <h4 class="members">Members</h4>
3385 <dl>
3386 <dt>instance </dt>
3387         <dd class="description">Local instance name or NULL</dd>
3388 <dt>is_default </dt>
3389         <dd class="description">Is this printer the default?</dd>
3390 <dt>num_options </dt>
3391         <dd class="description">Number of options</dd>
3392 <dt>options </dt>
3393         <dd class="description">Options</dd>
3394 </dl>
3395 <h3 class="struct"><a id="cups_job_s">cups_job_s</a></h3>
3396         <p class="description">Job</p>
3397 <p class="code">struct cups_job_s {<br />
3398 &#160;&#160;&#160;&#160;time_t completed_time;<br />
3399 &#160;&#160;&#160;&#160;time_t creation_time;<br />
3400 &#160;&#160;&#160;&#160;char *dest;<br />
3401 &#160;&#160;&#160;&#160;char *format;<br />
3402 &#160;&#160;&#160;&#160;int id;<br />
3403 &#160;&#160;&#160;&#160;int priority;<br />
3404 &#160;&#160;&#160;&#160;time_t processing_time;<br />
3405 &#160;&#160;&#160;&#160;int size;<br />
3406 &#160;&#160;&#160;&#160;ipp_jstate_t state;<br />
3407 &#160;&#160;&#160;&#160;char *title;<br />
3408 &#160;&#160;&#160;&#160;char *user;<br />
3409 };</p>
3410 <h4 class="members">Members</h4>
3411 <dl>
3412 <dt>completed_time </dt>
3413         <dd class="description">Time the job was completed</dd>
3414 <dt>creation_time </dt>
3415         <dd class="description">Time the job was created</dd>
3416 <dt>dest </dt>
3417         <dd class="description">Printer or class name</dd>
3418 <dt>format </dt>
3419         <dd class="description">Document format</dd>
3420 <dt>id </dt>
3421         <dd class="description">The job ID</dd>
3422 <dt>priority </dt>
3423         <dd class="description">Priority (1-100)</dd>
3424 <dt>processing_time </dt>
3425         <dd class="description">Time the job was processed</dd>
3426 <dt>size </dt>
3427         <dd class="description">Size in kilobytes</dd>
3428 <dt>state </dt>
3429         <dd class="description">Job state</dd>
3430 <dt>title </dt>
3431         <dd class="description">Title/job name</dd>
3432 <dt>user </dt>
3433         <dd class="description">User the submitted the job</dd>
3434 </dl>
3435 <h3 class="struct"><a id="cups_option_s">cups_option_s</a></h3>
3436         <p class="description">Printer Options</p>
3437 <p class="code">struct cups_option_s {<br />
3438 &#160;&#160;&#160;&#160;char *name;<br />
3439 &#160;&#160;&#160;&#160;char *value;<br />
3440 };</p>
3441 <h4 class="members">Members</h4>
3442 <dl>
3443 <dt>name </dt>
3444         <dd class="description">Name of option</dd>
3445 <dt>value </dt>
3446         <dd class="description">Value of option</dd>
3447 </dl>
3448 <h3 class="struct"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cups_size_s">cups_size_s</a></h3>
3449         <p class="description">Media Size </p>
3450 <p class="code">struct cups_size_s {<br />
3451 &#160;&#160;&#160;&#160;char media[128];<br />
3452 &#160;&#160;&#160;&#160;int width, length, bottom, left, right, top;<br />
3453 };</p>
3454 <h4 class="members">Members</h4>
3455 <dl>
3456 <dt>media[128] </dt>
3457         <dd class="description">Media name to use</dd>
3458 <dt>top </dt>
3459         <dd class="description">Top margin in hundredths of
3460 millimeters</dd>
3461 </dl>
3462 <h3 class="struct"><a id="pollfd">pollfd</a></h3>
3463         <p class="description">User data (unused)</p>
3464 <p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br />
3465 &#160;&#160;&#160;&#160;_cups_dnssd_data_t *data;<br />
3466 &#160;&#160;&#160;&#160;else if(val 0) data - got_data;<br />
3467 &#160;&#160;&#160;&#160;void) timeout;<br />
3468 &#160;&#160;&#160;&#160;int val;<br />
3469 };</p>
3470 <h4 class="members">Members</h4>
3471 <dl>
3472 <dt>data </dt>
3473         <dd class="description">Enumeration data</dd>
3474 <dt>got_data </dt>
3475 <dt>timeout </dt>
3476 <dt>val </dt>
3477         <dd class="description">Return value</dd>
3478 </dl>
3479 <h3 class="struct"><a id="pwg_map_s">pwg_map_s</a></h3>
3480         <p class="description">Map element - PPD to/from PWG</p>
3481 <p class="code">struct pwg_map_s {<br />
3482 &#160;&#160;&#160;&#160;char *pwg, *ppd;<br />
3483 };</p>
3484 <h4 class="members">Members</h4>
3485 <dl>
3486 <dt>ppd </dt>
3487         <dd class="description">PPD option keyword</dd>
3488 </dl>
3489 <h3 class="struct"><a id="pwg_media_s">pwg_media_s</a></h3>
3490         <p class="description">Common media size data</p>
3491 <p class="code">struct pwg_media_s {<br />
3492 &#160;&#160;&#160;&#160;int width, length;<br />
3493 &#160;&#160;&#160;&#160;const char *pwg, *legacy, *ppd;<br />
3494 };</p>
3495 <h4 class="members">Members</h4>
3496 <dl>
3497 <dt>length </dt>
3498         <dd class="description">Length in 2540ths</dd>
3499 <dt>ppd </dt>
3500         <dd class="description">Standard Adobe PPD name</dd>
3501 </dl>
3502 <h3 class="struct"><a id="pwg_size_s">pwg_size_s</a></h3>
3503         <p class="description">Size element - PPD to/from PWG</p>
3504 <p class="code">struct pwg_size_s {<br />
3505 &#160;&#160;&#160;&#160;<a href="#pwg_map_t">pwg_map_t</a> map;<br />
3506 &#160;&#160;&#160;&#160;int width, length, left, bottom, right, top;<br />
3507 };</p>
3508 <h4 class="members">Members</h4>
3509 <dl>
3510 <dt>map </dt>
3511         <dd class="description">Map element</dd>
3512 <dt>top </dt>
3513         <dd class="description">Top margin in 2540ths</dd>
3514 </dl>
3515       <h2 class="title"><a id="VARIABLES">Variables</a></h2>
3516       <h3 class="variable"><a id="CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></h3>
3517         <p class="description">Get the Apple language identifier associated with a
3518 locale ID.</p>
3519       <p class="code">const char *locale) CF_RETURNS_RETAINED;</p>
3520       <h2 class="title"><a id="ENUMERATIONS">Constants</a></h2>
3521       <h3 class="enumeration"><a id="cups_ptype_e">cups_ptype_e</a></h3>
3522         <p class="description">Printer type/capability bit
3523 constants</p>
3524       <h4 class="constants">Constants</h4>
3525       <dl>
3526         <dt>CUPS_PRINTER_AUTHENTICATED <span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span></dt>
3527         <dd class="description">Printer requires authentication
3528 </dd>
3529         <dt>CUPS_PRINTER_BIND </dt>
3530         <dd class="description">Can bind output</dd>
3531         <dt>CUPS_PRINTER_BW </dt>
3532         <dd class="description">Can do B&amp;W printing</dd>
3533         <dt>CUPS_PRINTER_CLASS </dt>
3534         <dd class="description">Printer class</dd>
3535         <dt>CUPS_PRINTER_COLLATE </dt>
3536         <dd class="description">Can collage copies</dd>
3537         <dt>CUPS_PRINTER_COLOR </dt>
3538         <dd class="description">Can do color printing</dd>
3539         <dt>CUPS_PRINTER_COMMANDS <span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span></dt>
3540         <dd class="description">Printer supports maintenance commands
3541 </dd>
3542         <dt>CUPS_PRINTER_COPIES </dt>
3543         <dd class="description">Can do copies</dd>
3544         <dt>CUPS_PRINTER_COVER </dt>
3545         <dd class="description">Can cover output</dd>
3546         <dt>CUPS_PRINTER_DEFAULT </dt>
3547         <dd class="description">Default printer on network</dd>
3548         <dt>CUPS_PRINTER_DELETE <span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span></dt>
3549         <dd class="description">Delete printer
3550 </dd>
3551         <dt>CUPS_PRINTER_DUPLEX </dt>
3552         <dd class="description">Can do duplexing</dd>
3553         <dt>CUPS_PRINTER_FAX </dt>
3554         <dd class="description">Fax queue</dd>
3555         <dt>CUPS_PRINTER_LARGE </dt>
3556         <dd class="description">Can do D/E/A1/A0</dd>
3557         <dt>CUPS_PRINTER_LOCAL </dt>
3558         <dd class="description">Local printer or class</dd>
3559         <dt>CUPS_PRINTER_MEDIUM </dt>
3560         <dd class="description">Can do Tabloid/B/C/A3/A2</dd>
3561         <dt>CUPS_PRINTER_MFP <span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span></dt>
3562         <dd class="description">Printer with scanning capabilities
3563 </dd>
3564         <dt>CUPS_PRINTER_NOT_SHARED <span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span></dt>
3565         <dd class="description">Printer is not shared
3566 </dd>
3567         <dt>CUPS_PRINTER_PUNCH </dt>
3568         <dd class="description">Can punch output</dd>
3569         <dt>CUPS_PRINTER_REJECTING </dt>
3570         <dd class="description">Printer is rejecting jobs</dd>
3571         <dt>CUPS_PRINTER_REMOTE </dt>
3572         <dd class="description">Remote printer or class</dd>
3573         <dt>CUPS_PRINTER_SCANNER <span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span></dt>
3574         <dd class="description">Scanner-only device
3575 </dd>
3576         <dt>CUPS_PRINTER_SMALL </dt>
3577         <dd class="description">Can do Letter/Legal/A4</dd>
3578         <dt>CUPS_PRINTER_SORT </dt>
3579         <dd class="description">Can sort output</dd>
3580         <dt>CUPS_PRINTER_STAPLE </dt>
3581         <dd class="description">Can staple output</dd>
3582         <dt>CUPS_PRINTER_VARIABLE </dt>
3583         <dd class="description">Can do variable sizes</dd>
3584 </dl>
3585     </div>
3586   </body>
3587 </html>