doc/help/spec-ipp.html

   1 <!DOCTYPE HTML>
   2 <html>
   3 <!-- SECTION: Specifications -->
   4 <head>
   5         <title>CUPS Implementation of IPP</title>
   6         <meta name='keywords' content='Programming, Internet Printing Protocol'>
   7         <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
   8 </head>
   9 <body>
  10 <!--
  11   IPP specification for CUPS.
  12
  13   Copyright © 2007-2023 by Apple Inc.
  14   Copyright © 1997-2007 by Easy Software Products.
  15
  16   Licensed under Apache License v2.0.  See the file "LICENSE" for more
  17   information.
  18 -->
  19
  20 <H1 CLASS="title">CUPS Implementation of IPP</H1>
  21
  22 <h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
  23
  24 <p>CUPS implements <a href="http://ftp.pwg.org/pub/pwg/standards/std-ipp20-20151030-5100.12.pdf">IPP/2.1</a> and the operations and attributes defined in the following specifications:</p>
  25
  26 <ul>
  27
  28         <li><a href="http://ftp.pwg.org/pub/pwg/candidates/cs-ippjobprinterext10-20101030-5100.11.pdf">PWG 5100.11: IPP Job and Printer Extensions - Set 2 (JPS2)</a> (all operations plus the "job-creation-attributes-supported", "job-ids", "job-password", "job-password-encryption", "media-col-database", and "which-jobs" attributes)</li>
  29
  30         <li><a href="http://ftp.pwg.org/pub/pwg/candidates/cs-ippjobprinterext3v10-20120727-5100.13.pdf">PWG 5100.13: IPP Job and Printer Extensions - Set 3 (JPS3)</a> (all operations/attributes required for IPP Everywhere except "printer-geo-location" and "printer-icc-profiles")</li>
  31
  32         <li><a href="http://ftp.pwg.org/pub/pwg/candidates/cs-ippeve10-20130128-5100.14.pdf">PWG 5100.14: IPP Everywhere</a> (conforming to the Client and most of the Printer requirements)</li>
  33
  34         <li><a href="http://ftp.pwg.org/pub/pwg/candidates/cs-ippfaxout10-20140618-5100.15.pdf">PWG 5100.15: IPP FaxOut Service</a> (for facsimile queues)</li>
  35
  36         <li><a href="http://ftp.pwg.org/pub/pwg/candidates/cs-ipptrans10-20131108-5100.16.pdf">PWG 5100.16: IPP Transaction-Based Printing Extensions</a></li>
  37
  38         <li><a href="http://tools.ietf.org/html/rfc3995">RFC 3995: IPP: Event Notifications and Subscriptions</a></li>
  39
  40         <li><a href="http://tools.ietf.org/html/rfc3996">RFC 3996: IPP: The 'ippget' Delivery Method for Event Notifications</li>
  41
  42         <li><a href="http://tools.ietf.org/html/rfc3998">RFC 3998: IPP: Job and Printer Administrative Operations</a> (Disable-Printer, Enable-Printer, Hold-New-Jobs, and Release-Held-New-Jobs operations)</li>
  43
  44         <li><a href="http://tools.ietf.org/html/rfc7472">RFC 7472: IPP over HTTPS Transport Binding and 'ipps' URI Scheme</a></li>
  45
  46 </ul>
  47
  48 <p>CUPS also provides 17 new operations and many new attributes to support multiple IPP printers and printer classes on a single host.</p>
  49
  50 <h3 class='title'><a name='IPP_URIS'>IPP URIs</a></h3>
  51
  52 <p>CUPS supports the "http", "https", "ipp", and "ipps" schemes. The following resource names are used:</p>
  53
  54 <dl>
  55
  56         <dt><tt>scheme://hostname:port/</tt></dt>
  57
  58         <dd>Can be used for all "get" operations and for server subscriptions.</dd>
  59
  60         <dt><tt>scheme://hostname:port/admin/</tt></dt>
  61
  62         <dd>Used for all administrative operations.</dd>
  63
  64         <dt><tt>scheme://hostname:port/classes/name</tt></dt>
  65
  66         <dd>Specifies a printer class.</dd>
  67
  68         <dt><tt>scheme://hostname:port/jobs/id</tt></dt>
  69
  70         <dd>Specifies a job.</dd>
  71
  72         <dt><tt>scheme://hostname:port/printers/name</tt></dt>
  73
  74         <dd>Specifies a printer.</dd>
  75
  76 </dl>
  77
  78 <p>So a typical printer URI would be "ipp://foo.example.com/printers/LaserJet". In addition, the CUPS scheduler also supports (when enabled) normal browser access via "http://foo.example.com:port/" and "https://foo.example.com:port/".</p>
  79
  80 <h3 class='title'><a name='IPP_OPERATIONS'>CUPS IPP Operations</a></h3>
  81
  82 <p>CUPS provides 17 vendor extension operations in addition to most of the standard IPP and registered extension operations:</p>
  83
  84 <div class='table'><table align='center' border='1' width='80%'
  85 summary='Supported Operations'>
  86 <thead>
  87 <tr>
  88         <TH VALIGN="TOP">Operation Name</th>
  89         <TH VALIGN="TOP">CUPS</th>
  90         <TH VALIGN="TOP">Code</th>
  91         <TH VALIGN="TOP">Brief Description</th>
  92 </tr>
  93 </thead>
  94 <tbody>
  95 <tr>
  96         <td>Print-Job</td>
  97         <td>1.0</td>
  98         <td>0x0002</td>
  99         <td>Print a file.</td>
 100 </tr>
 101 <tr>
 102         <td>Validate-Job</td>
 103         <td>1.0</td>
 104         <td>0x0004</td>
 105         <td>Validate job attributes.</td>
 106 </tr>
 107 <tr>
 108         <td>Create-Job</td>
 109         <td>1.1</td>
 110         <td>0x0005</td>
 111         <td>Create a print job.</td>
 112 </tr>
 113 <tr>
 114         <td>Send-Document</td>
 115         <td>1.1</td>
 116         <td>0x0006</td>
 117         <td>Send a file for a print job.</td>
 118 </tr>
 119 <tr>
 120         <td><a href='#CANCEL_JOB'>Cancel-Job</a></td>
 121         <td>1.0</td>
 122         <td>0x0008</td>
 123         <td>Cancel a print job.</td>
 124 </tr>
 125 <tr>
 126         <td>Get-Job-Attributes</td>
 127         <td>1.0</td>
 128         <td>0x0009</td>
 129         <td>Get job attributes.</td>
 130 </tr>
 131 <tr>
 132         <td>Get-Jobs</td>
 133         <td>1.0</td>
 134         <td>0x000A</td>
 135         <td>Get all jobs.</td>
 136 </tr>
 137 <tr>
 138         <td>Get-Printer-Attributes</td>
 139         <td>1.0</td>
 140         <td>0x000B</td>
 141         <td>Get printer attributes.</td>
 142 </tr>
 143 <tr>
 144         <td>Hold-Job</td>
 145         <td>1.1</td>
 146         <td>0x000C</td>
 147         <td>Hold a job for printing.</td>
 148 </tr>
 149 <tr>
 150         <td>Release-Job</td>
 151         <td>1.1</td>
 152         <td>0x000D</td>
 153         <td>Release a job for printing.</td>
 154 </tr>
 155 <tr>
 156         <td>Restart-Job</td>
 157         <td>1.1</td>
 158         <td>0x000E</td>
 159         <td>Restarts a print job.</td>
 160 </tr>
 161 <tr>
 162         <td>Pause-Printer</td>
 163         <td>1.0</td>
 164         <td>0x0010</td>
 165         <td>Pause printing on a printer.</td>
 166 </tr>
 167 <tr>
 168         <td>Resume-Printer</td>
 169         <td>1.0</td>
 170         <td>0x0011</td>
 171         <td>Resume printing on a printer.</td>
 172 </tr>
 173 <tr>
 174         <td><a href='#PURGE_JOBS'>Purge-Jobs</a></td>
 175         <td>1.0</td>
 176         <td>0x0012</td>
 177         <td>Purge all jobs.</td>
 178 </tr>
 179 <tr>
 180         <td>Set-Printer-Attributes</td>
 181         <td>1.4</td>
 182         <td>0x0013</td>
 183         <td>Set attributes for a printer.</td>
 184 </tr>
 185 <tr>
 186         <td>Set-Job-Attributes</td>
 187         <td>1.1</td>
 188         <td>0x0014</td>
 189         <td>Set attributes for a pending or held job.</td>
 190 </tr>
 191 <tr>
 192         <td><a href='#CREATE_PRINTER_SUBSCRIPTION'>Create-Printer-Subscription</a></td>
 193         <td>1.2</td>
 194         <td>0x0016</td>
 195         <td>Creates a subscription associated with a printer or the server.</td>
 196 </tr>
 197 <tr>
 198         <td>Create-Job-Subscription</td>
 199         <td>1.2</td>
 200         <td>0x0017</td>
 201         <td>Creates a subscription associated with a job.</td>
 202 </tr>
 203 <tr>
 204         <td>Get-Subscription-Attributes</td>
 205         <td>1.2</td>
 206         <td>0x0018</td>
 207         <td>Gets the attributes for a subscription.</td>
 208 </tr>
 209 <tr>
 210         <td>Get-Subscriptions</td>
 211         <td>1.2</td>
 212         <td>0x0019</td>
 213         <td>Gets the attributes for zero or more subscriptions.</td>
 214 </tr>
 215 <tr>
 216         <td>Renew-Subscription</td>
 217         <td>1.2</td>
 218         <td>0x001A</td>
 219         <td>Renews a subscription.</td>
 220 </tr>
 221 <tr>
 222         <td>Cancel-Subscription</td>
 223         <td>1.2</td>
 224         <td>0x001B</td>
 225         <td>Cancels a subscription.</td>
 226 </tr>
 227 <tr>
 228         <td>Get-Notifications</td>
 229         <td>1.2</td>
 230         <td>0x001C</td>
 231         <td>Get notification events for <tt>ippget</tt> subscriptions.</td>
 232 </tr>
 233 <tr>
 234         <td>Enable-Printer</td>
 235         <td>1.2</td>
 236         <td>0x0022</td>
 237         <td>Accepts jobs on a printer.</td>
 238 </tr>
 239 <tr>
 240         <td>Disable-Printer</td>
 241         <td>1.2</td>
 242         <td>0x0023</td>
 243         <td>Rejects jobs on a printer.</td>
 244 </tr>
 245 <tr>
 246         <td>Hold-New-Jobs</td>
 247         <td>1.4</td>
 248         <td>0x0025</td>
 249         <td>Hold new jobs by default.</td>
 250 </tr>
 251 <tr>
 252         <td>Release-Held-New-Jobs</td>
 253         <td>1.4</td>
 254         <td>0x0026</td>
 255         <td>Releases all jobs that were previously held.</td>
 256 </tr>
 257 <tr>
 258         <td>Cancel-Jobs</td>
 259         <td>1.5</td>
 260         <td>0x0038</td>
 261         <td>Cancel all jobs (administrator).</td>
 262 </tr>
 263 <tr>
 264         <td>Cancel-My-Jobs</td>
 265         <td>1.5</td>
 266         <td>0x0039</td>
 267         <td>Cancel all jobs (user).</td>
 268 </tr>
 269 <tr>
 270         <td>Close-Job</td>
 271         <td>1.5</td>
 272         <td>0x003b</td>
 273         <td>Close a created job.</td>
 274 </tr>
 275 <tr>
 276         <td><a href='#CUPS_GET_DEFAULT'>CUPS-Get-Default</a></td>
 277         <td>1.0</td>
 278         <td>0x4001</td>
 279         <td>Get the default destination.</td>
 280 </tr>
 281 <tr>
 282         <td><a href='#CUPS_GET_PRINTERS'>CUPS-Get-Printers</a></td>
 283         <td>1.0</td>
 284         <td>0x4002</td>
 285         <td>Get all of the available printers.</td>
 286 </tr>
 287 <tr>
 288         <td><a href='#CUPS_ADD_MODIFY_PRINTER'>CUPS-Add-Modify-Printer</a></td>
 289         <td>1.0</td>
 290         <td>0x4003</td>
 291         <td>Add or modify a printer.</td>
 292 </tr>
 293 <tr>
 294         <td><a href='#CUPS_DELETE_PRINTER'>CUPS-Delete-Printer</a></td>
 295         <td>1.0</td>
 296         <td>0x4004</td>
 297         <td>Delete a printer.</td>
 298 </tr>
 299 <tr>
 300         <td><a href='#CUPS_GET_CLASSES'>CUPS-Get-Classes</a></td>
 301         <td>1.0</td>
 302         <td>0x4005</td>
 303         <td>Get all of the available printer classes.</td>
 304 </tr>
 305 <tr>
 306         <td><a href='#CUPS_ADD_MODIFY_CLASS'>CUPS-Add-Modify-Class</a></td>
 307         <td>1.0</td>
 308         <td>0x4006</td>
 309         <td>Add or modify a printer class.</td>
 310 </tr>
 311 <tr>
 312         <td><a href='#CUPS_DELETE_CLASS'>CUPS-Delete-Class</a></td>
 313         <td>1.0</td>
 314         <td>0x4007</td>
 315         <td>Delete a printer class.</td>
 316 </tr>
 317 <tr>
 318         <td>CUPS-Accept-Jobs</td>
 319         <td>1.0</td>
 320         <td>0x4008</td>
 321         <td>Accept jobs on a printer or printer class. This operation is deprecated - use the Enable-Printer operation instead.</td>
 322 </tr>
 323 <tr>
 324         <td>CUPS-Reject-Jobs</td>
 325         <td>1.0</td>
 326         <td>0x4009</td>
 327         <td>Reject jobs on a printer or printer class. This operation is deprecated - use the Disable-Printer operation instead.</td>
 328 </tr>
 329 <tr>
 330         <td><a href='#CUPS_SET_DEFAULT'>CUPS-Set-Default</a></td>
 331         <td>1.0</td>
 332         <td>0x400A</td>
 333         <td>Set the default destination.</td>
 334 </tr>
 335 <tr>
 336         <td><a href='#CUPS_GET_DEVICES'>CUPS-Get-Devices</a></td>
 337         <td>1.1</td>
 338         <td>0x400B</td>
 339         <td>Get all of the available devices.</td>
 340 </tr>
 341 <tr>
 342         <td><a href='#CUPS_GET_PPDS'>CUPS-Get-PPDs</a></td>
 343         <td>1.1</td>
 344         <td>0x400C</td>
 345         <td>Get all of the available PPDs.</td>
 346 </tr>
 347 <tr>
 348         <td><a href='#CUPS_MOVE_JOB'>CUPS-Move-Job</a></td>
 349         <td>1.1</td>
 350         <td>0x400D</td>
 351         <td>Move a job to a different printer.</td>
 352 </tr>
 353 <tr>
 354         <td><a href='#CUPS_AUTHENTICATE_JOB'>CUPS-Authenticate-Job</a></td>
 355         <td>1.2</td>
 356         <td>0x400E</td>
 357         <td>Authenticate a job for printing.</td>
 358 </tr>
 359 <tr>
 360         <td><a href='#CUPS_GET_PPD'>CUPS-Get-PPD</a></td>
 361         <td>1.3</td>
 362         <td>0x400F</td>
 363         <td>Get a PPD file.</td>
 364 </tr>
 365 <tr>
 366         <td><a href='#CUPS_GET_DOCUMENT'>CUPS-Get-Document</a></td>
 367         <td>1.4</td>
 368         <td>0x4027</td>
 369         <td>Get a document file from a job.</td>
 370 </tr>
 371 <tr>
 372         <td><a href='#CUPS_CREATE_LOCAL_PRINTER'>CUPS-Create-Local-Printer</a></td>
 373         <td>2.2</td>
 374         <td>0x4028</td>
 375         <td>Creates a local (temporary) print queue pointing to a remote IPP Everywhere printer.</td>
 376 </tr>
 377 </tbody>
 378 </table></div>
 379
 380 <h2 class='title'><a name='OPERATIONS'>Operations</a></h2>
 381
 382 <p>The following sections describe the operations supported by CUPS. In the interest of brevity, operations which use only the standard IPP attributes are not described.
 383
 384
 385 <h3 class='title'><a name='CANCEL_JOB'>Cancel Job Operation (Extension)</a></h3>
 386
 387 <p>The Cancel-Job operation (0x0008) cancels the specified job. CUPS 1.4 added support for the <tt>purge-job (boolean)</tt> operation attribute that (if 'true') removes all history and document files for the job as well.</p>
 388
 389
 390 <h3 class='title'><a name='PURGE_JOBS'>Purge-Jobs Operation</a></h3>
 391
 392 <p>The Purge-Jobs operation (0x0012) cancels all of the jobs on a given destination and optionally removes all history and document files for the jobs as well. CUPS 1.2 added support for the <tt>purge-job (boolean)</tt> operation attribute that (if 'false') retains all history and document files for the canceled jobs.</p>
 393
 394 <blockquote><b>Note:</b>
 395         <p>The Cancel-Jobs and Cancel-My-Jobs operations should be used instead of Purge-Jobs.</p>
 396 </blockquote>
 397
 398
 399
 400 <h3 class='title'><span class='info'>CUPS 1.2/macOS 10.5</span><a
 401 name='CREATE_PRINTER_SUBSCRIPTION'>Create-Printer-Subscription</a></h3>
 402
 403 <p>The Create-Printer-Subscription operation (0x0016) creates a subscription for printer or server event notifications. CUPS provides several additional events in addition to the standard events in the IPP notifications specification. CUPS adds the following <tt>notify-events (1setOf type2 keyword)</tt> values:<p>
 404
 405 <ul>
 406
 407         <li><tt>printer-added</tt> - Get notified whenever a printer or class is added</li>
 408
 409         <li><tt>printer-deleted</tt> - Get notified whenever a printer or class is deleted</li>
 410
 411         <li><tt>printer-modified</tt> - Get notified whenever a printer or class is modified</li>
 412
 413         <li><tt>server-audit</tt> - Get notified when a security condition occurs</li>
 414
 415         <li><tt>server-restarted</tt> - Get notified when the server is restarted</li>
 416
 417         <li><tt>server-started</tt> - Get notified when the server is started</li>
 418
 419         <li><tt>server-stopped</tt> - Get notified when the server is stopped</li>
 420
 421 </ul>
 422
 423
 424 <h3 class='title'><a name='CUPS_GET_DEFAULT'>CUPS-Get-Default Operation</a></h3>
 425
 426 <p>The CUPS-Get-Default operation (0x4001) returns the default printer URI and attributes.
 427
 428 <h4>CUPS-Get-Default Request</h4>
 429
 430 <p>The following groups of attributes are supplied as part of the CUPS-Get-Default request:
 431
 432 <p>Group 1: Operation Attributes
 433
 434 <dl>
 435
 436         <dt>Natural Language and Character Set:
 437
 438         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
 439
 440         <dt>"requested-attributes" (1setOf keyword):
 441
 442         <dd>The client OPTIONALLY supplies a set of attribute names and/or attribute group names in whose values the requester is interested. If the client omits this attribute, the server responds as if this attribute had been supplied with a value of 'all'.
 443
 444 </dl>
 445
 446 <h4>CUPS-Get-Default Response</h4>
 447
 448 <p>The following groups of attributes are send as part of the CUPS-Get-Default Response:
 449
 450 <p>Group 1: Operation Attributes
 451
 452 <dl>
 453
 454         <dt>Natural Language and Character Set:
 455
 456         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
 457
 458         <dt>Status Message:
 459
 460         <dd>The standard response status message.
 461
 462 </dl>
 463
 464 <p>Group 2: Printer Object Attributes
 465
 466 <dl>
 467
 468         <dt>The set of requested attributes and their current values.
 469
 470 </dl>
 471
 472 <h3 class='title'><a name='CUPS_GET_PRINTERS'>CUPS-Get-Printers Operation</a></h3>
 473
 474 <p>The CUPS-Get-Printers operation (0x4002) returns the printer attributes for every printer known to the system. This may include printers that are not served directly by the server.
 475
 476 <h4>CUPS-Get-Printers Request</h4>
 477
 478 <p>The following groups of attributes are supplied as part of the CUPS-Get-Printers request:
 479
 480 <p>Group 1: Operation Attributes
 481
 482 <dl>
 483
 484         <dt>Natural Language and Character Set:
 485
 486         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
 487
 488         <dt>"first-printer-name" (name(127)): <span class='info'>CUPS 1.2/macOS 10.5</span>
 489
 490         <dd>The client OPTIONALLY supplies this attribute to select the first printer that is returned.
 491
 492         <dt>"limit" (integer (1:MAX)):
 493
 494         <dd>The client OPTIONALLY supplies this attribute limiting the number of printers that are returned.
 495
 496         <dt>"printer-id" (integer(0:65535)): <span class='info'>CUPS 2.2</span>
 497
 498         <dd>The client OPTIONALLY supplies this attribute to select which printer is returned.
 499
 500         <dt>"printer-location" (text(127)): <span class='info'>CUPS 1.1.7</span>
 501
 502         <dd>The client OPTIONALLY supplies this attribute to select which printers are returned.
 503
 504         <dt>"printer-type" (type2 enum): <span class='info'>CUPS 1.1.7</span>
 505
 506         <dd>The client OPTIONALLY supplies a printer type enumeration to select which printers are returned.
 507
 508         <dt>"printer-type-mask" (type2 enum): <span class='info'>CUPS 1.1.7</span>
 509
 510         <dd>The client OPTIONALLY supplies a printer type mask enumeration to select which bits are used in the "printer-type" attribute.
 511
 512         <dt>"requested-attributes" (1setOf keyword):
 513
 514         <dd>The client OPTIONALLY supplies a set of attribute names and/or attribute group names in whose values the requester is interested. If the client omits this attribute, the server responds as if this attribute had been supplied with a value of 'all'.
 515
 516         <dt>"requested-user-name" (name(127)): <span class='info'>CUPS 1.2/macOS 10.5</span>
 517
 518         <dd>The client OPTIONALLY supplies a user name that is used to filter the returned printers.
 519
 520 </dl>
 521
 522 <h4>CUPS-Get-Printers Response</h4>
 523
 524 <p>The following groups of attributes are send as part of the CUPS-Get-Printers Response:
 525
 526 <p>Group 1: Operation Attributes
 527
 528 <dl>
 529
 530         <dt>Natural Language and Character Set:
 531
 532         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
 533
 534         <dt>Status Message:
 535
 536         <dd>The standard response status message.
 537
 538 </dl>
 539
 540 <p>Group 2: Printer Object Attributes
 541
 542 <dl>
 543
 544         <dt>The set of requested attributes and their current values for each printer.
 545
 546 </dl>
 547
 548
 549 <h3 class='title'><a name='CUPS_ADD_MODIFY_PRINTER'>CUPS-Add-Modify-Printer Operation</a></h3>
 550
 551 <p>The CUPS-Add-Modify-Printer operation (0x4003) adds a new printer or modifies an existing printer on the system.
 552
 553 <h4>CUPS-Add-Modify-Printer Request</h4>
 554
 555 <p>The following groups of attributes are supplied as part of the CUPS-Add-Modify-Printer request:
 556
 557 <p>Group 1: Operation Attributes
 558
 559 <dl>
 560
 561         <dt>Natural Language and Character Set:
 562
 563         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
 564
 565         <dt>"printer-uri" (uri):
 566
 567         <dd>The client MUST supply a URI for the specified printer.
 568
 569 </dl>
 570
 571 <p>Group 2: Printer Object Attributes
 572
 573 <dl>
 574
 575         <dt>"auth-info-required" (1setOf type2 keyword): <span class='info'>CUPS 1.3/macOS 10.5</span>
 576
 577         <dd>The client OPTIONALLY supplies one or more authentication keywords that are required to communicate with the printer/remote queue.
 578
 579         <dt>"job-sheets-default" (1setOf name(127)): <span class='info'>CUPS 1.1.7</span>
 580
 581         <dd>The client OPTIONALLY supplies one or two banner page names that are printed before and after files in a job. The reserved name "none" is used to specify that no banner page should be printed.
 582
 583         <dt>"device-uri" (uri):
 584
 585         <dd>The client OPTIONALLY supplies a device URI for the specified printer.
 586
 587         <dt>"port-monitor" (name(127)):
 588
 589         <dd>The client OPTIONALLY supplies a port monitor name for the specified printer.
 590
 591         <dt>"ppd-name" (name(255)):
 592
 593         <dd>The client OPTIONALLY supplies a PPD name for the specified printer.
 594
 595         <dt>"printer-is-accepting-jobs" (boolean):
 596
 597         <dd>The client OPTIONALLY supplies this boolean attribute indicating whether the printer object should accept new jobs.
 598
 599         <dt>"printer-info" (text(127)):
 600
 601         <dd>The client OPTIONALLY supplies this attribute indicating the printer information string.
 602
 603         <dt>"printer-location" (text(127)):
 604
 605         <dd>The client OPTIONALLY supplies this attribute indicating a textual location of the printer.
 606
 607         <dt>"printer-more-info" (uri):
 608
 609         <dd>The client OPTIONALLY supplies this attribute indicating a URI for additional printer information.
 610
 611         <dt>"printer-state" (type2 enum):
 612
 613         <dd>The client OPTIONALLY supplies this attribute indicating the initial/current state of the printer. Only the 'idle(3)' and 'stopped(5)' enumerations are recognized.
 614
 615         <dt>"printer-state-message" (text(MAX)):
 616
 617         <dd>The client OPTIONALLY supplies this attribute indicating a textual reason for the current printer state.
 618
 619         <dt>"requesting-user-name-allowed" (1setof name(127) | delete)
 620         <br><i>OR</i>
 621         <br>"requesting-user-name-denied" (1setof name(127) | delete):
 622
 623         <dd>The client OPTIONALLY supplies one of these attributes to specify an access control list for incoming print jobs. To allow all users access to a printer, use the delete tag for the attribute value.
 624
 625 </dl>
 626
 627 <p>The CUPS-Add-Modify-Printer request can optionally be followed by a PPD file to be used for the printer. The "ppd-name" attribute overrides any file that is attached to the end of the request with a local CUPS PPD file.
 628
 629 <h4>CUPS-Add-Modify-Printer Response</h4>
 630
 631 <p>The following groups of attributes are send as part of the
 632 CUPS-Add-Modify-Printer Response:
 633
 634 <p>Group 1: Operation Attributes
 635
 636 <dl>
 637
 638         <dt>Natural Language and Character Set:
 639
 640         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
 641
 642         <dt>Status Message:
 643
 644         <dd>The standard response status message.
 645
 646 </dl>
 647
 648
 649 <h3 class='title'><a name='CUPS_DELETE_PRINTER'>CUPS-Delete-Printer Operation</a></h3>
 650
 651 <p>The CUPS-Delete-Printer operation (0x4004) removes an existing printer from the system.
 652
 653 <h4>CUPS-Delete-Printer Request</h4>
 654
 655 <p>The following groups of attributes are supplied as part of the CUPS-Delete-Printer request:
 656
 657 <p>Group 1: Operation Attributes
 658
 659 <dl>
 660
 661         <dt>Natural Language and Character Set:
 662
 663         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
 664
 665         <dt>"printer-uri" (uri):
 666
 667         <dd>The client MUST supply a URI for the specified printer.
 668
 669 </dl>
 670
 671 <h4>CUPS-Delete-Printer Response</h4>
 672
 673 <p>The following groups of attributes are send as part of the CUPS-Delete-Printer Response:
 674
 675 <p>Group 1: Operation Attributes
 676
 677 <dl>
 678
 679         <dt>Natural Language and Character Set:
 680
 681         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
 682
 683         <dt>Status Message:
 684
 685         <dd>The standard response status message.
 686
 687 </dl>
 688
 689
 690 <h3 class='title'><a name='CUPS_GET_CLASSES'>CUPS-Get-Classes Operation</a></h3>
 691
 692 <p>The CUPS-Get-Classes operation (0x4005) returns the printer attributes for every printer class known to the system. This may include printer classes that are not served directly by the server.
 693
 694 <h4>CUPS-Get-Classes Request</h4>
 695
 696 <p>The following groups of attributes are supplied as part of the CUPS-Get-Classes request:
 697
 698 <p>Group 1: Operation Attributes
 699
 700 <dl>
 701
 702         <dt>Natural Language and Character Set:
 703
 704         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
 705
 706         <dt>"first-printer-name" (name(127)): <span class='info'>CUPS 1.2/macOS 10.5</span>
 707
 708         <dd>The client OPTIONALLY supplies this attribute to select the first printer that is returned.
 709
 710         <dt>"limit" (integer (1:MAX)):
 711
 712         <dd>The client OPTIONALLY supplies this attribute limiting the number of printer classes that are returned.
 713
 714         <dt>"printer-location" (text(127)): <span class='info'>CUPS 1.1.7</span>
 715
 716         <dd>The client OPTIONALLY supplies this attribute to select which printer classes are returned.
 717
 718         <dt>"printer-type" (type2 enum): <span class='info'>CUPS 1.1.7</span>
 719
 720         <dd>The client OPTIONALLY supplies a printer type enumeration to select which printer classes are returned.
 721
 722         <dt>"printer-type-mask" (type2 enum): <span class='info'>CUPS 1.1.7</span>
 723
 724         <dd>The client OPTIONALLY supplies a printer type mask enumeration to select which bits are used in the "printer-type" attribute.
 725
 726         <dt>"requested-attributes" (1setOf keyword):
 727
 728         <dd>The client OPTIONALLY supplies a set of attribute names and/or attribute group names in whose values the requester is interested. If the client omits this attribute, the server responds as if this attribute had been supplied with a value of 'all'.
 729
 730         <dt>"requested-user-name" (name(127)): <span class='info'>CUPS 1.2/macOS 10.5</span>
 731
 732         <dd>The client OPTIONALLY supplies a user name that is used to filter the returned printers.
 733
 734 </dl>
 735
 736 <h4>CUPS-Get-Classes Response</h4>
 737
 738 <p>The following groups of attributes are send as part of the CUPS-Get-Classes Response:
 739
 740 <p>Group 1: Operation Attributes
 741
 742 <dl>
 743
 744         <dt>Natural Language and Character Set:
 745
 746         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
 747
 748         <dt>Status Message:
 749
 750         <dd>The standard response status message.
 751
 752 </dl>
 753
 754 <p>Group 2: Printer Class Object Attributes
 755
 756 <dl>
 757
 758         <dt>The set of requested attributes and their current values for each printer class.
 759
 760 </dl>
 761
 762 <h3 class='title'><a name='CUPS_ADD_MODIFY_CLASS'>CUPS-Add-Modify-Class Operation</a></h3>
 763
 764 <p>The CUPS-Add-Modify-Class operation (0x4006) adds a new printer class or modifies and existing printer class on the system.
 765
 766 <h4>CUPS-Add-Modify-Class Request</h4>
 767
 768 <p>The following groups of attributes are supplied as part of the CUPS-Add-Modify-Class request:
 769
 770 <p>Group 1: Operation Attributes
 771
 772 <dl>
 773
 774         <dt>Natural Language and Character Set:
 775
 776         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
 777
 778         <dt>"printer-uri" (uri):
 779
 780         <dd>The client MUST supply a URI for the specified printer class.
 781
 782 </dl>
 783
 784 <p>Group 2: Printer Object Attributes
 785
 786 <dl>
 787
 788         <dt>"auth-info-required" (1setOf type2 keyword): <span class='info'>CUPS 1.3/macOS 10.5</span>
 789
 790         <dd>The client OPTIONALLY supplies one or more authentication keywords that are required to communicate with the printer/remote queue.
 791
 792         <dt>"member-uris" (1setof uri):
 793
 794         <dd>The client OPTIONALLY supplies the "member-uris" set specifying the printers and printer classes that are part of the class.
 795
 796         <dt>"printer-is-accepting-jobs" (boolean):
 797
 798         <dd>The client OPTIONALLY supplies this boolean attribute indicating whether the class object should accept new jobs.
 799
 800         <dt>"printer-info" (text(127)):
 801
 802         <dd>The client OPTIONALLY supplies this attribute indicating the printer information string.
 803
 804         <dt>"printer-location" (text(127)):
 805
 806         <dd>The client OPTIONALLY supplies this attribute indicating a textual location of the class.
 807
 808         <dt>"printer-more-info" (uri):
 809
 810         <dd>The client OPTIONALLY supplies this attribute indicating a URI for additional class information.
 811
 812         <dt>"printer-state" (type2 enum):
 813
 814         <dd>The client OPTIONALLY supplies this attribute indicating the initial/current state of the class. Only the 'idle(3)' and 'stopped(5)' enumerations are recognized.
 815
 816         <dt>"printer-state-message" (text(MAX)):
 817
 818         <dd>The client OPTIONALLY supplies this attribute indicating a textual reason for the current class state.
 819
 820         <dt>"requesting-user-name-allowed" (1setof name(127))
 821         <br><i>OR</i>
 822         <br>"requesting-user-name-denied" (1setof name(127)):
 823
 824         <dd>The client OPTIONALLY supplies one of these attributes to specify an access control list for incoming print jobs. To allow all users access to a class, use the delete tag for the attribute value.
 825
 826 </dl>
 827
 828 <h4>CUPS-Add-Modify-Class Response</h4>
 829
 830 <p>The following groups of attributes are send as part of the CUPS-Add-Modify-Class Response:
 831
 832 <p>Group 1: Operation Attributes
 833
 834 <dl>
 835
 836         <dt>Natural Language and Character Set:
 837
 838         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
 839
 840         <dt>Status Message:
 841
 842         <dd>The standard response status message.
 843
 844 </dl>
 845
 846
 847 <h3 class='title'><a name='CUPS_DELETE_CLASS'>CUPS-Delete-Class Operation</a></h3>
 848
 849 <p>The CUPS-Delete-Class operation (0x4007) removes an existing printer class from the system.
 850
 851 <h4>CUPS-Delete-Class Request</h4>
 852
 853 <p>The following groups of attributes are supplied as part of the CUPS-Delete-Class request:
 854
 855 <p>Group 1: Operation Attributes
 856
 857 <dl>
 858
 859         <dt>Natural Language and Character Set:
 860
 861         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
 862
 863         <dt>"printer-uri" (uri):
 864
 865         <dd>The client MUST supply a URI for the specified printer class.
 866
 867 </dl>
 868
 869 <h4>CUPS-Delete-Class Response</h4>
 870
 871 <p>The following groups of attributes are send as part of the CUPS-Delete-Class Response:
 872
 873 <p>Group 1: Operation Attributes
 874
 875 <dl>
 876
 877         <dt>Natural Language and Character Set:
 878
 879         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
 880
 881         <dt>Status Message:
 882
 883         <dd>The standard response status message.
 884
 885 </dl>
 886
 887
 888 <h3 class='title'><a name='CUPS_SET_DEFAULT'>CUPS-Set-Default Operation</a></h3>
 889
 890 <p>The CUPS-Set-Default operation (0x400A) sets the default printer destination for all clients when a resource name of "/printers" is specified.
 891
 892 <h4>CUPS-Set-Default Request</h4>
 893
 894 <p>The following groups of attributes are supplied as part of the CUPS-Set-Default request:
 895
 896 <p>Group 1: Operation Attributes
 897
 898 <dl>
 899
 900         <dt>Natural Language and Character Set:
 901
 902         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
 903
 904         <dt>"printer-uri" (uri):
 905
 906         <dd>The client MUST supply a URI for the specified printer or printer class.
 907
 908 </dl>
 909
 910 <h4>CUPS-Set-Default Response</h4>
 911
 912 <p>The following groups of attributes are send as part of the CUPS-Set-Default Response:
 913
 914 <p>Group 1: Operation Attributes
 915
 916 <dl>
 917
 918         <dt>Natural Language and Character Set:
 919
 920         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
 921
 922         <dt>Status Message:
 923
 924         <dd>The standard response status message.
 925
 926 </dl>
 927
 928
 929 <h3 class='title'><span class='info'>Deprecated</span><a name='CUPS_GET_DEVICES'>CUPS-Get-Devices Operation</a></h3>
 930
 931 <p>The CUPS-Get-Devices operation (0x400B) returns all of the supported device-uri's for the server.</p>
 932
 933 <h4>CUPS-Get-Devices Request</h4>
 934
 935 <p>The following groups of attributes are supplied as part of the CUPS-Get-Devices request:
 936
 937 <p>Group 1: Operation Attributes
 938
 939 <dl>
 940
 941         <dt>Natural Language and Character Set:
 942
 943         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
 944
 945         <dt>"device-class" (type1 keyword):
 946
 947         <dd>The client OPTIONALLY supplies a device class keyword to select which devices are returned.
 948
 949         <dt>"exclude-schemes" (1setOf name): <span class='info'>CUPS 1.4/macOS 10.6</span>
 950
 951         <dd>The client OPTIONALLY supplies a set of scheme names that the requestor does not want to discover. If the client omits this attribute, the server responds with devices of all schemes specified by the "include-schemes" attribute.
 952
 953         <dt>"include-schemes" (1setOf name): <span class='info'>CUPS 1.4/macOS 10.6</span>
 954
 955         <dd>The client OPTIONALLY supplies a set of scheme names that the requestor wants to discover. If the client omits this attribute, the server responds with devices of all schemes except those specified by the "exclude-schemes" attribute.
 956
 957         <dt>"limit" (integer (1:MAX)):
 958
 959         <dd>The client OPTIONALLY supplies this attribute limiting the number of devices that are returned.
 960
 961         <dt>"requested-attributes" (1setOf keyword):
 962
 963         <dd>The client OPTIONALLY supplies a set of attribute names and/or attribute group names in whose values the requester is interested. If the client omits this attribute, the server responds as if this attribute had been supplied with a value of 'all'.
 964
 965         <dt>"timeout" (integer (1:MAX)): <span class='info'>CUPS 1.4/macOS 10.6</span>
 966
 967         <dd>The client OPTIONALLY supplies this attribute to limit the duration of the lookup. The default timeout is 15 seconds.
 968
 969 </dl>
 970
 971 <h4>CUPS-Get-Devices Response</h4>
 972
 973 <p>The following groups of attributes are send as part of the CUPS-Get-Devices Response:
 974
 975 <p>Group 1: Operation Attributes
 976
 977 <dl>
 978
 979         <dt>Natural Language and Character Set:
 980
 981         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
 982
 983         <dt>Status Message:
 984
 985         <dd>The standard response status message.
 986
 987 </dl>
 988
 989 <p>Groups 2-N: Device Object Attributes (using printer-attributes-tag group)
 990
 991 <dl>
 992
 993         <dt>The set of requested attributes and their current values for
 994         each device.
 995
 996 </dl>
 997
 998
 999 <h3 class='title'><span class='info'>Deprecated</span><a name='CUPS_GET_PPDS'>CUPS-Get-PPDs Operation</a></h3>
