doc/help/api-cups.html

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