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