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