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