1000
1001 <p>The CUPS-Get-PPDs operation (0x400C) returns all of the locally available PPD files on the system.</p>
1002
1003 <h4>CUPS-Get-PPDs Request</h4>
1004
1005 <p>The following groups of attributes are supplied as part of the CUPS-Get-PPDs request:
1006
1007 <p>Group 1: Operation Attributes
1008
1009 <dl>
1010
1011         <dt>Natural Language and Character Set:
1012
1013         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
1014
1015         <dt>"exclude-schemes" (1setOf name): <span class='info'>CUPS 1.4/macOS 10.6</span>
1016
1017         <dd>The client OPTIONALLY supplies a set of scheme names that the requestor does not want to list. If the client omits this attribute, the server responds with PPDs of all schemes specified by the "include-schemes" attribute.
1018
1019         <dt>"include-schemes" (1setOf name): <span class='info'>CUPS 1.4/macOS 10.6</span>
1020
1021         <dd>The client OPTIONALLY supplies a set of scheme names that the requestor wants to list. If the client omits this attribute, the server responds with PPDs of all schemes except those specified by the "exclude-schemes" attribute.
1022
1023         <dt>"limit" (integer (1:MAX)):
1024
1025         <dd>The client OPTIONALLY supplies this attribute limiting the number of PPDs that are returned.
1026
1027         <dt>"ppd-make" (text(127)):
1028
1029         <dd>The client OPTIONALLY supplies a printer manufacturer to select which PPDs are returned.
1030
1031         <dt>"ppd-make-and-model" (text(127)): <span class='info'>CUPS 1.3/macOS 10.5</span>
1032
1033         <dd>The client OPTIONALLY supplies a make and model to select which PPDs are returned.
1034
1035         <dt>"ppd-model-number" (integer): <span class='info'>CUPS 1.3/macOS 10.5</span>
1036
1037         <dd>The client OPTIONALLY supplies a model number to select which PPDs are returned.
1038
1039         <dt>"ppd-natural-language" (naturalLanguage): <span class='info'>CUPS 1.3/macOS 10.5</span>
1040
1041         <dd>The client OPTIONALLY supplies a language to select which PPDs are returned.
1042
1043         <dt>"ppd-product" (text(127)): <span class='info'>CUPS 1.3/macOS 10.5</span>
1044
1045         <dd>The client OPTIONALLY supplies a PostScript product string to select which PPDs are returned.
1046
1047         <dt>"ppd-psversion" (text(127)): <span class='info'>CUPS 1.3/macOS 10.5</span>
1048
1049         <dd>The client OPTIONALLY supplies a PostScript version string to select which PPDs are returned.
1050
1051         <dt>"ppd-type" (type1 keyword): <span class='info'>CUPS 1.3/macOS 10.5</span>
1052
1053         <dd>The client OPTIONALLY supplies a driver type to select which PPDs are returned.
1054
1055         <dt>"requested-attributes" (1setOf keyword):
1056
1057         <dd>The client OPTIONALLY supplies a set of attribute names and/or attribute group names in whose values the requester is interested. If the client omits this attribute, the server responds as if this attribute had been supplied with a value of 'all'. Specify "ppd-make" to get a list of manufacturers.
1058
1059 </dl>
1060
1061 <h4>CUPS-Get-PPDs Response</h4>
1062
1063 <p>The following groups of attributes are send as part of the
1064 CUPS-Get-PPDs Response:
1065
1066 <p>Group 1: Operation Attributes
1067
1068 <dl>
1069
1070         <dt>Natural Language and Character Set:
1071
1072         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
1073
1074         <dt>Status Message:
1075
1076         <dd>The standard response status message.
1077
1078 </dl>
1079
1080 <p>Groups 2-N: PPD Attributes (using printer-attributes-tag group)
1081
1082 <dl>
1083
1084         <dt>The set of requested attributes and their current values for each PPD file.
1085
1086 </dl>
1087
1088
1089 <h3 class='title'><span class='info'>CUPS 1.1</span><a name='CUPS_MOVE_JOB'>CUPS-Move-Job Operation</a></h3>
1090
1091 <p>The CUPS-Move-Job operation (0x400D) moves an active print job or all print jobs for a printer to a different printer.</p>
1092
1093 <h4>CUPS-Move-Job Request</h4>
1094
1095 <p>The following groups of attributes are supplied as part of the CUPS-Move-Job request:
1096
1097 <p>Group 1: Operation Attributes
1098
1099 <dl>
1100
1101         <dt>Natural Language and Character Set:
1102
1103         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
1104
1105         <dt>"printer-uri" (uri)
1106         <br><i>OR</i>
1107         <dt>"printer-uri" (uri) and "job-id" (integer)
1108         <br><i>OR</i>
1109         <br>"job-uri" (uri):
1110
1111         <dd>The client MUST supply a URI for the specified printer, the URI for the specified printer and a job ID number, or the job URI.
1112
1113 </dl>
1114
1115 <p>Group 2: Job Template Attributes
1116
1117 <dl>
1118
1119         <dt>"job-printer-uri" (uri):
1120
1121         <dd>The client MUST supply a URI for a printer on the same server.
1122
1123 </dl>
1124
1125 <h4>CUPS-Move-Job Response</h4>
1126
1127 <p>The following groups of attributes are send as part of the CUPS-Move-Job Response:
1128
1129 <p>Group 1: Operation Attributes
1130
1131 <dl>
1132
1133         <dt>Status Message:
1134
1135         <dd>The standard response status message.
1136
1137         <dt>Natural Language and Character Set:
1138
1139         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
1140
1141 </dl>
1142
1143 <h3 class='title'><span class='info'>CUPS 1.2/macOS 10.5</span><a name='CUPS_AUTHENTICATE_JOB'>CUPS-Authenticate-Job Operation</a></h3>
1144
1145 <p>The CUPS-Authenticate-Job operation (0x400E) authenticates a print job for printing, releasing the job if it is held. Typically this is used when printing to a remote server. The authentication information is passed in the HTTP request; the HTTP connection is normally encrypted for this type of request.</p>
1146
1147 <h4>CUPS-Authenticate-Job Request</h4>
1148
1149 <p>The following groups of attributes are supplied as part of the CUPS-Authenticate-Job request:
1150
1151 <p>Group 1: Operation Attributes
1152
1153 <dl>
1154
1155         <dt>Natural Language and Character Set:
1156
1157         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
1158
1159         <dt>"printer-uri" (uri) and "job-id" (integer)
1160         <br><i>OR</i>
1161         <br>"job-uri" (uri):
1162
1163         <dd>The client MUST supply a URI for the specified printer and a job ID number, or the job URI.
1164
1165 </dl>
1166
1167 <p>Group 2: Job Attributes
1168
1169 <dl>
1170
1171         <dt>"auth-info" (1setOf text(MAX)): <span class='info'>CUPS 1.3/macOS 10.5</span>
1172
1173         <dd>The client OPTIONALLY supplies one or more authentication values as specified by the "auth-info-required" attribute.
1174
1175         <dt>"job-hold-until" (keyword | name(MAX)): <span class='info'>CUPS 1.3/macOS 10.5</span>
1176
1177         <dd>The client OPTIONALLY supplies a new job-hold-until value for the job. If specified and not the "no-hold" value, the job is held instead of released for printing.
1178
1179 </dl>
1180
1181 <h4>CUPS-Authenticate-Job Response</h4>
1182
1183 <p>The following groups of attributes are send as part of the CUPS-Authenticate-Job Response:
1184
1185 <p>Group 1: Operation Attributes
1186
1187 <dl>
1188
1189         <dt>Natural Language and Character Set:
1190
1191         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
1192
1193         <dt>Status Message:
1194
1195         <dd>The standard response status message.
1196
1197 </dl>
1198
1199 <p>Group 2: Unsupported Attributes (status=client-eror-attributes-or-values-not-supported)
1200
1201 <dl>
1202
1203         <dt>auth-info-required (1setOf Type2 keyword)
1204
1205         <dd>The required authentication information.
1206
1207 </dl>
1208
1209
1210 <h3 class='title'><span class='info'>Deprecated</span><a name='CUPS_GET_PPD'>CUPS-Get-PPD Operation</a></h3>
1211
1212 <p>The CUPS-Get-PPD operation (0x400F) gets a PPD file from the server. The PPD file can be specified using a <tt>ppd-name</tt> returned by <a href='#CUPS_GET_PPDS'><tt>CUPS-Get-PPDs</tt></a> or using the <tt>printer-uri</tt> for a queue.</p>
1213
1214 <p>If the PPD file is found, <tt>successful-ok</tt> is returned with the PPD file following the response data.</p>
1215
1216 <p>If the PPD file cannot be served by the local server because the <tt>printer-uri</tt> attribute points to an external printer, a <tt>cups-see-other</tt> status is returned with the correct URI to use.</p>
1217
1218 <p>If the PPD file does not exist, <tt>client-error-not-found</tt> is returned.</p>
1219
1220 <h4>CUPS-Get-PPD Request</h4>
1221
1222 <p>The following group of attributes is supplied as part of the CUPS-Get-PPD request:
1223
1224 <p>Group 1: Operation Attributes
1225
1226 <dl>
1227
1228         <dt>Natural Language and Character Set:
1229
1230         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
1231
1232         <dt>"printer-uri" (uri)
1233         <br><i>OR</i>
1234         <br>"ppd-name" (name(255)):
1235
1236         <dd>The client MUST supply a printer URI or PPD name.
1237
1238 </dl>
1239
1240 <h4>CUPS-Get-PPD Response</h4>
1241
1242 <p>The following group of attributes is sent as part of the CUPS-Get-PPD Response:
1243
1244 <p>Group 1: Operation Attributes
1245
1246 <dl>
1247
1248         <dt>Natural Language and Character Set:
1249
1250         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
1251
1252         <dt>Status Message:
1253
1254         <dd>The standard response status message.
1255
1256         <dt>"printer-uri" (uri):
1257
1258         <dd>The printer that provides the actual PPD file when the status code is cups-see-other (0x280).
1259
1260 </dl>
1261
1262 <p>If the status code is <tt>successful-ok</tt>, the PPD file follows the end of the IPP response.</p>
1263
1264
1265 <h3 class='title'><span class='info'>CUPS 1.4/macOS 10.6</span><a name='CUPS_GET_DOCUMENT'>CUPS-Get-Document Operation</a></h3>
1266
1267 <p>The CUPS-Get-Document operation (0x4027) gets a document file from a job on the server. The document file is specified using the <tt>document-number</tt> and either the <tt>job-uri</tt> or <tt>printer-uri</tt> and <tt>job-id</tt> identifying the job.</p>
1268
1269 <p>If the document file is found, <tt>successful-ok</tt> is returned with the document file following the response data.</p>
1270
1271 <p>If the document file does not exist, <tt>client-error-not-found</tt> is returned.</p>
1272
1273 <p>If the requesting user does not have access to the document file, <tt>client-error-not-authorized</tt> is returned.
1274
1275 <h4>CUPS-Get-Document Request</h4>
1276
1277 <p>The following group of attributes is supplied as part of the CUPS-Get-Document request:
1278
1279 <p>Group 1: Operation Attributes
1280
1281 <dl>
1282
1283         <dt>Natural Language and Character Set:
1284
1285         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
1286
1287         <dt>"printer-uri" (uri) and "job-id" (integer)
1288         <br><i>OR</i>
1289         <br>"job-uri" (uri):
1290
1291         <dd>The client MUST supply a printer URI and job ID or job URI.
1292
1293         <dt>"document-number" (integer(1:MAX)):
1294
1295         <dd>The client MUST supply a document number to retrieve. The <tt>document-count</tt> attribute for the job defines the maximum document number that can be specified. In the case of jobs with banners (<tt>job-sheets</tt> is not "none"), document number 1 will typically contain the start banner and document number N will typically contain the end banner.
1296
1297 </dl>
1298
1299 <h4>CUPS-Get-Document Response</h4>
1300
1301 <p>The following group of attributes is sent as part of the CUPS-Get-Document Response:
1302
1303 <p>Group 1: Operation Attributes
1304
1305 <dl>
1306
1307         <dt>Natural Language and Character Set:
1308
1309         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
1310
1311         <dt>Status Message:
1312
1313         <dd>The standard response status message.
1314
1315         <dt>"document-format" (mimeType):
1316
1317         <dd>The format of the document file.
1318
1319         <dt>"document-number" (integer(1:MAX)):
1320
1321         <dd>The requested document number.
1322
1323         <dt>"document-name" (name(MAX)):
1324
1325         <dd>The name that was supplied with the document, if any.
1326
1327 </dl>
1328
1329 <p>If the status code is <tt>successful-ok</tt>, the document file follows the end of the IPP response.</p>
1330
1331
1332 <h3 class='title'><a name='CUPS_CREATE_LOCAL_PRINTER'>CUPS-Create-Local-Printer</a></h3>
1333
1334 <p>The CUPS-Create-Local-Printer operation (0x4028) creates a local (temporary) print queue pointing to a remote IPP Everywhere Printer. The queue will remain until the scheduler idle exits, is restarted, or the system is restarted or shutdown. Temporary print queues can be made permanent by an administrator by setting the "printer-is-shared" attribute to 'true'.</p>
1335
1336 <p>At a minimum, the scheduler requires a name and URI for the Printer to add. When successful, the local "printer-uri" values are returned and may be used by the Client to submit Job Creation Requests, monitor for state changes, and so forth.</p>
1337
1338 <p>If the named printer already exists, the scheduler will reject the request with the 'client-error-not-possible' status code.</p>
1339
1340 <p>Access Rights: The authenticated user performing this operation MUST be a Local User of the system, and the request MUST be made over a local (domain socket or loopback interface) address. Otherwise, the request will be rejected with the 'client-error-forbidden' status code.</p>
1341
1342 <h4>CUPS-Create-Local-Printer Request</h4>
1343
1344 <p>The following group of attributes is supplied as part of the CUPS-Create-Local-Printer request:
1345
1346 <p>Group 1: Operation Attributes
1347
1348 <dl>
1349
1350         <dt>Natural Language and Character Set:
1351
1352         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1 of the IPP Model and Semantics document.
1353
1354 </dl>
1355
1356 <p>Group 2: Printer Attributes
1357
1358 <dl>
1359
1360         <dt>"printer-name" (name(127)):
1361
1362         <dd>The Client MUST supply this attribute which provides the name for the new Printer.
1363
1364         <dt>"device-uri" (uri):
1365
1366         <dd>The Client MUST supply this attribute which provides an "ipp" or "ipps" URI pointing to an IPP Everywhere Printer.
1367
1368         <dt>"printer-device-id" (text(1023)):
1369
1370         <dd>The Client OPTIONALLY supplies this attribute which provides the IEEE 1284 device ID for the new Printer.
1371
1372         <dt>"printer-geo-location" (uri):
1373
1374         <dd>The Client OPTIONALLY supplies this attribute which provides the geo-location of the new Printer as a "geo" URI.
1375
1376         <dt>"printer-info" (text(127)):
1377
1378         <dd>The Client OPTIONALLY supplies this attribute which provides the description for the new Printer.
1379
1380         <dt>"printer-location" (text(127)):
1381
1382         <dd>The Client OPTIONALLY supplies this attribute which provides the location of the new Printer.
1383
1384 </dl>
1385
1386 <h4>CUPS-Create-Local-Printer Response</h4>
1387
1388 <p>The following group of attributes is sent as part of the CUPS-Create-Local-Printer Response:
1389
1390 <p>Group 1: Operation Attributes
1391
1392 <dl>
1393
1394         <dt>Natural Language and Character Set:
1395
1396         <dd>The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of the IPP Model and Semantics document.
1397
1398         <dt>Status Message:
1399
1400         <dd>The standard response status message.
1401
1402 </dl>
1403
1404 <p>Group 2: Printer Attributes
1405
1406 <dl>
1407
1408         <dt>"printer-id" (integer(0:65535)):
1409
1410         <dd>The numeric identifier for the created Printer.
1411
1412         <dt>"printer-is-accepting-jobs" (boolean):
1413
1414         <dd>Whether the created Printer is accepting jobs at the time of the response.
1415
1416         <dt>"printer-state" (type1 enum):
1417
1418         <dd>The state of the created Printer at the time of the response.
1419
1420         <dt>"printer-state-reasons" (1setOf type2 keyword):
1421
1422         <dd>The state keywords for the created Printer at the time of the response.
1423
1424         <dt>"printer-uri-supported" (1setOf uri):
1425
1426         <dd>The URIs for the created Printer.
1427
1428 </dl>
1429
1430
1431 <h2 class='title'><a name='ATTRIBUTES'>Attributes</a></h2>
1432
1433 <p>CUPS provides many extension attributes to support multiple devices, PPD files, standard job filters, printers, and printer classes.</p>
1434
1435 <h3 class='title'><a name='DEVICE_ATTRIBUTES'>Device Attributes</a><span class="info">Deprecated</span></h3>
1436
1437 <p>Device attributes are returned by the CUPS-Get-Devices operation and enumerate all of the available hardware devices and network protocols that are supported by the server. Device attributes are reported in the printer-attributes-tag group.</p>
1438
1439 <h4><a name="device-class">device-class (type2 keyword)</a><span class="info">Deprecated</span></h4>
1440
1441 <p>The "device-class" attribute provides the class of device and can be one of the following:
1442
1443 <ul>
1444
1445         <li>'file': A disk file.
1446
1447         <li>'direct': A parallel or fixed-rate serial data port,
1448         currently used for Centronics, IEEE-1284, and USB printer
1449         ports.
1450
1451         <li>'serial': A variable-rate serial port.
1452
1453         <li>'network': A network connection, typically via AppSocket, HTTP, IPP, LPD, or SMB/CIFS protocols.
1454
1455 </ul>
1456
1457 <h4><a name="device-id">device-id (text(1023))</a><span class="info">Deprecated</span></h4>
1458
1459 <p>The "device-id" attribute provides the IEEE-1284 device ID string for the device.</p>
1460
1461 <h4><a name="device-info">device-info (text(127))</a><span class="info">Deprecated</span></h4>
1462
1463 <p>The "device-info" attribute specifies a human-readable string describing the device, e.g., 'Parallel Port #1'.
1464
1465 <h4><a name="device-location">device-location (text(127))</a><span class="info">Deprecated</span></h4>
1466
1467 <p>The "device-location" attribute specifies the physical location of the printer, e.g., '2nd Floor Computer Lab'.
1468
1469 <h4><a name="device-make-and-model">device-make-and-model (text(127))</a><span class="info">Deprecated</span></h4>
1470
1471 <p>The "device-make-and-model" attribute specifies a device identification string provided by the printer connected to the device. If the device or printer does not support identification then this attribute contains the string 'unknown'.
1472
1473 <h4><a name="device-uri">device-uri (uri)</a></h4>
1474
1475 <p>The "device-uri" attribute specifies a unique identifier for the device. The actual format of the "device-uri" string depends on the value of the "device-class" attribute:
1476
1477 <ul>
1478
1479         <li>'file': The "device-uri" will be of the form 'file:///path/to/filename'.
1480
1481         <li>'direct': The "device-uri" will be of the form 'scheme:/dev/filename' or 'scheme://vendor/identifier', where scheme may be 'parallel' or 'usb' in the current implementation.
1482
1483         <li>'serial': The "device-uri" will be of the form 'serial:/dev/filename?baud=value+parity=value+flow=value'. The baud value is the data rate in bits per second; the supported values depend on the underlying hardware. The parity value can be one of "none", "even", or "odd". The flow value can be one of "none", "soft" (XON/XOFF handshaking), "hard" or "rts/cts" (RTS/CTS handshaking), or "dtrdsr" (DTR/DSR handshaking).
1484
1485         <p>The URI returned by CUPS-Get-Devices will contain the maximum baud rate supported by the device and the best type of flow control available ("soft" or "hard").
1486
1487         <li>'network': The "device-uri" will be of the form 'scheme://[username:password@]hostname[:port]/[resource]', where scheme may be "http", "https", "ipp", "lpd", "smb", or "socket" in the current implementation.
1488
1489         <p>The URI returned by CUPS-Get-Devices MAY only contain the scheme name ('scheme'). It is up to the client application to add the appropriate host and other information when adding a new printer.
1490
1491         <p>The URI returned by Get-Printer-Attributes and CUPS-Get-Printers has any username and password information stripped; the information is still stored and used by the server internally to perform any needed authentication.
1492
1493 </ul>
1494
1495
1496 <h3 class='title'><a name='JOB_ATTRIBUTES'>Job Attributes</a></h3>
1497
1498 <h4><a name="auth-info">auth-info (1setOf text(MAX))</a><span class="info">CUPS 1.3/macOS 10.5</span></h4>
1499
1500 <p>The "auth-info" attribute specifies the authentication information to use when printing to a remote device. The order and content of each text value is specifed by the <a href="#auth-info-required">auth-info-required</a> printer attribute.
1501
1502 <h4><a name="job-cancel-after">job-cancel-after (integer(1:MAX))</a><span class='info'>CUPS 2.0</span></h4>
1503
1504 <p>The "job-cancel-after" attribute provides the maximum number of seconds that are allowed for processing a job.</p>
1505
1506 <h4><a name="job-hold-until">job-hold-until (keyword | name(MAX))</a><span class='info'>CUPS 1.1</span></h4>
1507
1508 <p>The "job-hold-until" attribute specifies a hold time. In addition to the standard IPP/1.1 keyword names, CUPS supports name values of the form "HH:MM" and "HH:MM:SS" that specify a hold time. The hold time is in Universal Coordinated Time (UTC) and <i>not</i> in the local time zone. If the specified time is less than the current time, the job is held until the next day.
1509
1510 <h4><a name="job-media-progress">job-media-progress (integer(0:100))</a><span class='info'>CUPS 1.4/macOS 10.6</span></h4>
1511
1512 <p>The "job-media-progress" status attribute specifies the percentage of completion of the current page. It is only valid when the "job-state" attribute has the 'processing(5)' value.</p>
1513
1514 <h4><a name="job-printer-state-message">job-printer-state-message (text(MAX))</a><span class='info'>CUPS 1.3/macOS 10.5</span></h4>
1515
1516 <p>The "job-printer-state-message" status attribute provides the last known value of the "printer-state-message" attribute for the printer that processed (or is processing) the job.</p>
1517
1518 <h4><a name="job-printer-state-reasons">job-printer-state-reasons (1setOf type2 keyword)</a><span class='info'>CUPS 1.3/macOS 10.5</span></h4>
1519
1520 <p>The "job-printer-state-reasons" status attribute provides the last known value of the "printer-state-reasons" attribute for the printer that processed (or is processing) the job.</p>
1521
1522 <h4><a name="job-sheets">job-sheets (1setof type3 keyword | name(MAX))</a><span class='info'>CUPS 1.1</span></h4>
1523
1524 <p>The "job-sheets" attribute specifies one or two banner files that are printed before and after a job. The reserved value of "none" disables banner printing. The default value is stored in the "job-sheets-default" attribute.
1525
1526 <p>If only one value is supplied, the banner file is printed before the job. If two values are supplied, the first value is used as the starting banner file and the second as the ending banner file.
1527
1528 <h4><a name="job-originating-host-name">job-originating-host-name (name(MAX))</a><span class='info'>CUPS 1.1.5/macOS 10.2</span></h4>
1529
1530 <p>The "job-originating-host-name" status attribute specifies the host from which the job was queued. The value will be the hostname or IP address of the client depending on whether hostname resolution is enabled.  The localhost address (127.0.0.1) is <b>always</b> resolved to the name "localhost".
1531
1532 <p>This attribute is read-only.
1533
1534 <h4><a name="page-border">page-border (type2 keyword)</a><span class='info'>CUPS 1.1.15</span></h4>
1535
1536 <p>The "page-border" attribute specifies whether a border is draw around each page. The following keywords are presently defined:
1537
1538 <ul>
1539
1540         <li>'double': Two hairline borders are drawn</li>
1541
1542         <li>'double-thick': Two 1pt borders are drawn</li>
1543
1544         <li>'none': No border is drawn (default)</li>
1545
1546         <li>'single': A single hairline border is drawn</li>
1547
1548         <li>'single-thick': A single 1pt border is drawn</li>
1549
1550 </ul>
1551
1552 <h4><a name="page-set">page-set (type2 keyword)</a><span class="info">Deprecated</span></h4>
1553
1554 <p>The "page-set" attribute specifies which pages to print in a file. The supported keywords are 'all', 'even', and 'odd'. The default value is 'all'.
1555
1556 <h3 class='title'><a name='PPD_ATTRIBUTES'>PPD Attributes</a><span class="info">Deprecated</span></h3>
1557
1558 <p>PPD attributes are returned in the printer-attributes-tag group.
1559
1560 <h4><a name="ppd-device-id">ppd-device-id (text(127))</a><span class="info">Deprecated</span></h4>
1561
1562 <p>The "ppd-device-id" attribute specifies the IEEE-1284 device ID string for the device described by the PPD file.</p>
1563
1564 <h4><a name="ppd-make">ppd-make (text(127))</a><span class="info">Deprecated</span></h4>
1565
1566 <p>The "ppd-make" attribute specifies the manufacturer of the printer (the Manufacturer attribute in the PPD file). If the manufacturer is not specified in the PPD file then an educated guess is made using the NickName attribute in the PPD file.
1567
1568 <h4><a name="ppd-make-and-model">ppd-make-and-model (text(127))</a><span class="info">Deprecated</span></h4>
1569
1570 <p>The "ppd-make-and-model" attribute specifies the manufacturer and model name of the PPD file (the NickName attribute in the PPD file). If the make and model is not specified in the PPD file then the ModelName or ShortNickName attributes are used instead.
1571
1572 <h4><a name="ppd-model-number">ppd-model-number (integer)</a><span class="info">Deprecated</span></h4>
1573
1574 <p>The "ppd-model-number" attribute provides the <tt>cupsModelNumber</tt> value from the PPD file.
1575
1576 <h4><a name="ppd-name">ppd-name (name(255))</a><span class="info">Deprecated</span></h4>
1577
1578 <p>The "ppd-name" attribute specifies either the PPD filename on the server relative to the model directory or a URI that maps to a specific driver interface in the driver directory. The forward slash (/) is used to delineate directories.
1579
1580 <h4><a name="ppd-natural-language">ppd-natural-language (1setOf naturalLanguage)</a><span class="info">Deprecated</span></h4>
1581
1582 <p>The "ppd-natural-language" attribute specifies the language encoding of the PPD file (the LanguageVersion attribute in the PPD file). If the language is unknown or undefined then "en" (English) is assumed.
1583
1584 <h4><a name="ppd-product">ppd-product (1setOf text(127))</a><span class="info">Deprecated</span></h4>
1585
1586 <p>The "ppd-product" attribute specifies the Product attribute values in the PPD file.
1587
1588 <h4><a name="ppd-psversion">ppd-psversion (1setOf text(127))</a><span class="info">Deprecated</span></h4>
1589
1590 <p>The "ppd-product" attribute specifies the PSVersion attribute values in the PPD file.
1591
1592 <h4><a name="ppd-type">ppd-type (type1 keyword)</a><span class="info">Deprecated</span></h4>
1593
1594 <p>The "ppd-type" attribute specifies the type of driver described by the PPD file:</p>
1595
1596 <ul>
1597
1598         <li>'fax': A facsimile or multi-function device</li>
1599
1600         <li>'pdf': A PDF printer</li>
1601
1602         <li>'postscript': A PostScript printer (no filters)</li>
1603
1604         <li>'raster': A CUPS raster driver</li>
1605
1606         <li>'unknown': An unknown or hybrid driver</li>
1607
1608 </ul>
1609
1610
1611 <h3 class='title'><a name='PRINTER_ATTRIBUTES'>Printer Attributes</a></h3>
1612
1613 <h4><a name="auth-info-required">auth-info-required (1setOf type2 keyword)</a><span class="info">CUPS 1.3/macOS 10.5</span></h4>
1614
1615 <p>The "auth-info-required" attribute specifies the authentication information that is required for printing a job. The following keywords are recognized:</p>
1616
1617 <ul>
1618
1619         <li>'domain': A domain name is required.</li>
1620
1621         <li>'negotiate': Kerberos is required - this keyword can only appear by itself and causes cupsd to collect the UID of the printing user.</li>
1622
1623         <li>'none': No authentication is required - this keyword can only appear by itself.</li>
1624
1625         <li>'password': A password is required.</li>
1626
1627         <li>'username': A username is required. Some protocols (like SMB) prefix the username with the domain, for example "DOMAIN\user".</li>
1628
1629 </ul>
1630
1631 <h4><a name="job-k-limit">job-k-limit (integer)</a><span class='info'>CUPS 1.1</span></h4>
1632
1633 <p>The "job-k-limit" attribute specifies the maximum number of kilobytes that may be printed by a user, including banner files. The default value of 0 specifies that there is no limit.
1634
1635 <h4><a name="job-page-limit">job-page-limit (integer)</a><span class='info'>CUPS 1.1</span></h4>
1636
1637 <p>The "job-page-limit" attribute specifies the maximum number of pages that may be printed by a user, including banner files. The default value of 0 specifies that there is no limit.
1638
1639 <h4><a name="job-quota-period">job-quota-period (integer)</a><span class='info'>CUPS 1.1</span></h4>
1640
1641 <p>The "job-quota-period" attribute specifies the time period used for quota calculations, in seconds. The default value of 0 specifies that the limits apply to all jobs that have been printed by a user that are still known to the system.
1642
1643 <h4><a name="marker-change-time">marker-change-time (integer)</a><span class='info'>CUPS 1.3/macOS 10.5</span></h4>
1644
1645 <p>The "marker-change-time" status attribute specifies the "printer-up-time" value when the last change to the marker-colors, marker-levels, marker-message, marker-names, or marker-types attributes was made.</p>
1646
1647 <h4><a name="marker-colors">marker-colors (1setof name(MAX))</a><span class='info'>CUPS 1.3/macOS 10.5</span></h4>
1648
1649 <p>The "marker-colors" status attribute specifies the color(s) for each supply in the printer. It is only available when the driver provides supply levels. The color is either 'none' or one or more hex-encoded sRGB colors of the form '#RRGGBB'.</p>
1650
1651 <h4><a name="marker-high-levels">marker-high-levels (1setof integer(0:100))</a><span class='info'>CUPS 1.4/macOS 10.6</span></h4>
1652
1653 <p>The "marker-high-levels" status attribute specifies the supply levels that indicate a near-full condition. A value of 100 should be used for supplies that are consumed/emptied, e.g. ink cartridges.</p>
1654
1655 <h4><a name="marker-levels">marker-levels (1setof integer(-3:100))</a><span class='info'>CUPS 1.3/macOS 10.5</span></h4>
1656
1657 <p>The "marker-levels" status attribute specifies the current supply levels for the printer. It is only available when the driver provides supply levels. A value of -1 indicates the level is unavailable, -2 indicates unknown, and -3 indicates the level is unknown but has not yet reached capacity. Values from 0 to 100 indicate the corresponding percentage.</p>
1658
1659 <h4><a name="marker-low-levels">marker-low-levels (1setof integer(0:100))</a><span class='info'>CUPS 1.4/macOS 10.6</span></h4>
1660
1661 <p>The "marker-low-levels" status attribute specifies the supply levels that indicate a near-empty condition. A value of 0 should be used for supplies that are filled, e.g. waste ink tanks.</p>
1662
1663 <h4><a name="marker-message">marker-message (text(MAX))</a><span class='info'>CUPS 1.4/macOS 10.6</span></h4>
1664
1665 <p>The "marker-message" status attribute provides a human-readable status message for the current supply levels, e.g. "12 pages of ink remaining." It is only available when the driver provides supply levels.</p>
1666
1667 <h4><a name="marker-names">marker-names (1setof name(MAX))</a><span class='info'>CUPS 1.3/macOS 10.5</span></h4>
1668
1669 <p>The "marker-names" status attribute specifies the name(s) for each supply in the printer. It is only available when the driver provides supply levels.</p>
1670
1671 <h4><a name="marker-types">marker-types (1setof type3 keyword)</a><span class='info'>CUPS 1.3/macOS 10.5</span></h4>
1672
1673 <p>The "marker-types" status attribute specifies the type(s) of each supply in the printer. It is only available when the driver provides supply levels. The following (RFC 3805) types are currently supported:</p>
1674
1675 <ul>
1676
1677         <li>'toner'</li>
1678
1679         <li>'waste-toner'</li>
1680
1681         <li>'ink'</li>
1682
1683         <li>'ink-cartridge'</li>
1684
1685         <li>'ink-ribbon'</li>
1686
1687         <li>'waste-ink'</li>
1688
1689         <li>'opc'</li>
1690
1691         <li>'developer'</li>
1692
1693         <li>'fuser-oil'</li>
1694
1695         <li>'solid-wax'</li>
1696
1697         <li>'ribbon-wax'</li>
1698
1699         <li>'waste-wax'</li>
1700
1701         <li>'fuser'</li>
1702
1703         <li>'corona-wire'</li>
1704
1705         <li>'fuser-oil-wick'</li>
1706
1707         <li>'cleaner-unit'</li>
1708
1709         <li>'fuser-cleaning-pad'</li>
1710
1711         <li>'transfer-unit'</li>
1712
1713         <li>'toner-cartridge'</li>
1714
1715         <li>'fuser-oiler'</li>
1716
1717         <li>'water'</li>
1718
1719         <li>'waste-water'</li>
1720
1721         <li>'binding-supply'</li>
1722
1723         <li>'banding-supply'</li>
1724
1725         <li>'stiching-wire'</li>
1726
1727         <li>'shrink-wrap'</li>
1728
1729         <li>'paper-wrap'</li>
1730
1731         <li>'staples'</li>
1732
1733         <li>'inserts'</li>
1734
1735         <li>'covers'</li>
1736
1737 </ul>
1738
1739 <h4><a name="port-monitor">port-monitor" (name(127))</a><span class="info">Deprecated</span></h4>
1740
1741 <p>The "port-monitor" attribute specifies the port monitor to use when printing to this printer. The default port monitor is 'none'.
1742
1743 <h4><a name="port-monitor-supported">port-monitor-supported" (1setOf name(127))</a><span class="info">Deprecated</span></h4>
1744
1745 <p>The "port-monitor-supported" attribute specifies the available port monitors.
1746
1747 <h4><a name="printer-commands">printer-commands (1setOf Type3 keyword)</a><span class='info'>Deprecated</span></h4>
1748
1749 <p>The "printer-commands" attribute specifies the commands that are supported by the CUPS command file filter. The keyword 'none' indicates that no commands are supported.</p>
1750
1751 <h4><a name="printer-dns-sd-name">printer-dns-sd-name (name(MAX) | noValue)</a><span class='info'>CUPS 1.4/macOS 10.6</span></h4>
1752
1753 <p>The "printer-dns-sd-name" attribute specifies the registered DNS-SD service name for the printer. If the printer is not being shared using this protocol, "printer-dns-sd-name" will have the no-value value.</p>
1754
1755 <h4><a name="printer-id">printer-id (integer(0:65535)</a><span class="info">CUPS 2.2</span></h4>
1756
1757 <p>The "printer-id" status attribute provides a unique integer identifying the printer. It is used when only an IP address and integer are provided for identifying a print queue.</p>
1758
1759 <h4><a name="printer-type">printer-type (type2 enum)</a></h4>
1760
1761 <p>The "printer-type" status attribute specifies printer type and capability bits for the printer or class. The default value is computed from internal state information and the PPD file for the printer. The following bits are defined:</p>
1762
1763 <div class='table'><table align='center' border='1' width='80%' summary='Printer Type Bits'>
1764 <thead>
1765 <tr>
1766         <th>Bit</th>
1767         <th>Description</th>
1768 </tr>
1769 </thead>
1770 <tbody>
1771 <tr>
1772         <td>0x00000001</td>
1773         <td>Is a printer class.</td>
1774 </tr>
1775 <tr>
1776         <td>0x00000002</td>
1777         <td>Is a remote destination.</td>
1778 </tr>
1779 <tr>
1780         <td>0x00000004</td>
1781         <td>Can print in black.</td>
1782 </tr>
1783 <tr>
1784         <td>0x00000008</td>
1785         <td>Can print in color.</td>
1786 </tr>
1787 <tr>
1788         <td>0x00000010</td>
1789         <td>Can print on both sides of the page in hardware.</td>
1790 </tr>
1791 <tr>
1792         <td>0x00000020</td>
1793         <td>Can staple output.</td>
1794 </tr>
1795 <tr>
1796         <td>0x00000040</td>
1797         <td>Can do fast copies in hardware.</td>
1798 </tr>
1799 <tr>
1800         <td>0x00000080</td>
1801         <td>Can do fast copy collation in hardware.</td>
1802 </tr>
1803 <tr>
1804         <td>0x00000100</td>
1805         <td>Can punch output.</td>
1806 </tr>
1807 <tr>
1808         <td>0x00000200</td>
1809         <td>Can cover output.</td>
1810 </tr>
1811 <tr>
1812         <td>0x00000400</td>
1813         <td>Can bind output.</td>
1814 </tr>
1815 <tr>
1816         <td>0x00000800</td>
1817         <td>Can sort output.</td>
1818 </tr>
1819 <tr>
1820         <td>0x00001000</td>
1821         <td>Can handle media up to US-Legal/A4.</td>
1822 </tr>
1823 <tr>
1824         <td>0x00002000</td>
1825         <td>Can handle media from US-Legal/A4 to ISO-C/A2.</td>
1826 </tr>
1827 <tr>
1828         <td>0x00004000</td>
1829         <td>Can handle media larger than ISO-C/A2.</td>
1830 </tr>
1831 <tr>
1832         <td>0x00008000</td>
1833         <td>Can handle user-defined media sizes.</td>
1834 </tr>
1835 <tr>
1836         <td>0x00010000</td>
1837         <td>Is an implicit (server-generated) class.</td>
1838 </tr>
1839 <tr>
1840         <td>0x00020000</td>
1841         <td>Is the a default printer on the network.</td>
1842 </tr>
1843 <tr>
1844         <td>0x00040000</td>
1845         <td>Is a facsimile device.</td>
1846 </tr>
1847 <tr>
1848         <td>0x00080000</td>
1849         <td>Is rejecting jobs.</td>
1850 </tr>
1851 <tr>
1852         <td>0x00100000</td>
1853         <td>Delete this queue.</td>
1854 </tr>
1855 <tr>
1856         <td>0x00200000</td>
1857         <td>Queue is not shared.</td>
1858 </tr>
1859 <tr>
1860         <td>0x00400000</td>
1861         <td>Queue requires authentication.</td>
1862 </tr>
1863 <tr>
1864         <td>0x00800000</td>
1865         <td>Queue supports CUPS command files.</td>
1866 </tr>
1867 <tr>
1868         <td>0x01000000</td>
1869         <td>Queue was automatically discovered and added.</td>
1870 </tr>
1871 <tr>
1872         <td>0x02000000</td>
1873         <td>Queue is a scanner with no printing capabilities.</td>
1874 </tr>
1875 <tr>
1876         <td>0x04000000</td>
1877         <td>Queue is a printer with scanning capabilities.</td>
1878 </tr>
1879 <tr>
1880         <td>0x08000000</td>
1881         <td>Queue is a printer with 3D capabilities.</td>
1882 </tr>
1883 </tbody>
1884 </table></div>
1885
1886 <h4>printer-type-mask (type2 enum)<span class='info'>CUPS 1.1</span></h4>
1887
1888 <p>The "printer-type-mask" attribute is used to choose printers or classes with the CUPS-Get-Printers and CUPS-Get-Classes operations. The bits are defined identically to the printer-type attribute and default to all 1's.
1889 </p>
1890
1891 <h4>printer-wifi-password (octetString(MAX))</h4>
1892
1893 <p>The optional "printer-wifi-password" description attribute provides the wireless network password for a printer.
1894 Printers must not return this attribute in the response to a Get-Printer-Attributes request.
1895 This attribute can only be set via an authenticated Set-Printer-Attributes request over a secure channel,
1896 or via an unauthenticated IPP USB connection when the printer is in its initial setup state.
1897 When a value for this attribute is not set, the 'wifi-not-configured-report' keyword must be present in the
1898 "printer-state-reasons" printer attribute values. If a printer supports this attribute, it must also support
1899 the "printer-wifi-ssid" and "printer-wifi-state" attributes.</p>
1900
1901 <h4>printer-wifi-ssid (name(MAX))</h4>
1902
1903 <p>The optional "printer-wifi-ssid" description attribute specifies the wireless network name for the printer.
1904 When set to the empty string, the printer must not join infrastructure or ad-hoc networks.
1905 This attribute can only be set via an authenticated Set-Printer-Attributes request over a secure channel,
1906 or via an unauthenticated IPP USB connection when the printer is in its initial setup state.
1907 This attribute also must reflect any configuration done by the user through the printer's web interface,
1908 control panel, or other interface. When a value for this attribute is not set, the 'wifi-not-configured-report'
1909 keyword must be present in the "printer-state-reasons" printer attribute values.
1910 If a printer supports this attribute, it must also support the "printer-wifi-password" and
1911 "printer-wifi-state" attributes.</p>
1912
1913 <p>Printers that support the Set-Printer-Attribtes operation and "printer-wifi-password" and "printer-wifi-ssid"
1914 printer description attributes must also support unauthenticated Set-Printer-Attributes requests over USB when Wi-Fi
1915 networking has not yet been configured. This allows a client to configure the Wi-Fi networking of a printer over USB.</p>
1916
1917 <p>When configuring a wireless network, clients must send both the "printer-wifi-ssid" and "printer-wifi-password"
1918 printer description attributes. If only one attribute is supplied, the printer must reject the request with the
1919 client-error-bad-request status code. If either attribute is supplied with an invalid value,
1920 the printer must reject the request with the client-error-attributes-or-values-not-supported status code.</p>
1921
1922 In addition to other defined printer-state-reasons, the 'wifi-not-configured-report' reason is returned when the
1923 "printer-wifi-password" and "printer-wifi-ssid" printer description attributes are not set,
1924 regardless of the value of the "printer-wifi-state" printer status attribute.
1925
1926 <h4>printer-wifi-state (type2 enum)</h4>
1927
1928 <p>The optional "printer-wifi-state" status attribute specifies a printer's current wireless network state as
1929 an enumerated value. The following values are currently defined:</p>
1930
1931 <div class='table'><table align='center' border='1' width='80%' summary='Wireless Networking State'>
1932 <tbody>
1933 <tr>
1934         <td>3</td>
1935         <td>(off) wireless networking is turned off</td>
1936 </tr>
1937 <tr>
1938         <td>4</td>
1939         <td>(not-configured) wireless networking is not yet configured</td>
1940 </tr>
1941 <tr>
1942         <td>5</td>
1943         <td>(not-visible) the configured wireless network is not visible</td>
1944 </tr>
1945 <tr>
1946         <td>6</td>
1947         <td>(cannot-join) unable to join the configured wireless network</td>
1948 </tr>
1949 <tr>
1950         <td>7</td>
1951         <td>(joining) joining the configured wireless network</td>
1952 </tr>
1953 <tr>
1954         <td>8</td>
1955         <td>(on) joined to the configured wireless network</td>
1956 </tr>
1957 </tbody>
1958 </table></div>
1959
1960 <h4>requesting-user-name-allowed (1setof name(127))<span class='info'>CUPS 1.1</span></h4>
1961
1962 <p>The "requesting-user-name-allowed" attribute lists all of the users that are allowed to access a printer or class. Either this attribute or the "requesting-user-name-denied" attribute will be defined, but not both.
1963
1964 <h4>requesting-user-name-denied (1setof name(127))<span class='info'>CUPS 1.1</span></h4>
1965
1966 <p>The "requesting-user-name-denied" attribute lists all of the users that are not allowed to access a printer or class. Either this attribute or the "requesting-user-name-allowed" attribute will be defined, but not both.
1967
1968 <h3 class='title'><a name='CLASS_ATTRIBUTES'>Printer Class Attributes</a></h3>
1969
1970 <p>Printer class attributes are placed in the printer-attributes-tag group.</p>
1971
1972 <h4>member-names (1setof name(127))</h4>
1973
1974 <p>The "member-names" attribute specifies the "printer-name" attributes for each the member printer and class. Each name corresponds to the same element of the "member-uris" attribute.
1975
1976 <h4>member-uris (1setof uri)</h4>
1977
1978 <p>The "member-uris" attribute specifies the "printer-uri-supported" values for each member printer and class. Each URI corresponds to the same element of the "member-names" attribute.
1979
1980 </body>
1981 </html>