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