doc/help/spec-ipp.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
   2 <html>
   3 <!-- SECTION: Specifications -->
   4 <head>
   5         <title>CUPS Implementation of IPP</title>
   6         <meta name='keywords' content='Programming, Internet Printing Protocol'>
   7 </head>
   8 <body>
   9 <!--
  10   "$Id$"
  11
  12   CUPS IPP specification for the Common UNIX Printing System (CUPS).
  13
  14   Copyright 2007 by Apple Inc.
  15   Copyright 1997-2007 by Easy Software Products.
  16
  17   These coded instructions, statements, and computer programs are the
  18   property of Easy Software Products and are protected by Federal
  19   copyright law.  Distribution and use rights are outlined in the file
  20   "LICENSE.txt" which should have been included with this file.  If this
  21   file is missing or damaged please contact Easy Software Products
  22   at:
  23
  24       Attn: CUPS Licensing Information
  25       Easy Software Products
  26       44141 Airport View Drive, Suite 204
  27       Hollywood, Maryland 20636 USA
  28
  29       Voice: (301) 373-9600
  30       EMail: cups-info@cups.org
  31         WWW: http://www.cups.org
  32 -->
  33
  34 <h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
  35
  36 <p>CUPS 1.1 implements IPP/1.1 and the operations and attributes
  37 defined in the "IPP: Job and Printer Set Operations", "IPP/1.1:
  38 Output-bin Attribute Extension", and "IPP/1.1: finishings
  39 'fold',' trim', and 'bale' attribute values extension"
  40 specifications.</p>
  41
  42 <p>CUPS also provides 16 new operations and many new attributes
  43 to support multiple IPP printers and printer classes on a single
  44 host.</p>
  45
  46 <h3 class='title'><a name='IPP_URIS'>IPP URIs</a></h3>
  47
  48 <p>CUPS supports the "http", "https", and "ipp" schemes. The
  49 following resource names are used:</p>
  50
  51 <dl>
  52
  53         <dt><tt>scheme://hostname:port/</tt></dt>
  54
  55         <dd>Can be used for all "get" operations and for server
  56         subscriptions.</dd>
  57
  58         <dt><tt>scheme://hostname:port/admin/</tt></dt>
  59
  60         <dd>Used for all administrative operations.</dd>
  61
  62         <dt><tt>scheme://hostname:port/classes/name</tt></dt>
  63
  64         <dd>Specifies a printer class.</dd>
  65
  66         <dt><tt>scheme://hostname:port/jobs/id</tt></dt>
  67
  68         <dd>Specifies a job.</dd>
  69
  70         <dt><tt>scheme://hostname:port/printers/name</tt></dt>
  71
  72         <dd>Specifies a printer.</dd>
  73
  74 </dl>
  75
  76 <p>So a typical printer URI would be
  77 "ipp://foo.bar.com/printers/LaserJet". In addition, the CUPS
  78 server also supports normal browser access via
  79 "http://hostname:port/" and "https://hostname:port/".</p>
  80
  81 <h3 class='title'><a name='IPP_OPERATIONS'>CUPS IPP Operations</a></h3>
  82
  83 <p>CUPS provides 16 extension operations in addition to most of the
  84 standard IPP and registered extension operations:
  85
  86 <div class='table'><table align='center' border='1' width='80%'
  87 summary='Supported Operations'>
  88 <thead>
  89 <tr>
  90         <TH VALIGN="TOP">Operation Name</th>
  91         <TH VALIGN="TOP">CUPS</th>
  92         <TH VALIGN="TOP">Code</th>
  93         <TH VALIGN="TOP">Brief Description</th>
  94 </tr>
  95 </thead>
  96 <tbody>
  97 <tr>
  98         <td><a href='#PRINT_JOB'>Print-Job</a></td>
  99         <td>1.0</td>
 100         <td>0x0002</td>
 101         <td>Print a file.</td>
 102 </tr>
 103 <tr>
 104         <td>Validate-Job</td>
 105         <td>1.0</td>
 106         <td>0x0004</td>
 107         <td>Validate job attributes.</td>
 108 </tr>
 109 <tr>
 110         <td><a href='#CREATE_JOB'>Create-Job</a></td>
 111         <td>1.1</td>
 112         <td>0x0005</td>
 113         <td>Create a print job.</td>
 114 </tr>
 115 <tr>
 116         <td>Send-Document</td>
 117         <td>1.1</td>
 118         <td>0x0006</td>
 119         <td>Send a file for a print job.</td>
 120 </tr>
 121 <tr>
 122         <td><a href='#CANCEL_JOB'>Cancel-Job</a></td>
 123         <td>1.0</td>
 124         <td>0x0008</td>
 125         <td>Cancel a print job.</td>
 126 </tr>
 127 <tr>
 128         <td>Get-Job-Attributes</td>
 129         <td>1.0</td>
 130         <td>0x0009</td>
 131         <td>Get job attributes.</td>
 132 </tr>
 133 <tr>
 134         <td>Get-Jobs</td>
 135         <td>1.0</td>
 136         <td>0x000A</td>
 137         <td>Get all jobs.</td>
 138 </tr>
 139 <tr>
 140         <td>Get-Printer-Attributes</td>
 141         <td>1.0</td>
 142         <td>0x000B</td>
 143         <td>Get printer attributes.</td>
 144 </tr>
 145 <tr>
 146         <td>Hold-Job</td>
 147         <td>1.1</td>
 148         <td>0x000C</td>
 149         <td>Hold a job for printing.</td>
 150 </tr>
 151 <tr>
 152         <td>Release-Job</td>
 153         <td>1.1</td>
 154         <td>0x000D</td>
 155         <td>Release a job for printing.</td>
 156 </tr>
 157 <tr>
 158         <td>Restart-Job</td>
 159         <td>1.1</td>
 160         <td>0x000E</td>
 161         <td>Restarts a print job.</td>
 162 </tr>
 163 <tr>
 164         <td>Pause-Printer</td>
 165         <td>1.0</td>
 166         <td>0x0010</td>
 167         <td>Pause printing on a printer.</td>
 168 </tr>
 169 <tr>
 170         <td>Resume-Printer</td>
 171         <td>1.0</td>
 172         <td>0x0011</td>
 173         <td>Resume printing on a printer.</td>
 174 </tr>
 175 <tr>
 176         <td><a href='#PURGE_JOBS'>Purge-Jobs</a></td>
 177         <td>1.0</td>
 178         <td>0x0012</td>
 179         <td>Purge all jobs.</td>
 180 </tr>
 181 <tr>
 182         <td><a href='#SET_JOB_ATTRIBUTES'>Set-Job-Attributes</a></td>
 183         <td>1.1</td>
 184         <td>0x0014</td>
 185         <td>Set attributes for a pending or held job.</td>
 186 </tr>
 187 <tr>
 188         <td><a href='#CREATE_PRINTER_SUBSCRIPTION'>Create-Printer-Subscription</a></td>
 189         <td>1.2</td>
 190         <td>0x0016</td>
 191         <td>Creates a subscription associated with a printer or the server.</td>
 192 </tr>
 193 <tr>
 194         <td>Create-Job-Subscription</td>
 195         <td>1.2</td>
 196         <td>0x0017</td>
 197         <td>Creates a subscription associated with a job.</td>
 198 </tr>
 199 <tr>
 200         <td>Get-Subscription-Attributes</td>
 201         <td>1.2</td>
 202         <td>0x0018</td>
 203         <td>Gets the attributes for a subscription.</td>
 204 </tr>
 205 <tr>
 206         <td>Get-Subscriptions</td>
 207         <td>1.2</td>
 208         <td>0x0019</td>
 209         <td>Gets the attributes for zero or more subscriptions.</td>
 210 </tr>
 211 <tr>
 212         <td>Renew-Subscription</td>
 213         <td>1.2</td>
 214         <td>0x001A</td>
 215         <td>Renews a subscription.</td>
 216 </tr>
 217 <tr>
 218         <td>Cancel-Subscription</td>
 219         <td>1.2</td>
 220         <td>0x001B</td>
 221         <td>Cancels a subscription.</td>
 222 </tr>
 223 <tr>
 224         <td>Get-Notifications</td>
 225         <td>1.2</td>
 226         <td>0x001C</td>
 227         <td>Get notification events for <tt>ippget</tt> subscriptions.</td>
 228 </tr>
 229 <tr>
 230         <td>Enable-Printer</td>
 231         <td>1.2</td>
 232         <td>0x0022</td>
 233         <td>Accepts jobs on a printer.</td>
 234 </tr>
 235 <tr>
 236         <td>Disable-Printer</td>
 237         <td>1.2</td>
 238         <td>0x0023</td>
 239         <td>Rejects jobs on a printer.</td>
 240 </tr>
 241 <tr>
 242         <td><a href='#CUPS_GET_DEFAULT'>CUPS-Get-Default</a></td>
 243         <td>1.0</td>
 244         <td>0x4001</td>
 245         <td>Get the default destination.</td>
 246 </tr>
 247 <tr>
 248         <td><a href='#CUPS_GET_PRINTERS'>CUPS-Get-Printers</a></td>
 249         <td>1.0</td>
 250         <td>0x4002</td>
 251         <td>Get all of the available printers.</td>
 252 </tr>
 253 <tr>
 254         <td><a href='#CUPS_ADD_MODIFY_PRINTER'>CUPS-Add-Modify-Printer</a></td>
 255         <td>1.0</td>
 256         <td>0x4003</td>
 257         <td>Add or modify a printer.</td>
 258 </tr>
 259 <tr>
 260         <td><a href='#CUPS_DELETE_PRINTER'>CUPS-Delete-Printer</a></td>
 261         <td>1.0</td>
 262         <td>0x4004</td>
 263         <td>Delete a printer.</td>
 264 </tr>
 265 <tr>
 266         <td><a href='#CUPS_GET_CLASSES'>CUPS-Get-Classes</a></td>
 267         <td>1.0</td>
 268         <td>0x4005</td>
 269         <td>Get all of the available printer classes.</td>
 270 </tr>
 271 <tr>
 272         <td><a href='#CUPS_ADD_MODIFY_CLASS'>CUPS-Add-Modify-Class</a></td>
 273         <td>1.0</td>
 274         <td>0x4006</td>
 275         <td>Add or modify a printer class.</td>
 276 </tr>
 277 <tr>
 278         <td><a href='#CUPS_DELETE_CLASS'>CUPS-Delete-Class</a></td>
 279         <td>1.0</td>
 280         <td>0x4007</td>
 281         <td>Delete a printer class.</td>
 282 </tr>
 283 <tr>
 284         <td><a href='#CUPS_ACCEPT_JOBS'>CUPS-Accept-Jobs</a></td>
 285         <td>1.0</td>
 286         <td>0x4008</td>
 287         <td>Accept jobs on a printer or printer class.</td>
 288 </tr>
 289 <tr>
 290         <td><a href='#CUPS_REJECT_JOBS'>CUPS-Reject-Jobs</a></td>
 291         <td>1.0</td>
 292         <td>0x4009</td>
 293         <td>Reject jobs on a printer or printer class.</td>
 294 </tr>
 295 <tr>
 296         <td><a href='#CUPS_SET_DEFAULT'>CUPS-Set-Default</a></td>
 297         <td>1.0</td>
 298         <td>0x400A</td>
 299         <td>Set the default destination.</td>
 300 </tr>
 301 <tr>
 302         <td><a href='#CUPS_GET_DEVICES'>CUPS-Get-Devices</a></td>
 303         <td>1.1</td>
 304         <td>0x400B</td>
 305         <td>Get all of the available devices.</td>
 306 </tr>
 307 <tr>
 308         <td><a href='#CUPS_GET_PPDS'>CUPS-Get-PPDs</a></td>
 309         <td>1.1</td>
 310         <td>0x400C</td>
 311         <td>Get all of the available PPDs.</td>
 312 </tr>
 313 <tr>
 314         <td><a href='#CUPS_MOVE_JOB'>CUPS-Move-Job</a></td>
 315         <td>1.1</td>
 316         <td>0x400D</td>
 317         <td>Move a job to a different printer.</td>
 318 </tr>
 319 <tr>
 320         <td><a href='#CUPS_AUTHENTICATE_JOB'>CUPS-Authenticate-Job</a></td>
 321         <td>1.2</td>
 322         <td>0x400E</td>
 323         <td>Authenticate a job for printing.</td>
 324 </tr>
 325 <tr>
 326         <td><a href='#CUPS_GET_PPD'>CUPS-Get-PPD</a></td>
 327         <td>1.3</td>
 328         <td>0x400F</td>
 329         <td>Get a PPD file.</td>
 330 </tr>
 331 <tr>
 332         <td><a href='#CUPS_GET_DOCUMENT'>CUPS-Get-Document</a></td>
 333         <td>1.4</td>
 334         <td>0x4027</td>
 335         <td>Get a document file from a job.</td>
 336 </tr>
 337 </tbody>
 338 </table></div>
 339
 340 <h2 class='title'><a name='OPERATIONS'>Operations</a></h2>
 341
 342 <p>The following sections describe the operations supported by CUPS.
 343 In the interest of brevity, operations which use only the standard
 344 IPP attributes are not described.
 345
 346 <h3 class='title'><a name='PRINT_JOB'>Print-Job Operation</a></h3>
 347
 348 <p>The Print-Job operation (0x0002) prints a file.
 349
 350 <h4>Print-Job Request</h4>
 351
 352 <p>The following groups of attributes are supplied as part of the
 353 Print-Job request:
 354
 355 <p>Group 1: Operation Attributes
 356
 357 <dl>
 358
 359         <dt>Natural Language and Character Set:
 360
 361         <dd>The "attributes-charset" and "attributes-natural-language"
 362         attributes as described in section 3.1.4.1 of the IPP Model and
 363         Semantics document.
 364
 365         <dt>"printer-uri" (uri):
 366
 367         <dd>The client MUST supply a URI for the specified printer.
 368
 369 </dl>
 370
 371 <p>Group 2: Job Template Attributes
 372
 373 <dl>
 374
 375         <dt>"auth-info" (1setOf text(MAX)):<span class='info'>CUPS 1.3</span>
 376
 377         <dd>The client OPTIONALLY supplies one or more authentication values as specified by the "auth-info-required" attribute.
 378
 379         <dt>"job-billing" (text(MAX)):<span class='info'>CUPS 1.1</span>
 380
 381         <dd>The client OPTIONALLY supplies a billing string that is logged
 382         with the page accounting information.
 383
 384         <dt>"job-sheets" (1setof type3 keyword | name(MAX)):<span class='info'>CUPS 1.1</span>
 385
 386         <dd>The client OPTIONALLY supplies one or two banner pages that
 387         are printed before and after any files in the print job. The
 388         name of "none" is reserved to indicate that no banner page
 389         should be printed. If the client does not specify this
 390         attribute then the value of the "job-sheets-default" printer
 391         object attribute is used.
 392
 393         <blockquote><b>Note:</b> Standard IPP only allows
 394         specification of a single job-sheets attribute
 395         value.</blockquote>
 396
 397         <dt>"media" (1setof type3 keyword | name(MAX)):
 398
 399         <dd>The client OPTIONALLY supplies one or more media attributes
 400         specifying the size, type, source, and color of the output
 401         media. If the client does not specify this attribute then the
 402         value of the "media-default" printer object attribute is used.
 403
 404         <blockquote><b>Note:</b> Standard IPP only allows
 405         specification of a single media attribute
 406         value.</blockquote>
 407
 408         <dt>Other Job Template Attributes
 409
 410 </dl>
 411
 412 <p>The Print-Job request is followed by a file to be printed.
 413
 414 <h4>Print-Job Response</h4>
 415
 416 <p>The following groups of attributes are send as part of the Print-Job
 417 Response:
 418
 419 <p>Group 1: Operation Attributes
 420
 421 <dl>
 422
 423         <dt>Status Message:
 424
 425         <dd>The standard response status message.
 426
 427         <dt>Natural Language and Character Set:
 428
 429         <dd>The "attributes-charset" and "attributes-natural-language"
 430         attributes as described in section 3.1.4.2 of the IPP Model and
 431         Semantics document.
 432
 433 </dl>
 434
 435 <p>Group 2: Job Attributes
 436
 437 <dl>
 438
 439         <dt>Standard Job Attributes
 440
 441 </dl>
 442
 443 <p>Group 3: Unsupported Attributes (status=client-eror-attributes-or-values-not-supported)
 444
 445 <dl>
 446
 447         <dt>auth-info-required (1setOf Type2 keyword)
 448
 449         <dd>The required authentication information.
 450
 451 </dl
 452
 453 <h3 class='title'><span class='info'>CUPS 1.1</span><a name='CREATE_JOB'>Create-Job Operation</a></h3>
 454
 455 <p>The Create-Job operation (0x0005) creates a new, empty print job.
 456
 457 <h4>Create-Job Request</h4>
 458
 459 <p>The following groups of attributes are supplied as part of the
 460 Create-Job request:
 461
 462 <p>Group 1: Operation Attributes
 463
 464 <dl>
 465
 466         <dt>Natural Language and Character Set:
 467
 468         <dd>The "attributes-charset" and "attributes-natural-language"
 469         attributes as described in section 3.1.4.1 of the IPP Model and
 470         Semantics document.
 471
 472         <dt>"printer-uri" (uri):
 473
 474         <dd>The client MUST supply a URI for the specified printer.
 475
 476 </dl>
 477
 478 <p>Group 2: Job Template Attributes
 479
 480 <dl>
 481
 482         <dt>"auth-info" (1setOf text(MAX)):<span class='info'>CUPS 1.3</span>
 483
 484         <dd>The client OPTIONALLY supplies one or more authentication values as specified by the "auth-info-required" attribute.
 485
 486         <dt>"job-billing" (text(MAX)):<span class='info'>CUPS 1.1</span>
 487
 488         <dd>The client OPTIONALLY supplies a billing string that is logged
 489         with the page accounting information.
 490
 491         <dt>"job-sheets" (1setof type3 keyword | name(MAX)):<span class='info'>CUPS 1.1</span>
 492
 493         <dd>The client OPTIONALLY supplies one or two banner pages that
 494         are printed before and after any files in the print job. The
 495         name of "none" is reserved to indicate that no banner page
 496         should be printed. If the client does not specify this
 497         attribute then the value of the "job-sheets-default" printer
 498         object attribute is used.
 499
 500         <blockquote><b>Note:</b> Standard IPP only allows
 501         specification of a single job-sheets attribute
 502         value.</blockquote>
 503
 504         <dt>"media" (1setof type3 keyword | name(MAX)):
 505
 506         <dd>The client OPTIONALLY supplies one or more media attributes
 507         specifying the size, type, source, and color of the output
 508         media. If the client does not specify this attribute then the
 509         value of the "media-default" printer object attribute is used.
 510
 511         <blockquote><b>Note:</b> Standard IPP only allows
 512         specification of a single media attribute
 513         value.</blockquote>
 514
 515         <dt>Standard Job Template Attributes
 516
 517 </dl>
 518
 519 <h4>Create-Job Response</h4>
 520
 521 <p>The following groups of attributes are send as part of the
 522 Create-Job Response:
 523
 524 <p>Group 1: Operation Attributes
 525
 526 <dl>
 527
 528         <dt>Status Message:
 529
 530         <dd>The standard response status message.
 531
 532         <dt>Natural Language and Character Set:
 533
 534         <dd>The "attributes-charset" and "attributes-natural-language"
 535         attributes as described in section 3.1.4.2 of the IPP Model and
 536         Semantics document.
 537
 538 </dl>
 539
 540 <p>Group 2: Job Attributes
 541
 542 <dl>
 543
 544         <dt>Standard Job Attributes
 545
 546 </dl>
 547
 548 <p>Group 3: Unsupported Attributes (status=client-eror-attributes-or-values-not-supported)
 549
 550 <dl>
 551
 552         <dt>auth-info-required (1setOf Type2 keyword)
 553
 554         <dd>The required authentication information.
 555
 556 </dl
 557
 558 <h3 class='title'><a name='CANCEL_JOB'>Set-Job-Attributes Operation</a></h3>
 559
 560 <p>The Cancel-Job operation (0x0008) cancels the specified job. CUPS 1.4 adds
 561 a new <tt>purge-job (boolean)</tt> attribute that allows you to purge both
 562 active and completed jobs, removing all history and document files for the
 563 job as well.
 564
 565 <h4>Cancel-Job Request</h4>
 566
 567 <p>The following groups of attributes are supplied as part of the
 568 Set-Job-Attributes request:
 569
 570 <p>Group 1: Operation Attributes
 571
 572 <dl>
 573
 574         <dt>Natural Language and Character Set:
 575
 576         <dd>The "attributes-charset" and "attributes-natural-language"
 577         attributes as described in section 3.1.4.1 of the IPP Model and
 578         Semantics document.
 579
 580         <dt>"printer-uri" (uri) and "job-id" (integer)
 581         <br><i>OR</i>
 582         <br>"job-uri":
 583
 584         <dd>The client MUST supply a URI for the specified printer and
 585         a job ID number, or the job URI.
 586
 587         <dt><span class="info">CUPS 1.4</span>"purge-job" (boolean):
 588
 589         <dd>The client OPTIONALLY supplies this attribute. When true,
 590         all job files (history and document) are purged. The default
 591         is false, leading to the standard IPP behavior.
 592
 593 </dl>
 594
 595 <h4>Cancel-Job Response</h4>
 596
 597 <p>The following groups of attributes are send as part of the Cancel-Job
 598 Response:
 599
 600 <p>Group 1: Operation Attributes
 601
 602 <dl>
 603
 604         <dt>Status Message:
 605
 606         <dd>The standard response status message.
 607
 608         <dt>Natural Language and Character Set:
 609
 610         <dd>The "attributes-charset" and "attributes-natural-language"
 611         attributes as described in section 3.1.4.2 of the IPP Model and
 612         Semantics document.
 613
 614 </dl>
 615
 616 <h3 class='title'><a name='PURGE_JOBS'>Purge-Jobs Operation</a></h3>
 617
 618 <p>The Purge-Jobs operation (0x0012) cancels all of the jobs on a
 619 given destination and optionally removes all history and document
 620 files for the jobs as well.
 621
 622 <h4>Purge-Jobs Request</h4>
 623
 624 <p>The following groups of attributes are supplied as part of the
 625 Purge-Jobs request:
 626
 627 <p>Group 1: Operation Attributes
 628
 629 <dl>
 630
 631         <dt>Natural Language and Character Set:
 632
 633         <dd>The "attributes-charset" and "attributes-natural-language"
 634         attributes as described in section 3.1.4.1 of the IPP Model and
 635         Semantics document.
 636
 637         <dt>"printer-uri" (uri):
 638
 639         <dd>The client MUST supply a URI for the specified printer or
 640         "ipp://.../printers" for all printers and classes.
 641
 642         <dt><span class="info">CUPS 1.2</span>"purge-jobs" (boolean):
 643
 644         <dd>The client OPTIONALLY supplies this attribute to specify
 645         whether the jobs are purged (true) or just canceled (false).
 646         The default is true.
 647
 648 </dl>
 649
 650 <h4>Purge-Jobs Response</h4>
 651
 652 <p>The following groups of attributes are send as part of the Purge-Jobs
 653 Response:
 654
 655 <p>Group 1: Operation Attributes
 656
 657 <dl>
 658
 659         <dt>Status Message:
 660
 661         <dd>The standard response status message.
 662
 663         <dt>Natural Language and Character Set:
 664
 665         <dd>The "attributes-charset" and "attributes-natural-language"
 666         attributes as described in section 3.1.4.2 of the IPP Model and
 667         Semantics document.
 668
 669 </dl>
 670
 671 <h3 class='title'><span class='info'>CUPS 1.1</span><a name='SET_JOB_ATTRIBUTES'>Set-Job-Attributes Operation</a></h3>
 672
 673 <p>The Set-Job-Attributes operation (0x0014) changes the attributes of
 674 an active (not completed) job.
 675
 676 <h4>Set-Job-Attributes Request</h4>
 677
 678 <p>The following groups of attributes are supplied as part of the
 679 Set-Job-Attributes request:
 680
 681 <p>Group 1: Operation Attributes
 682
 683 <dl>
 684
 685         <dt>Natural Language and Character Set:
 686
 687         <dd>The "attributes-charset" and "attributes-natural-language"
 688         attributes as described in section 3.1.4.1 of the IPP Model and
 689         Semantics document.
 690
 691         <dt>"printer-uri" (uri) and "job-id" (integer)
 692         <br><i>OR</i>
 693         <br>"job-uri":
 694
 695         <dd>The client MUST supply a URI for the specified printer and
 696         a job ID number, or the job URI.
 697
 698 </dl>
 699
 700 <p>Group 2: Job Template Attributes
 701
 702 <dl>
 703
 704         <dt>"job-sheets" (1setof type3 keyword | name(MAX)):<span class='info'>CUPS 1.1</span>
 705
 706         <dd>The client OPTIONALLY supplies one or two banner pages that
 707         are printed before and after any files in the print job. The
 708         name of "none" is reserved to indicate that no banner page
 709         should be printed. If the client does not specify this
 710         attribute then the value of the "job-sheets-default" printer
 711         object attribute is used.
 712
 713         <blockquote><b>Note:</b> Standard IPP only allows
 714         specification of a single job-sheets attribute
 715         value.</blockquote>
 716
 717         <dt>"media" (1setof type3 keyword | name(MAX)):
 718
 719         <dd>The client OPTIONALLY supplies one or more media attributes
 720         specifying the size, type, source, and color of the output
 721         media. If the client does not specify this attribute then the
 722         value of the "media-default" printer object attribute is used.
 723
 724         <blockquote><b>Note:</b> Standard IPP only allows
 725         specification of a single media attribute
 726         value.</blockquote>
 727
 728         <dt>Other Job Template Attributes
 729
 730 </dl>
 731
 732 <h4>Set-Job-Attributes Response</h4>
 733
 734 <p>The following groups of attributes are send as part of the Set-Job-Attributes
 735 Response:
 736
 737 <p>Group 1: Operation Attributes
 738
 739 <dl>
 740
 741         <dt>Status Message:
 742
 743         <dd>The standard response status message.
 744
 745         <dt>Natural Language and Character Set:
 746
 747         <dd>The "attributes-charset" and "attributes-natural-language"
 748         attributes as described in section 3.1.4.2 of the IPP Model and
 749         Semantics document.
 750
 751 </dl>
 752
 753 <h3 class='title'><span class='info'>CUPS 1.2</span><a
 754 name='CREATE_PRINTER_SUBSCRIPTION'>Create-Printer-Subscription</a></h3>
 755
 756 <p>The Create-Printer-Subscription operation (0x0016) creates a
 757 subscription for printer or server event notifications. CUPS
 758 provides several additional events in addition to the standard
 759 events in the IPP notifications specification.</p>
 760
 761 <h4>Create-Printer-Subscription Request</h4>
 762
 763 <p>The following groups of attributes are supplied as part of the
 764 request:</p>
 765
 766 <p>Group 1: Operation Attributes</p>
 767
 768 <dl>
 769
 770         <dt>Natural Language and Character Set:
 771
 772         <dd>The "attributes-charset" and "attributes-natural-language"
 773         attributes as described in section 3.1.4.1 of the IPP Model and
 774         Semantics document.
 775
 776         <dt>"printer-uri" (uri):
 777
 778         <dd>The printer
 779         (<tt>ipp://server/printers/printername</tt>), class
 780         (<tt>ipp://server/classes/classname</tt>), or server
 781         (<tt>ipp://server/</tt>) URI for event notifications.
 782
 783         <dt>"notify-events" (1setOf keyword):
 784
 785         <dd>The events to monitor. In addition to the standard
 786         events, CUPS adds the following keywords:
 787         <ul>
 788
 789                 <li><tt>printer-added</tt> - Get notified
 790                 whenever a printer or class is added</li>
 791
 792                 <li><tt>printer-deleted</tt> - Get notified
 793                 whenever a printer or class is deleted</li>
 794
 795                 <li><tt>printer-modified</tt> - Get notified
 796                 whenever a printer or class is modified</li>
 797
 798                 <li><tt>server-audit</tt> - Get notified when a
 799                 security condition occurs</li>
 800
 801                 <li><tt>server-restarted</tt> - Get notified when
 802                 the server is restarted</li>
 803
 804                 <li><tt>server-started</tt> - Get notified when
 805                 the server is started</li>
 806
 807                 <li><tt>server-stopped</tt> - Get notified when
 808                 the server is stopped</li>
 809
 810         </ul>
 811
 812 </dl>
 813
 814 <h4>Create-Printer-Subscription Response</h4>
 815
 816 <p>The following groups of attributes are send as part of the
 817 response:</p>
 818
 819 <p>Group 1: Operation Attributes</p>
 820
 821 <dl>
 822
 823         <dt>Status Message:
 824
 825         <dd>The standard response status message.
 826
 827         <dt>Natural Language and Character Set:
 828
 829         <dd>The "attributes-charset" and "attributes-natural-language"
 830         attributes as described in section 3.1.4.2 of the IPP Model and
 831         Semantics document.
 832
 833 </dl>
 834
 835 <p>Group 2: Subscription Object Attributes</p>
 836
 837 <dl>
 838
 839         <dt>"subscription-id" (integer):
 840
 841         <dd>The subscription number.
 842
 843 </dl>
 844
 845 <h3 class='title'><a name='CUPS_GET_DEFAULT'>CUPS-Get-Default Operation</a></h3>
 846
 847 <p>The CUPS-Get-Default operation (0x4001) returns the default printer
 848 URI and attributes.
 849
 850 <h4>CUPS-Get-Default Request</h4>
 851
 852 <p>The following groups of attributes are supplied as part of the
 853 CUPS-Get-Default 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"
 862         attributes as described in section 3.1.4.1 of the IPP Model and
 863         Semantics document.
 864
 865         <dt>"requested-attributes" (1setOf keyword) :
 866
 867         <dd>The client OPTIONALLY supplies a set of attribute names
 868         and/or attribute group names in whose values the requester is
 869         interested. If the client omits this attribute, the server
 870         responds as if this attribute had been supplied with a value of
 871         'all'.
 872
 873 </dl>
 874
 875 <h4>CUPS-Get-Default Response</h4>
 876
 877 <p>The following groups of attributes are send as part of the
 878 CUPS-Get-Default Response:
 879
 880 <p>Group 1: Operation Attributes
 881
 882 <dl>
 883
 884         <dt>Status Message:
 885
 886         <dd>The standard response status message.
 887
 888         <dt>Natural Language and Character Set:
 889
 890         <dd>The "attributes-charset" and "attributes-natural-language"
 891         attributes as described in section 3.1.4.2 of the IPP Model and
 892         Semantics document.
 893
 894 </dl>
 895
 896 <p>Group 2: Printer Object Attributes
 897
 898 <dl>
 899
 900         <dt>The set of requested attributes and their current values.
 901
 902 </dl>
 903
 904 <h3 class='title'><a name='CUPS_GET_PRINTERS'>CUPS-Get-Printers Operation</a></h3>
 905
 906 <p>The CUPS-Get-Printers operation (0x4002) returns the printer
 907 attributes for every printer known to the system. This may include
 908 printers that are not served directly by the server.
 909
 910 <h4>CUPS-Get-Printers Request</h4>
 911
 912 <p>The following groups of attributes are supplied as part of the
 913 CUPS-Get-Printers request:
 914
 915 <p>Group 1: Operation Attributes
 916
 917 <dl>
 918
 919         <dt>Natural Language and Character Set:
 920
 921         <dd>The "attributes-charset" and "attributes-natural-language"
 922         attributes as described in section 3.1.4.1 of the IPP Model and
 923         Semantics document.
 924
 925         <dt>"limit" (integer (1:MAX)):
 926
 927         <dd>The client OPTIONALLY supplies this attribute limiting the
 928         number of printers that are returned.
 929
 930         <dt>"printer-info" (text(127)):<span class='info'>CUPS 1.1</span>
 931
 932         <dd>The client OPTIONALLY supplies this attribute to
 933         select which printers are returned.
 934
 935         <dt>"printer-location" (text(127)): <span class='info'>CUPS 1.1.7</span>
 936
 937         <dd>The client OPTIONALLY supplies this attribute to
 938         select which printers are returned.
 939
 940         <dt>"printer-type" (type2 enum): <span class='info'>CUPS 1.1.7</span>
 941
 942         <dd>The client OPTIONALLY supplies a printer type enumeration to
 943         select which printers are returned.
 944
 945         <dt>"printer-type-mask" (type2 enum): <span class='info'>CUPS 1.1.7</span>
 946
 947         <dd>The client OPTIONALLY supplies a printer type mask
 948         enumeration to select which bits are used in the "printer-type"
 949         attribute.
 950
 951         <dt>"requested-attributes" (1setOf keyword) :
 952
 953         <dd>The client OPTIONALLY supplies a set of attribute names
 954         and/or attribute group names in whose values the requester is
 955         interested. If the client omits this attribute, the server
 956         responds as if this attribute had been supplied with a value of
 957         'all'.
 958
 959 </dl>
 960
 961 <h4>CUPS-Get-Printers Response</h4>
 962
 963 <p>The following groups of attributes are send as part of the
 964 CUPS-Get-Printers Response:
 965
 966 <p>Group 1: Operation Attributes
 967
 968 <dl>
 969
 970         <dt>Status Message:
 971
 972         <dd>The standard response status message.
 973
 974         <dt>Natural Language and Character Set:
 975
 976         <dd>The "attributes-charset" and "attributes-natural-language"
 977         attributes as described in section 3.1.4.2 of the IPP Model and
 978         Semantics document.
 979
 980 </dl>
 981
 982 <p>Group 2: Printer Object Attributes
 983
 984 <dl>
 985
 986         <dt>The set of requested attributes and their current values for
 987         each printer.
 988
 989 </dl>
 990
 991 <h3 class='title'><a name='CUPS_ADD_MODIFY_PRINTER'>CUPS-Add-Modify-Printer Operation</a></h3>
 992
 993 <p>The CUPS-Add-Modify-Printer operation (0x4003) adds a new printer or
 994 modifies an existing printer on the system.
 995
 996 <h4>CUPS-Add-Modify-Printer Request</h4>
 997
 998 <p>The following groups of attributes are supplied as part of the
 999 CUPS-Add-Modify-Printer request:
1000
1001 <p>Group 1: Operation Attributes
1002
1003 <dl>
1004
1005         <dt>Natural Language and Character Set:
1006
1007         <dd>The "attributes-charset" and "attributes-natural-language"
1008         attributes as described in section 3.1.4.1 of the IPP Model and
1009         Semantics document.
1010
1011         <dt>"printer-uri" (uri):
1012
1013         <dd>The client MUST supply a URI for the specified printer.
1014
1015 </dl>
1016
1017 <p>Group 2: Printer Object Attributes
1018
1019 <dl>
1020
1021         <dt>"auth-info-required" (1setOf type2 keyword):<span class='info'>CUPS 1.3</span>
1022
1023         <dd>The client OPTIONALLY supplies one or more authentication keywords that are required to communicate with the printer/remote queue.
1024
1025         <dt>"job-sheets-default" (1setOf name(127)): <span
1026         class='info'>CUPS 1.1.7</span>
1027
1028         <dd>The client OPTIONALLY supplies one or two banner page
1029         names that are printed before and after files in a job.
1030         The reserved name "none" is used to specify that no
1031         banner page should be printed.
1032
1033         <dt>"device-uri" (uri):
1034
1035         <dd>The client OPTIONALLY supplies a device URI for the
1036         specified printer.
1037
1038         <dt>"port-monitor" (name(127)):
1039
1040         <dd>The client OPTIONALLY supplies a port monitor name for the
1041         specified printer.
1042
1043         <dt>"ppd-name" (name(127)):
1044
1045         <dd>The client OPTIONALLY supplies a PPD name for the specified
1046         printer.
1047
1048         <dt>"printer-is-accepting-jobs" (boolean):
1049
1050         <dd>The client OPTIONALLY supplies this boolean attribute
1051         indicating whether or not the printer object should accept new jobs.
1052
1053         <dt>"printer-info" (text(127)):
1054
1055         <dd>The client OPTIONALLY supplies this attribute indicating the
1056         printer information string.
1057
1058         <dt>"printer-location" (text(127)):
1059
1060         <dd>The client OPTIONALLY supplies this attribute indicating a
1061         textual location of the printer.
1062
1063         <dt>"printer-more-info" (uri):
1064
1065         <dd>The client OPTIONALLY supplies this attribute indicating a
1066         URI for additional printer information.
1067
1068         <dt>"printer-state" (type2 enum):
1069
1070         <dd>The client OPTIONALLY supplies this attribute indicating the
1071         initial/current state of the printer. Only the "idle" and "stopped"
1072         enumerations are recognized.
1073
1074         <dt>"printer-state-message" (text(MAX)):
1075
1076         <dd>The client OPTIONALLY supplies this attribute indicating a
1077         textual reason for the current printer state.
1078
1079         <dt>"requesting-user-name-allowed" (1setof name(127) | delete)
1080         <br><i>OR</i>
1081         <br>"requesting-user-name-denied" (1setof name(127) | delete):
1082
1083         <dd>The client OPTIONALLY supplies one of these attributes to
1084         specify an access control list for incoming print jobs. To allow
1085         all users access to a printer, use the delete tag for the
1086         attribute value.
1087
1088 </dl>
1089
1090 <p>The CUPS-Add-Modify-Printer request can optionally be followed by a PPD
1091 file or System V interface script to be used for the printer. The
1092 "ppd-name" attribute overrides any file that is attached to the end of
1093 the request with a local CUPS PPD file.
1094
1095 <h4>CUPS-Add-Modify-Printer Response</h4>
1096
1097 <p>The following groups of attributes are send as part of the
1098 CUPS-Add-Modify-Printer Response:
1099
1100 <p>Group 1: Operation Attributes
1101
1102 <dl>
1103
1104         <dt>Status Message:
1105
1106         <dd>The standard response status message.
1107
1108         <dt>Natural Language and Character Set:
1109
1110         <dd>The "attributes-charset" and "attributes-natural-language"
1111         attributes as described in section 3.1.4.2 of the IPP Model and
1112         Semantics document.
1113
1114 </dl>
1115
1116 <h3 class='title'><a name='CUPS_DELETE_PRINTER'>CUPS-Delete-Printer Operation</a></h3>
1117
1118 <p>The CUPS-Delete-Printer operation (0x4004) removes an existing
1119 printer from the system.
1120
1121 <h4>CUPS-Delete-Printer Request</h4>
1122
1123 <p>The following groups of attributes are supplied as part of the
1124 CUPS-Delete-Printer request:
1125
1126 <p>Group 1: Operation Attributes
1127
1128 <dl>
1129
1130         <dt>Natural Language and Character Set:
1131
1132         <dd>The "attributes-charset" and "attributes-natural-language"
1133         attributes as described in section 3.1.4.1 of the IPP Model and
1134         Semantics document.
1135
1136         <dt>"printer-uri" (uri):
1137
1138         <dd>The client MUST supply a URI for the specified printer.
1139
1140 </dl>
1141
1142 <h4>CUPS-Delete-Printer Response</h4>
1143
1144 <p>The following groups of attributes are send as part of the
1145 CUPS-Delete-Printer Response:
1146
1147 <p>Group 1: Operation Attributes
1148
1149 <dl>
1150
1151         <dt>Status Message:
1152
1153         <dd>The standard response status message.
1154
1155         <dt>Natural Language and Character Set:
1156
1157         <dd>The "attributes-charset" and "attributes-natural-language"
1158         attributes as described in section 3.1.4.2 of the IPP Model and
1159         Semantics document.
1160
1161 </dl>
1162
1163 <h3 class='title'><a name='CUPS_GET_CLASSES'>CUPS-Get-Classes Operation</a></h3>
1164
1165 <p>The CUPS-Get-Classes operation (0x4005) returns the printer
1166 attributes for every printer class known to the system. This may
1167 include printer classes that are not served directly by the server.
1168
1169 <h4>CUPS-Get-Classes Request</h4>
1170
1171 <p>The following groups of attributes are supplied as part of the
1172 CUPS-Get-Classes request:
1173
1174 <p>Group 1: Operation Attributes
1175
1176 <dl>
1177
1178         <dt>Natural Language and Character Set:
1179
1180         <dd>The "attributes-charset" and "attributes-natural-language"
1181         attributes as described in section 3.1.4.1 of the IPP Model and
1182         Semantics document.
1183
1184         <dt>"limit" (integer (1:MAX)):
1185
1186         <dd>The client OPTIONALLY supplies this attribute limiting the
1187         number of printer classes that are returned.
1188
1189         <dt>"printer-info" (text(127)): <span class='info'>CUPS 1.1.7</span>
1190         <dd>The client OPTIONALLY supplies this attribute to
1191         select which printer classes are returned.
1192
1193         <dt>"printer-location" (text(127)): <span class='info'>CUPS 1.1.7</span>
1194         <dd>The client OPTIONALLY supplies this attribute to
1195         select which printer classes are returned.
1196
1197         <dt>"printer-type" (type2 enum): <span class='info'>CUPS 1.1.7</span>
1198         <dd>The client OPTIONALLY supplies a printer type enumeration to
1199         select which printer classes are returned.
1200
1201         <dt>"printer-type-mask" (type2 enum): <span class='info'>CUPS 1.1.7</span>
1202         <dd>The client OPTIONALLY supplies a printer type mask
1203         enumeration to select which bits are used in the "printer-type"
1204         attribute.
1205
1206         <dt>"requested-attributes" (1setOf keyword) :
1207
1208         <dd>The client OPTIONALLY supplies a set of attribute names
1209         and/or attribute group names in whose values the requester is
1210         interested. If the client omits this attribute, the server responds as
1211         if this attribute had been supplied with a value of 'all'.
1212
1213 </dl>
1214
1215 <h4>CUPS-Get-Classes Response</h4>
1216
1217 <p>The following groups of attributes are send as part of the
1218 CUPS-Get-Classes Response:
1219
1220 <p>Group 1: Operation Attributes
1221
1222 <dl>
1223
1224         <dt>Status Message:
1225
1226         <dd>The standard response status message.
1227
1228         <dt>Natural Language and Character Set:
1229
1230         <dd>The "attributes-charset" and "attributes-natural-language"
1231         attributes as described in section 3.1.4.2 of the IPP Model and
1232         Semantics document.
1233
1234 </dl>
1235
1236 <p>Group 2: Printer Class Object Attributes
1237
1238 <dl>
1239
1240         <dt>The set of requested attributes and their current values for
1241         each printer class.
1242
1243 </dl>
1244
1245 <h3 class='title'><a name='CUPS_ADD_MODIFY_CLASS'>CUPS-Add-Modify-Class Operation</a></h3>
1246
1247 <p>The CUPS-Add-Modify-Class operation (0x4006) adds a new printer class or
1248 modifies and existing printer class on the system.
1249
1250 <h4>CUPS-Add-Modify-Class Request</h4>
1251
1252 <p>The following groups of attributes are supplied as part of the
1253 CUPS-Add-Modify-Class request:
1254
1255 <p>Group 1: Operation Attributes
1256
1257 <dl>
1258
1259         <dt>Natural Language and Character Set:
1260
1261         <dd>The "attributes-charset" and "attributes-natural-language"
1262         attributes as described in section 3.1.4.1 of the IPP Model and
1263         Semantics document.
1264
1265         <dt>"printer-uri" (uri):
1266
1267         <dd>The client MUST supply a URI for the specified printer class.
1268
1269 </dl>
1270
1271 <p>Group 2: Printer Object Attributes
1272
1273 <dl>
1274
1275         <dt>"auth-info-required" (1setOf type2 keyword):<span class='info'>CUPS 1.3</span>
1276
1277         <dd>The client OPTIONALLY supplies one or more authentication keywords that are required to communicate with the printer/remote queue.
1278
1279         <dt>"member-uris" (1setof uri):
1280
1281         <dd>The client OPTIONALLY supplies the "member-uris" set
1282         specifying the printers and printer classes that are part of the class.
1283
1284         <dt>"printer-is-accepting-jobs" (boolean):
1285
1286         <dd>The client OPTIONALLY supplies this boolean attribute
1287         indicating whether or not the class object should accept new jobs.
1288
1289         <dt>"printer-info" (text(127)):
1290
1291         <dd>The client OPTIONALLY supplies this attribute indicating the
1292         printer information string.
1293
1294         <dt>"printer-location" (text(127)):
1295
1296         <dd>The client OPTIONALLY supplies this attribute indicating a
1297         textual location of the class.
1298
1299         <dt>"printer-more-info" (uri):
1300
1301         <dd>The client OPTIONALLY supplies this attribute indicating a
1302         URI for additional class information.
1303
1304         <dt>"printer-state" (type2 enum):
1305
1306         <dd>The client OPTIONALLY supplies this attribute indicating the
1307         initial/current state of the class. Only the "idle" and "stopped"
1308         enumerations are recognized.
1309
1310         <dt>"printer-state-message" (text(MAX)):
1311
1312         <dd>The client OPTIONALLY supplies this attribute indicating a
1313         textual reason for the current class state.
1314
1315         <dt>"requesting-user-name-allowed" (1setof name(127))
1316         <br><i>OR</i>
1317         <br>"requesting-user-name-denied" (1setof name(127)):
1318
1319         <dd>The client OPTIONALLY supplies one of these attributes to
1320         specify an access control list for incoming print jobs. To allow
1321         all users access to a class, use the delete tag for the
1322         attribute value.
1323
1324 </dl>
1325
1326 <h4>CUPS-Add-Modify-Class Response</h4>
1327
1328 <p>The following groups of attributes are send as part of the CUPS-Add-Modify-Class Response:
1329
1330 <p>Group 1: Operation Attributes
1331
1332 <dl>
1333
1334         <dt>Status Message:
1335
1336         <dd>The standard response status message.
1337
1338         <dt>Natural Language and Character Set:
1339
1340         <dd>The "attributes-charset" and "attributes-natural-language"
1341         attributes as described in section 3.1.4.2 of the IPP Model and
1342         Semantics document.
1343
1344 </dl>
1345
1346 <h3 class='title'><a name='CUPS_DELETE_CLASS'>CUPS-Delete-Class Operation</a></h3>
1347
1348 <p>The CUPS-Delete-Class operation (0x4007) removes an existing printer
1349 class from the system.
1350
1351 <h4>CUPS-Delete-Class Request</h4>
1352
1353 <p>The following groups of attributes are supplied as part of the
1354 CUPS-Delete-Class request:
1355
1356 <p>Group 1: Operation Attributes
1357
1358 <dl>
1359
1360         <dt>Natural Language and Character Set:
1361
1362         <dd>The "attributes-charset" and "attributes-natural-language"
1363         attributes as described in section 3.1.4.1 of the IPP Model and
1364         Semantics document.
1365
1366         <dt>"printer-uri" (uri):
1367
1368         <dd>The client MUST supply a URI for the specified printer class.
1369
1370 </dl>
1371
1372 <h4>CUPS-Delete-Class Response</h4>
1373
1374 <p>The following groups of attributes are send as part of the
1375 CUPS-Delete-Class Response:
1376
1377 <p>Group 1: Operation Attributes
1378
1379 <dl>
1380
1381         <dt>Status Message:
1382
1383         <dd>The standard response status message.
1384
1385         <dt>Natural Language and Character Set:
1386
1387         <dd>The "attributes-charset" and "attributes-natural-language"
1388         attributes as described in section 3.1.4.2 of the IPP Model and
1389         Semantics document.
1390
1391 </dl>
1392
1393 <h3 class='title'><a name='CUPS_ACCEPT_JOBS'>CUPS-Accept-Jobs Operation</a></h3>
1394
1395 <p>The CUPS-Accept-Jobs operation (0x4008) sets the
1396 "printer-is-accepting-jobs" attribute to true for the specified printer
1397 or printer class.
1398
1399 <h4>CUPS-Accept-Jobs Request</h4>
1400
1401 <p>The following groups of attributes are supplied as part of the
1402 CUPS-Accept-Jobs request:
1403
1404 <p>Group 1: Operation Attributes
1405
1406 <dl>
1407
1408         <dt>Natural Language and Character Set:
1409
1410         <dd>The "attributes-charset" and "attributes-natural-language"
1411         attributes as described in section 3.1.4.1 of the IPP Model and
1412         Semantics document.
1413
1414         <dt>"printer-uri" (uri):
1415
1416         <dd>The client MUST supply a URI for the specified printer or printer class.
1417
1418 </dl>
1419
1420 <h4>CUPS-Accept-Jobs Response</h4>
1421
1422 <p>The following groups of attributes are send as part of the
1423 CUPS-Accept-Jobs Response:
1424
1425 <p>Group 1: Operation Attributes
1426
1427 <dl>
1428
1429         <dt>Status Message:
1430
1431         <dd>The standard response status message.
1432
1433         <dt>Natural Language and Character Set:
1434
1435         <dd>The "attributes-charset" and "attributes-natural-language"
1436         attributes as described in section 3.1.4.2 of the IPP Model and
1437         Semantics document.
1438
1439 </dl>
1440
1441 <h3 class='title'><a name='CUPS_REJECT_JOBS'>CUPS-Reject-Jobs Operation</a></h3>
1442
1443 <p>The CUPS-Reject-Jobs operation (0x4009) sets
1444 the"printer-is-accepting-jobs" attribute to false for the specified
1445 printer or printer class.
1446
1447 <h4>CUPS-Reject-Jobs Request</h4>
1448
1449 <p>The following groups of attributes are supplied as part of the
1450 CUPS-Reject-Jobs request:
1451
1452 <p>Group 1: Operation Attributes
1453
1454 <dl>
1455
1456         <dt>Natural Language and Character Set:
1457
1458         <dd>The "attributes-charset" and "attributes-natural-language"
1459         attributes as described in section 3.1.4.1 of the IPP Model and
1460         Semantics document.
1461
1462         <dt>"printer-uri" (uri):
1463
1464         <dd>The client MUST supply a URI for the specified printer or printer class.
1465
1466 </dl>
1467
1468 <p>Group 2: Printer Object Attributes
1469
1470 <dl>
1471
1472         <dt>"printer-state-message" (text(MAX)):
1473
1474         <dd>The client OPTIONALLY supplies this attribute indicating a
1475         textual reason for the current printer state.
1476
1477 </dl>
1478
1479 <h4>CUPS-Reject-Jobs Response</h4>
1480
1481 <p>The following groups of attributes are send as part of the
1482 CUPS-Reject-Jobs Response:
1483
1484 <p>Group 1: Operation Attributes
1485
1486 <dl>
1487
1488         <dt>Status Message:
1489
1490         <dd>The standard response status message.
1491
1492         <dt>Natural Language and Character Set:
1493
1494         <dd>The "attributes-charset" and "attributes-natural-language"
1495         attributes as described in section 3.1.4.2 of the IPP Model and
1496         Semantics document.
1497
1498 </dl>
1499
1500 <h3 class='title'><a name='CUPS_SET_DEFAULT'>CUPS-Set-Default Operation</a></h3>
1501
1502 <p>The CUPS-Set-Default operation (0x400A) sets the default printer
1503 destination for all clients when a resource name of "/printers" is
1504 specified.
1505
1506 <h4>CUPS-Set-Default Request</h4>
1507
1508 <p>The following groups of attributes are supplied as part of the
1509 CUPS-Set-Default request:
1510
1511 <p>Group 1: Operation Attributes
1512
1513 <dl>
1514
1515         <dt>Natural Language and Character Set:
1516
1517         <dd>The "attributes-charset" and "attributes-natural-language"
1518         attributes as described in section 3.1.4.1 of the IPP Model and
1519         Semantics document.
1520
1521         <dt>"printer-uri" (uri):
1522
1523         <dd>The client MUST supply a URI for the specified printer or
1524         printer class.
1525
1526 </dl>
1527
1528 <h4>CUPS-Set-Default Response</h4>
1529
1530 <p>The following groups of attributes are send as part of the
1531 CUPS-Set-Default Response:
1532
1533 <p>Group 1: Operation Attributes
1534
1535 <dl>
1536
1537         <dt>Status Message:
1538
1539         <dd>The standard response status message.
1540
1541         <dt>Natural Language and Character Set:
1542
1543         <dd>The "attributes-charset" and "attributes-natural-language"
1544         attributes as described in section 3.1.4.2 of the IPP Model and
1545         Semantics document.
1546
1547 </dl>
1548
1549 <h3 class='title'><span class='info'>CUPS 1.1</span><a name='CUPS_GET_DEVICES'>CUPS-Get-Devices Operation</a></h3>
1550
1551 <p>The CUPS-Get-Devices operation (0x400B) returns all of the
1552 supported device-uri's for the server.</p>
1553
1554 <h4>CUPS-Get-Devices Request</h4>
1555
1556 <p>The following groups of attributes are supplied as part of the
1557 CUPS-Get-Devices request:
1558
1559 <p>Group 1: Operation Attributes
1560
1561 <dl>
1562
1563         <dt>Natural Language and Character Set:
1564
1565         <dd>The "attributes-charset" and "attributes-natural-language"
1566         attributes as described in section 3.1.4.1 of the IPP Model and
1567         Semantics document.
1568
1569         <dt>"device-class" (type1 keyword):
1570
1571         <dd>The client OPTIONALLY supplies a device class keyword to select
1572         which devices are returned.
1573
1574         <dt>"limit" (integer (1:MAX)):
1575
1576         <dd>The client OPTIONALLY supplies this attribute limiting the number of
1577         devices that are returned.
1578
1579         <dt>"requested-attributes" (1setOf keyword) :
1580
1581         <dd>The client OPTIONALLY supplies a set of attribute names and/or
1582         attribute group names in whose values the requester is interested. If
1583         the client omits this attribute, the server responds as if this
1584         attribute had been supplied with a value of 'all'.
1585
1586 </dl>
1587
1588 <h4>CUPS-Get-Devices Response</h4>
1589
1590 <p>The following groups of attributes are send as part of the
1591 CUPS-Get-Devices Response:
1592
1593 <p>Group 1: Operation Attributes
1594
1595 <dl>
1596
1597         <dt>Status Message:
1598
1599         <dd>The standard response status message.
1600
1601         <dt>Natural Language and Character Set:
1602
1603         <dd>The "attributes-charset" and "attributes-natural-language"
1604         attributes as described in section 3.1.4.2 of the IPP Model and
1605         Semantics document.
1606
1607 </dl>
1608
1609 <p>Group 2: Device Object Attributes
1610
1611 <dl>
1612
1613         <dt>The set of requested attributes and their current values for
1614         each device.
1615
1616 </dl>
1617
1618 <h3 class='title'><span class='info'>CUPS 1.1</span><a name='CUPS_GET_PPDS'>CUPS-Get-PPDs Operation</a></h3>
1619
1620 <p>The CUPS-Get-PPDs operation (0x400C) returns all of the
1621 locally available PPD files on the system.</p>
1622
1623 <h4>CUPS-Get-PPDs Request</h4>
1624
1625 <p>The following groups of attributes are supplied as part of the
1626 CUPS-Get-PPDs request:
1627
1628 <p>Group 1: Operation Attributes
1629
1630 <dl>
1631
1632         <dt>Natural Language and Character Set:
1633
1634         <dd>The "attributes-charset" and "attributes-natural-language"
1635         attributes as described in section 3.1.4.1 of the IPP Model and
1636         Semantics document.
1637
1638         <dt>"limit" (integer (1:MAX)):
1639
1640         <dd>The client OPTIONALLY supplies this attribute limiting the number of PPDs that are returned.
1641
1642         <dt>"ppd-make" (text(127)):
1643
1644         <dd>The client OPTIONALLY supplies a printer manufacturer to select which PPDs are returned.
1645
1646         <dt>"ppd-make-and-model" (text(127)):<span class='info'>CUPS 1.3</span>
1647
1648         <dd>The client OPTIONALLY supplies a make and model to select which PPDs are returned.
1649
1650         <dt>"ppd-model-number" (integer):<span class='info'>CUPS 1.3</span>
1651
1652         <dd>The client OPTIONALLY supplies a model number to select which PPDs are returned.
1653
1654         <dt>"ppd-natural-language" (naturalLanguage):<span class='info'>CUPS 1.3</span>
1655
1656         <dd>The client OPTIONALLY supplies a language to select which PPDs are returned.
1657
1658         <dt>"ppd-product" (text(127)):<span class='info'>CUPS 1.3</span>
1659
1660         <dd>The client OPTIONALLY supplies a PostScript product string to select which PPDs are returned.
1661
1662         <dt>"ppd-psversion" (text(127)):<span class='info'>CUPS 1.3</span>
1663
1664         <dd>The client OPTIONALLY supplies a PostScript version string to select which PPDs are returned.
1665
1666         <dt>"ppd-type" (type1 keyword):<span class='info'>CUPS 1.3</span>
1667
1668         <dd>The client OPTIONALLY supplies a driver type to select which PPDs are returned.
1669
1670         <dt>"requested-attributes" (1setOf keyword) :
1671
1672         <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.
1673
1674 </dl>
1675
1676 <h4>CUPS-Get-PPDs Response</h4>
1677
1678 <p>The following groups of attributes are send as part of the
1679 CUPS-Get-PPDs Response:
1680
1681 <p>Group 1: Operation Attributes
1682
1683 <dl>
1684
1685         <dt>Status Message:
1686
1687         <dd>The standard response status message.
1688
1689         <dt>Natural Language and Character Set:
1690
1691         <dd>The "attributes-charset" and "attributes-natural-language"
1692         attributes as described in section 3.1.4.2 of the IPP Model and
1693         Semantics document.
1694
1695 </dl>
1696
1697 <p>Group 2: PPD Attributes
1698
1699 <dl>
1700
1701         <dt>The set of requested attributes and their current values for each
1702         PPD file.
1703
1704 </dl>
1705
1706 <h3 class='title'><span class='info'>CUPS 1.1</span><a name='CUPS_MOVE_JOB'>CUPS-Move-Job Operation</a></h3>
1707
1708 <p>The CUPS-Move-Job operation (0x400D) moves an active print job
1709 to a different printer.</p>
1710
1711 <h4>CUPS-Move-Job Request</h4>
1712
1713 <p>The following groups of attributes are supplied as part of the
1714 CUPS-Move-Job request:
1715
1716 <p>Group 1: Operation Attributes
1717
1718 <dl>
1719
1720         <dt>Natural Language and Character Set:
1721
1722         <dd>The "attributes-charset" and "attributes-natural-language"
1723         attributes as described in section 3.1.4.1 of the IPP Model and
1724         Semantics document.
1725
1726         <dt>"printer-uri" (uri) and "job-id" (integer)
1727         <br><i>OR</i>
1728         <br>"job-uri":
1729
1730         <dd>The client MUST supply a URI for the specified printer and
1731         a job ID number, or the job URI.
1732
1733 </dl>
1734
1735 <p>Group 2: Job Template Attributes
1736
1737 <dl>
1738
1739         <dt>"job-printer-uri" (uri)
1740
1741         <dd>The client MUST supply a URI for a printer on the same server.
1742
1743 </dl>
1744
1745 <h4>CUPS-Move-Job Response</h4>
1746
1747 <p>The following groups of attributes are send as part of the
1748 CUPS-Move-Job Response:
1749
1750 <p>Group 1: Operation Attributes
1751
1752 <dl>
1753
1754         <dt>Status Message:
1755
1756         <dd>The standard response status message.
1757
1758         <dt>Natural Language and Character Set:
1759
1760         <dd>The "attributes-charset" and "attributes-natural-language"
1761         attributes as described in section 3.1.4.2 of the IPP Model and
1762         Semantics document.
1763
1764 </dl>
1765
1766 <h3 class='title'><span class='info'>CUPS 1.2</span><a name='CUPS_AUTHENTICATE_JOB'>CUPS-Authenticate-Job Operation</a></h3>
1767
1768 <p>The CUPS-Authenticate-Job operation (0x400E) authenticate a
1769 print job for printing. Typically this is used when printing to a
1770 remote server. The authentication information is passed in the
1771 HTTP request.</p>
1772
1773 <h4>CUPS-Authenticate-Job Request</h4>
1774
1775 <p>The following groups of attributes are supplied as part of the
1776 CUPS-Authenticate-Job request:
1777
1778 <p>Group 1: Operation Attributes
1779
1780 <dl>
1781
1782         <dt>Natural Language and Character Set:
1783
1784         <dd>The "attributes-charset" and "attributes-natural-language"
1785         attributes as described in section 3.1.4.1 of the IPP Model and
1786         Semantics document.
1787
1788         <dt>"printer-uri" (uri) and "job-id" (integer)
1789         <br><i>OR</i>
1790         <br>"job-uri":
1791
1792         <dd>The client MUST supply a URI for the specified printer and
1793         a job ID number, or the job URI.
1794
1795 </dl>
1796
1797 <p>Group 2: Job Attributes
1798
1799 <dl>
1800
1801         <dt>"auth-info" (1setOf text(MAX)):<span class='info'>CUPS 1.3</span>
1802
1803         <dd>The client OPTIONALLY supplies one or more authentication values as specified by the "auth-info-required" attribute.
1804
1805 </dl>
1806
1807 <h4>CUPS-Authenticate-Job Response</h4>
1808
1809 <p>The following groups of attributes are send as part of the
1810 CUPS-Authenticate-Job Response:
1811
1812 <p>Group 1: Operation Attributes
1813
1814 <dl>
1815
1816         <dt>Status Message:
1817
1818         <dd>The standard response status message.
1819
1820         <dt>Natural Language and Character Set:
1821
1822         <dd>The "attributes-charset" and "attributes-natural-language"
1823         attributes as described in section 3.1.4.2 of the IPP Model and
1824         Semantics document.
1825
1826 </dl>
1827
1828 <p>Group 2: Unsupported Attributes (status=client-eror-attributes-or-values-not-supported)
1829
1830 <dl>
1831
1832         <dt>auth-info-required (1setOf Type2 keyword)
1833
1834         <dd>The required authentication information.
1835
1836 </dl
1837
1838 <h3 class='title'><span class='info'>CUPS 1.3</span><a name='CUPS_GET_PPD'>CUPS-Get-PPD Operation</a></h3>
1839
1840 <p>The CUPS-Get-PPD operation (0x400F) gets a PPD file from the
1841 server. The PPD file can be specified using a <tt>ppd-name</tt>
1842 returned by <a href='#CUPS_GET_PPDS'><tt>CUPS-Get-PPDs</tt></a>
1843 or using the <tt>printer-uri</tt> for a queue.</p>
1844
1845 <p>If the PPD file is found, <tt>successful-ok</tt> is returned with
1846 the PPD file following the response data.</p>
1847
1848 <p>If the PPD file cannot be served by the local server because
1849 the <tt>printer-uri</tt> attribute points to an external printer,
1850 a <tt>cups-see-other</tt> status is returned with the correct
1851 URI to use.</p>
1852
1853 <p>If the PPD file does not exist, <tt>client-error-not-found</tt> is
1854 returned.</p>
1855
1856 <h4>CUPS-Get-PPD Request</h4>
1857
1858 <p>The following group of attributes is supplied as part of the
1859 CUPS-Get-PPD request:
1860
1861 <p>Group 1: Operation Attributes
1862
1863 <dl>
1864
1865         <dt>Natural Language and Character Set:
1866
1867         <dd>The "attributes-charset" and "attributes-natural-language"
1868         attributes as described in section 3.1.4.1 of the IPP Model and
1869         Semantics document.
1870
1871         <dt>"printer-uri" (uri)
1872         <br><i>OR</i>
1873         <br>"ppd-name" (name(255)):
1874
1875         <dd>The client MUST supply a printer URI or PPD name.
1876
1877 </dl>
1878
1879 <h4>CUPS-Get-PPD Response</h4>
1880
1881 <p>The following group of attributes is sent as part of the
1882 CUPS-Get-PPD Response:
1883
1884 <p>Group 1: Operation Attributes
1885
1886 <dl>
1887
1888         <dt>Status Message:
1889
1890         <dd>The standard response status message.
1891
1892         <dt>Natural Language and Character Set:
1893
1894         <dd>The "attributes-charset" and "attributes-natural-language"
1895         attributes as described in section 3.1.4.2 of the IPP Model and
1896         Semantics document.
1897
1898         <dt>"printer-uri" (uri):
1899
1900         <dd>The printer that provides the actual PPD file when
1901         the status code is cups-see-other (0x280)
1902
1903 </dl>
1904
1905 <p>If the status code is <tt>successful-ok</tt>, the PPD file follows
1906 the end of the IPP response.</p>
1907
1908 <h3 class='title'><span class='info'>CUPS 1.4</span><a name='CUPS_GET_DOCUMENT'>CUPS-Get-Document Operation</a></h3>
1909
1910 <p>The CUPS-Get-Document operation (0x4027) gets a document file from a
1911 job on the server. The document file is specified using the
1912 <tt>document-number</tt> and either the <tt>job-uri</tt> or <tt>printer-uri</tt>
1913 and <tt>job-id</tt> identifying the job.</p>
1914
1915 <p>If the document file is found, <tt>successful-ok</tt> is returned with
1916 the document file following the response data.</p>
1917
1918 <p>If the document file does not exist, <tt>client-error-not-found</tt> is
1919 returned.</p>
1920
1921 <p>If the requesting user does not have access to the document file,
1922 <tt>client-error-not-authorized</tt> is returned.
1923
1924 <h4>CUPS-Get-Document Request</h4>
1925
1926 <p>The following group of attributes is supplied as part of the
1927 CUPS-Get-Document request:
1928
1929 <p>Group 1: Operation Attributes
1930
1931 <dl>
1932
1933         <dt>Natural Language and Character Set:
1934
1935         <dd>The "attributes-charset" and "attributes-natural-language"
1936         attributes as described in section 3.1.4.1 of the IPP Model and
1937         Semantics document.
1938
1939         <dt>"printer-uri" (uri) and "job-id" (integer)
1940         <br><i>OR</i>
1941         <br>"job-uri" (uri):
1942
1943         <dd>The client MUST supply a printer URI and job ID or job URI.
1944
1945         <dt>"document-number" (integer(1:MAX)):
1946
1947         <dd>The client MUST supply a document number to retrieve. The
1948         <tt>document-count</tt> attribute for the job defines the maximum
1949         document number that can be specified. In the case of jobs with
1950         banners (<tt>job-sheets</tt> is not "none"), document number 1
1951         will typically contain the start banner and document number N
1952         will typically contain the end banner.
1953
1954 </dl>
1955
1956 <h4>CUPS-Get-Document Response</h4>
1957
1958 <p>The following group of attributes is sent as part of the
1959 CUPS-Get-Document Response:
1960
1961 <p>Group 1: Operation Attributes
1962
1963 <dl>
1964
1965         <dt>Status Message:
1966
1967         <dd>The standard response status message.
1968
1969         <dt>Natural Language and Character Set:
1970
1971         <dd>The "attributes-charset" and "attributes-natural-language"
1972         attributes as described in section 3.1.4.2 of the IPP Model and
1973         Semantics document.
1974
1975         <dt>"document-format" (mimeType):
1976
1977         <dd>The format of the document file.
1978
1979         <dt>"document-number" (integer(1:MAX)):
1980
1981         <dd>The requested document number.
1982
1983         <dt>"document-name" (name(MAX)):
1984
1985         <dd>The name that was supplied with the document, if any.
1986
1987 </dl>
1988
1989 <p>If the status code is <tt>successful-ok</tt>, the document file follows
1990 the end of the IPP response.</p>
1991
1992
1993 <h2 class='title'><a name='ATTRIBUTES'>Attributes</a></h2>
1994
1995 <p>CUPS provides many extension attributes to support multiple
1996 devices, PPD files, standard job filters, printers, and printer
1997 classes.</p>
1998
1999 <h3 class='title'><a name='DEVICE_ATTRIBUTES'>Device Attributes</a></h3>
2000
2001 <p>Device attributes are returned by the CUPS-Get-Devices
2002 operation and enumerate all of the available hardware devices and
2003 network protocols that are supported by the server.</p>
2004
2005 <h4><a name="device-class">device-class (type2 keyword)</a></h4>
2006
2007 <p>The device-class attribute specifies the class of device and can be
2008 one of the following:
2009
2010 <ul>
2011
2012         <li>"file" - a disk file.
2013
2014         <li>"direct" - a parallel or fixed-rate serial data port,
2015         currently used for Centronics, IEEE-1284, and USB printer
2016         ports.
2017
2018         <li>"serial" - a variable-rate serial port.
2019
2020         <li>"network" - a network connection, typically via AppSocket,
2021         HTTP, IPP, LPD, or SMB/CIFS protocols.
2022
2023 </ul>
2024
2025 <h4><a name="device-id">device-id (text(127))</a><span class="info">CUPS 1.2</span></h4>
2026
2027 <p>The device-id attribute specifies the IEEE-1284 device ID
2028 string for the device.</p>
2029
2030 <h4><a name="device-info">device-info (text(127))</a></h4>
2031
2032 <p>The device-info attribute specifies a human-readable string describing
2033 the device, e.g. "Parallel Port #1".
2034
2035 <h4><a name="device-make-and-model">device-make-and-model (text(127))</a></h4>
2036
2037 <p>The device-makr-and-model attribute specifies a device
2038 identification string provided by the printer connected to the device.
2039 If the device or printer does not support identification then this
2040 attribute contains the string "unknown".
2041
2042 <h4><a name="device-uri">device-uri (uri)</a></h4>
2043
2044 <p>The device-uri attribute specifies a unique identifier for the
2045 device. The actual format of the device-uri string depends on the value
2046 of the device-class attribute:
2047
2048 <ul>
2049
2050         <li>"file" - The device-uri will be of the form
2051         "file:///path/to/filename".
2052
2053         <li>"direct" - The device-uri will be of the form
2054         "scheme:/dev/filename" or "scheme://vendor/identifier",
2055         where scheme may be "parallel" or "usb" in the current
2056         implementation.
2057
2058         <li>"serial" - The device-uri will be of the form
2059         "serial:/dev/filename?baud=value+parity=value+flow=value".
2060         The baud value is the data rate in bits per second; the
2061         supported values depend on the underlying hardware.
2062         The parity value can be one of "none", "even", or "odd".
2063         The flow value can be one of "none", "soft" (XON/XOFF
2064         handshaking), "hard" or "rts/cts" (RTS/CTS handshaking),
2065         or "dtrdsr" (DTR/DSR handshaking).
2066
2067         <p>The URI returned by CUPS-Get-Devices will contain the
2068         maximum baud rate supported by the device and the best
2069         type of flow control available ("soft" or "hard").
2070
2071         <li>"network" - The device-uri will be of the form
2072         "scheme://[username:password@]hostname[:port]/[resource]",
2073         where scheme may be "http", "https", "ipp", "lpd", "smb", or
2074         "socket" in the current implementation.
2075
2076         <p>The URI returned by CUPS-Get-Devices will only contain
2077         the scheme name ("scheme"). It is up to the client
2078         application to add the appropriate host and other
2079         information when adding a new printer.
2080
2081         <p>The URI returned by Get-Printer-Attributes and
2082         CUPS-Get-Printers has any username and password information
2083         stripped; the information is still stored and used by the
2084         server internally to perform any needed authentication.
2085
2086 </ul>
2087
2088 <h3 class='title'><a name='JOB_TEMPLATE_ATTRIBUTES'>Job Template Attributes</a></h3>
2089
2090 <h4><a name="auth-info">auth-info (1setOf text(MAX))</a><span class="info">CUPS 1.3</span></h4>
2091
2092 <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.
2093
2094 <h4><a name="blackplot">blackplot (boolean)</a></h4>
2095
2096 <p>The blackplot attribute specifies whether HP-GL/2 plot files should be
2097 rendered entirely in black ink (blackplot=true) or using the colors and shades
2098 specified in the file (blackplot=false). The default value is false.
2099
2100 <h4><a name="brightness">brightness (integer(0:200))</a></h4>
2101
2102 <p>The brightness attribute specifies the overall brightness of the printed
2103 output in percent. A brightness of 100 is normal, while 200 is twice as
2104 bright and 50 is half as bright. The default value is 100.
2105
2106 <p>Brightness is applied to the Cyan, Magenta, Yellow, and Black values using
2107 the function "f(x) = brightness / 100 * x".
2108
2109 <h4><a name="columns">columns (integer(1:4))</a></h4>
2110
2111 <p>The columns attribute specifies the number of columns to generate when
2112 printing text files. The default value is 1.
2113
2114 <h4><a name="cpi">cpi (type2 enum)</a></h4>
2115
2116 <p>The cpi attribute specifies the number of characters per inch when
2117 printing text files. Only the values 10, 12, and 17 are currently
2118 supported. The default value is 10.
2119
2120 <h4><a name="document-count">document-count (integer(1:MAX))</a></h4>
2121
2122 <p>The document-count attribute specifies the number of documents that
2123 are present in the job.
2124
2125 <h4><a name="fitplot">fitplot (boolean)</a></h4>
2126
2127 <p>The fitplot attribute specifies whether to scale HP-GL/2 plot files to
2128 fit on the selected media (fitplot=true) or use the physical scale specified
2129 in the plot file (fitplot=false). The default value is false.
2130
2131 <h4><a name="gamma">gamma (integer(1:10000))</a></h4>
2132
2133 <p>The gamma attribute specifies the luminance correction for the output.
2134 A value of 1000 specifies no correction, while values of 2000 and 500 will
2135 generate lighter and darker output, respectively. The default value is
2136 1000.
2137
2138 <p>Gamma is applied to the Red, Green, and Blue values (or luminance for
2139 grayscale output) using the function "f(x) = x<SUp>(1000/gamma)</SUp>".
2140
2141 <h4><a name="hue">hue (integer(-180:180))</a></h4>
2142
2143 <p>The hue attribute specifies a color hue rotation when printing image
2144 files. The default value is 0.
2145
2146 <h4><a name="job-billing">job-billing (text(MAX))</a><span class='info'>CUPS 1.1</span></h4>
2147
2148 <p>The job-billing attribute provides a text value to associate with a job
2149 for billing purposes.
2150
2151 <h4><a name="job-hold-until">job-hold-until (keyword | name(MAX))</a><span class='info'>CUPS 1.1</span></h4>
2152
2153 <p>The job-hold-until attribute specifies a hold time. In addition to the
2154 standard IPP/1.1 keyword names, CUPS supports name values of the form
2155 "HH:MM" and "HH:MM:SS" that specify a hold time. The hold time is in
2156 Universal Coordinated Time (UTC) and <i>not</i> in the local time zone. If the
2157 specified time is less than the current time, the job is held until the
2158 next day.
2159
2160 <h4><a name="job-printer-state-message">job-printer-state-message (text(MAX))</a><span class='info'>CUPS 1.3</span></h4>
2161
2162 <p>The job-printer-state-message attribute provides the last known value of the printer-state-message attribute for the printer that processed (or is processing) the job.</p>
2163
2164 <h4><a name="job-printer-state-reasons">job-printer-state-reasons (1setOf type2 keyword)</a><span class='info'>CUPS 1.3</span></h4>
2165
2166 <p>The job-printer-state-reasons attribute provides the last known value of the printer-state-reasons attribute for the printer that processed (or is processing) the job.</p>
2167
2168 <h4><a name="job-sheets">job-sheets (1setof type3 keyword | name(MAX))</a><span class='info'>CUPS 1.1</span></h4>
2169
2170 <p>The job-sheets attribute specifies one or two banner files that are printed
2171 before and after a job. The reserved value of "none" disables banner printing.
2172 The default value is stored in the job-sheets-default attribute.
2173
2174 <p>If only one value is supplied, the banner file is printed before the job.
2175 If two values are supplied, the first value is used as the starting banner
2176 file and the second as the ending banner file.
2177
2178 <h4><a name="job-originating-host-name">job-originating-host-name (name(MAX))</a></h4>
2179
2180 <p><i>(CUPS 1.1.5 and higher)</i>
2181
2182 <p>The job-originating-host-name attribute specifies the host
2183 from which the job was queued. The value will be the hostname or
2184 IP address of the client depending on whether hostname
2185 resolution is enabled.  The localhost address (127.0.0.1) is
2186 <b>always</b> resolved to the name "localhost".
2187
2188 <p>This attribute is read-only.
2189
2190 <h4><a name="lpi">lpi (type2 enum)</a></h4>
2191
2192 <p>The lpi attribute specifies the number of lines per inch when
2193 printing text files. Only the values 6 and 8 are currently supported.
2194 The default value is 6.
2195
2196 <h4><a name="mirror">mirror (boolean)</a></h4>
2197
2198 <p>The mirror attribute specifies whether pages are mirrored on
2199 their X axis, which is useful for printing transfer images on
2200 special media. The default value is false.
2201
2202 <h4><a name="natural-scaling">natural-scaling (integer(1:1000))</a><span class='info'>CUPS 1.1.9</span></h4>
2203 <p>The natural-scaling attribute specifies the scaling of image files with
2204 respect to the natural image size. A value of 100 specifies that the image
2205 file should exactly the natural size, while 50 is half the natural size
2206 and 200 is twice the natural size. The default value is 100.
2207
2208 <p>The ppi option can be used to override the natural resolution of the
2209 image, which controls the natural size.
2210
2211 <h4><a name="number-up-layout">number-up-layout (type2 keyword)</a><span class='info'>CUPS 1.1.15</span></h4>
2212 <p>The number-up-layout attribute specifies the order each input
2213 page is placed on each output page. The following keywords are
2214 presently defined:
2215
2216 <ul>
2217
2218         <li><CODE>btlr</CODE> - Bottom to top, left to right</li>
2219
2220         <li><CODE>btrl</CODE> - Bottom to top, right to left</li>
2221
2222         <li><CODE>lrbt</CODE> - Left to right, bottom to top</li>
2223
2224         <li><CODE>lrtb</CODE> - Left to right, top to bottom (default)</li>
2225
2226         <li><CODE>rlbt</CODE> - Right to left, bottom to top</li>
2227
2228         <li><CODE>rltb</CODE> - Right to left, top to bottom</li>
2229
2230         <li><CODE>tblr</CODE> - Top to bottom, left to right</li>
2231
2232         <li><CODE>tbrl</CODE> - Top to bottom, right to left</li>
2233
2234 </ul>
2235
2236 <h4><a name="page-border">page-border (type2 keyword)</a><span class='info'>CUPS 1.1.15</span></h4>
2237 <p>The page-border attribute specifies whether a border is
2238 draw around each page. The following keywords are presently
2239 defined:
2240
2241 <ul>
2242
2243         <li><CODE>double</CODE> - Two hairline borders are drawn</li>
2244
2245         <li><CODE>double-thick</CODE> - Two 1pt borders are drawn</li>
2246
2247         <li><CODE>none</CODE> - No border is drawn (default)</li>
2248
2249         <li><CODE>single</CODE> - A single hairline border is drawn</li>
2250
2251         <li><CODE>single-thick</CODE> - A single 1pt border is drawn</li>
2252
2253 </ul>
2254
2255 <h4><a name="page-bottom">page-bottom (integer(0:MAX))</a></h4>
2256
2257 <p>The page-bottom attribute specifies the bottom margin in points (72 points
2258 equals 1 inch). The default value is the device physical margin.
2259
2260 <h4><a name="page-label">page-label (text(MAX))</a><span class='info'>CUPS 1.1.7</span></h4>
2261 <p>The page-label attribute provides a text value to place in
2262 the header and footer on each page. If a classification level is
2263 set on the server, then this classification is printed before
2264 the page label.
2265
2266 <h4><a name="page-left">page-left (integer(0:MAX))</a></h4>
2267
2268 <p>The page-left attribute specifies the left margin in points (72 points
2269 equals 1 inch). The default value is the device physical margin.
2270
2271 <h4><a name="page-right">page-right (integer(0:MAX))</a></h4>
2272
2273 <p>The page-right attribute specifies the right margin in points (72 points
2274 equals 1 inch). The default value is the device physical margin.
2275
2276 <h4><a name="page-set">page-set (type2 keyword)</a></h4>
2277
2278 <p>The page-set attribute specifies which pages to print in a file. The
2279 supported keywords are "all", "even", and "odd". The default value is
2280 "all".
2281
2282 <h4><a name="page-top">page-top (integer(0:MAX))</a></h4>
2283
2284 <p>The page-top attribute specifies the top margin in points (72 points
2285 equals 1 inch). The default value is the device physical margin.
2286
2287 <h4><a name="penwidth">penwidth (integer(0:MAX))</a></h4>
2288
2289 <p>The penwidth attribute specifies the default pen width in micrometers
2290 when printing HP-GL/2 plot files. The default value is 1000 (1 millimeter).
2291
2292 <h4><a name="position">position (type2 keyword)</a></h4>
2293
2294 <p>The position attribute specifies the location of image files on the
2295 media. The following keyword values are recognized:
2296
2297 <ul>
2298
2299         <li><CODE>center</CODE> - Center the image on the page (default)
2300
2301         <li><CODE>top</CODE> - Print the image centered at the top of the page
2302
2303         <li><CODE>left</CODE> - Print the image centered on the left of page
2304
2305         <li><CODE>right</CODE> - Print the image centered on the right of the page
2306
2307         <li><CODE>top-left</CODE> - Print the image at the top left corner of
2308         the page
2309
2310         <li><CODE>top-right</CODE> - Print the image at the top right corner of
2311         the page
2312
2313         <li><CODE>bottom</CODE> - Print the image centered at the bottom of
2314         the page
2315
2316         <li><CODE>bottom-left</CODE> - Print the image at the bottom left
2317         corner of the page
2318
2319         <li><CODE>bottom-right</CODE> - Print the image at the bottom right
2320         corner of the page
2321
2322 </ul>
2323
2324 <h4><a name="ppi">ppi (integer(1:MAX))</a></h4>
2325
2326 <p>The ppi attribute specifies the resolution of an image file in pixels
2327 per inch. The default value is the resolution included with the file or
2328 128 if no resolution information is available.
2329
2330 <h4><a name="prettyprint">prettyprint (boolean)</a></h4>
2331
2332 <p>The prettyprint attribute specifies whether text files should be printed
2333 with a shaded header and keyword highlighting (prettyprint=true) or without
2334 additional formatting (prettyprint=false). The default value is false.
2335
2336 <h4><a name="saturation">saturation (integer(0:200))</a></h4>
2337
2338 <p>The saturation attribute specifies the color saturation when
2339 printing image files. A saturation of 100 is normal, while values of 50
2340 and 200 will be half and twice as colorful, respectively. The default
2341 value is 100.
2342
2343 <h4><a name="scaling">scaling (integer(1:1000))</a></h4>
2344
2345 <p>The scaling attribute specifies the scaling of image files with
2346 respect to the selected media. A value of 100 specifies that the image
2347 file should fit 100% of the page, or as much as possible given the
2348 image dimensions. The default value is unspecified.
2349
2350 <p>The scaling attribute overrides the ppi attribute if specified.
2351
2352 <h4><a name="wrap">wrap (boolean)</a></h4>
2353
2354 <p>The wrap attribute specifies whether long lines should be wrapped
2355 (wrap=true) or not (wrap=false) when printing text files. The default
2356 value is true.
2357
2358 <h3 class='title'><a name='PPD_ATTRIBUTES'>PPD Attributes</a></h3>
2359
2360 <h4><a name="ppd-device-id">ppd-device-id (text(127))</a></h4>
2361
2362 <p>The ppd-device-id attribute specifies the IEEE-1284 device ID
2363 string for the device described by the PPD file.</p>
2364
2365 <h4><a name="ppd-make">ppd-make (text(127))</a></h4>
2366
2367 <p>The ppd-make attribute specifies the manufacturer of the printer
2368 (the Manufacturer attribute in the PPD file). If the manufacturer
2369 is not specified in the PPD file then an educated guess is made using
2370 the NickName attribute in the PPD file.
2371
2372 <h4><a name="ppd-make-and-model">ppd-make-and-model (text(127))</a></h4>
2373
2374 <p>The ppd-make-and-model attribute specifies the manufacturer and model
2375 name of the PPD file (the NickName attribute in the PPD file). If the
2376 make and model is not specified in the PPD file then the ModelName or
2377 ShortNickName attributes are used instead.
2378
2379 <h4><a name="ppd-model-number">ppd-model-number (integer)</a><span class="info">CUPS 1.3</span></h4>
2380
2381 <p>The ppd-model-number attribute provides the <tt>cupsModelNumber</tt> value from the PPD file.
2382
2383 <h4><a name="ppd-name">ppd-name (name(255))</a></h4>
2384
2385 <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.
2386
2387 <h4><a name="ppd-natural-language">ppd-natural-language (1setOf naturalLanguage)</a></h4>
2388
2389 <p>The ppd-natural-language attribute specifies the language encoding
2390 of the PPD file (the LanguageVersion attribute in the PPD file). If the
2391 language is unknown or undefined then "en" (English) is assumed.
2392
2393 <h4><a name="ppd-product">ppd-product (1setOf text(127))</a></h4>
2394
2395 <p>The ppd-product attribute specifies the Product attribute values in the PPD file.
2396
2397 <h4><a name="ppd-psversion">ppd-psversion (1setOf text(127))</a><span class="info">CUPS 1.3</span></h4>
2398
2399 <p>The ppd-product attribute specifies the PSVersion attribute values in the PPD file.
2400
2401 <h4><a name="ppd-type">ppd-type (type1 keyword)</a><span class="info">CUPS 1.3</span></h4>
2402
2403 <p>The ppd-type attribute specifies the type of driver described by the PPD file:</p>
2404
2405 <ul>
2406
2407         <li><tt>fax</tt> - A facsimile or multi-function device</li>
2408
2409         <li><tt>pdf</tt> - A PDF printer</li>
2410
2411         <li><tt>postscript</tt> - A PostScript printer (no filters)</li>
2412
2413         <li><tt>raster</tt> - A CUPS raster driver</li>
2414
2415         <li><tt>unknown</tt> - An unknown or hybrid driver</li>
2416
2417 </ul>
2418
2419
2420 <h3 class='title'><a name='PRINTER_ATTRIBUTES'>Printer Attributes</a></h3>
2421
2422 <h4><a name="auth-info-required">auth-info-required (1setOf type2 keyword)</a><span class="info">CUPS 1.3</span></h4>
2423
2424 <p>The auth-info-required attribute specifies the authentication information that is required for printing a job. The following keywords are recognized:</p>
2425
2426 <ul>
2427
2428         <li><tt>domain</tt> - A domain name is required.</li>
2429
2430         <li><tt>none</tt> - No authentication is required - this keyword can only appear by itself.</li>
2431
2432         <li><tt>password</tt> - A password is required.</li>
2433
2434         <li><tt>username</tt> - A username is required.</li>
2435
2436 </ul>
2437
2438 <h4><a name="job-k-limit">job-k-limit (integer)</a><span class='info'>CUPS 1.1</span></h4>
2439
2440 <p>The job-k-limit attribute specifies the maximum number of kilobytes that
2441 may be printed by a user, including banner files. The default value of 0
2442 specifies that there is no limit.
2443
2444 <h4><a name="job-page-limit">job-page-limit (integer)</a><span class='info'>CUPS 1.1</span></h4>
2445
2446 <p>The job-page-limit attribute specifies the maximum number of pages that
2447 may be printed by a user, including banner files. The default value of 0
2448 specifies that there is no limit.
2449
2450 <h4><a name="job-quota-period">job-quota-period (integer)</a><span class='info'>CUPS 1.1</span></h4>
2451
2452 <p>The job-quota-period attribute specifies the time period used for quota
2453 calculations, in seconds. The default value of 0 specifies that the limits
2454 apply to all jobs that have been printed by a user that are still known to
2455 the system.
2456
2457 <h4><a name="job-sheets-supported">job-sheets-supported (1setof type3 keyword | name(MAX))</a><span class='info'>CUPS 1.1</span></h4>
2458
2459 <p>The job-sheets-supported attribute specifies the available banner files.
2460 There will always be at least one banner file available called "none".
2461
2462 <h4><a name="port-monitor">port-monitor" (name(127))</a></h4>
2463
2464 <p>The port-monitor attribute specifies the port monitor to use when printing
2465 to this printer. The default port monitor is "none".
2466
2467 <h4><a name="port-monitor-supported">port-monitor-supported" (1setOf name(127))</a></h4>
2468
2469 <p>The port-monitor-supported attribute specifies the available port monitors.
2470
2471 <h4><a name="printer-type">printer-type (type2 enum)</a></h4>
2472
2473 <p>The printer-type attribute specifies printer type and
2474 capability bits for the printer or class. The default value is
2475 computed from internal state information and the PPD file for the
2476 printer. The following bits are defined:</p>
2477
2478 <div class='table'><table align='center' border='1' width='80%'
2479 summary='Printer Type Bits'>
2480 <thead>
2481 <tr>
2482         <th>Bit</th>
2483         <th>Description</th>
2484 </tr>
2485 </thead>
2486 <tbody>
2487 <tr>
2488         <td>0x00000001</td>
2489         <td>Is a printer class.</td>
2490 </tr>
2491 <tr>
2492         <td>0x00000002</td>
2493         <td>Is a remote destination.</td>
2494 </tr>
2495 <tr>
2496         <td>0x00000004</td>
2497         <td>Can print in black.</td>
2498 </tr>
2499 <tr>
2500         <td>0x00000008</td>
2501         <td>Can print in color.</td>
2502 </tr>
2503 <tr>
2504         <td>0x00000010</td>
2505         <td>Can print on both sides of the page in hardware.</td>
2506 </tr>
2507 <tr>
2508         <td>0x00000020</td>
2509         <td>Can staple output.</td>
2510 </tr>
2511 <tr>
2512         <td>0x00000040</td>
2513         <td>Can do fast copies in hardware.</td>
2514 </tr>
2515 <tr>
2516         <td>0x00000080</td>
2517         <td>Can do fast copy collation in hardware.</td>
2518 </tr>
2519 <tr>
2520         <td>0x00000100</td>
2521         <td>Can punch output.</td>
2522 </tr>
2523 <tr>
2524         <td>0x00000200</td>
2525         <td>Can cover output.</td>
2526 </tr>
2527 <tr>
2528         <td>0x00000400</td>
2529         <td>Can bind output.</td>
2530 </tr>
2531 <tr>
2532         <td>0x00000800</td>
2533         <td>Can sort output.</td>
2534 </tr>
2535 <tr>
2536         <td>0x00001000</td>
2537         <td>Can handle media up to US-Legal/A4.</td>
2538 </tr>
2539 <tr>
2540         <td>0x00002000</td>
2541         <td>Can handle media from US-Legal/A4 to ISO-C/A2.</td>
2542 </tr>
2543 <tr>
2544         <td>0x00004000</td>
2545         <td>Can handle media larger than ISO-C/A2.</td>
2546 </tr>
2547 <tr>
2548         <td>0x00008000</td>
2549         <td>Can handle user-defined media sizes.</td>
2550 </tr>
2551 <tr>
2552         <td>0x00010000</td>
2553         <td>Is an implicit (server-generated) class.</td>
2554 </tr>
2555 <tr>
2556         <td>0x00020000</td>
2557         <td>Is the a default printer on the network.</td>
2558 </tr>
2559 <tr>
2560         <td>0x00040000<td>
2561         <td>Is a facsimile device.</td>
2562 </tr>
2563 <tr>
2564         <td>0x00080000</td>
2565         <td>Is rejecting jobs.</td>
2566 </tr>
2567 <tr>
2568         <td>0x00100000</td>
2569         <td>Delete this queue.</td>
2570 </tr>
2571 <tr>
2572         <td>0x00200000</td>
2573         <td>Queue is not shared.</td>
2574 </tr>
2575 <tr>
2576         <td>0x00400000</td>
2577         <td>Queue requires authentication.</td>
2578 </tr>
2579 <tr>
2580         <td>0x00800000</td>
2581         <td>Queue supports CUPS command files.</td>
2582 </tr>
2583 <tr>
2584         <td>0x01000000</td>
2585         <td>Queue was automatically discovered and added.</td>
2586 </tr>
2587 </tbody>
2588 </table></div>
2589
2590 <h4>printer-type-mask (type2 enum)<span class='info'>CUPS 1.1</span></h4>
2591
2592 <p>The printer-type-mask attribute is used to choose printers or classes with
2593 the CUPS-Get-Printers and CUPS-Get-Classes operations. The bits are defined
2594 identically to the printer-type attribute and default to all 1's.
2595
2596 <h4>requesting-user-name-allowed (1setof name(127))<span class='info'>CUPS 1.1</span></h4>
2597
2598 <p>The requesting-user-name-allowed attribute lists all of the users that are
2599 allowed to access a printer or class. Either this attribute or the
2600 requesting-user-name-denied attribute will be defined, but not both.
2601
2602 <h4>requesting-user-name-denied (1setof name(127))<span class='info'>CUPS 1.1</span></h4>
2603
2604 <p>The requesting-user-name-denied attribute lists all of the users that are
2605 not allowed to access a printer or class. Either this attribute or the
2606 requesting-user-name-allowed attribute will be defined, but not both.
2607
2608 <h3 class='title'><a name='CLASS_ATTRIBUTES'>Printer Class Attributes</a></h3>
2609
2610 <h4>member-names (1setof name(127))</h4>
2611
2612 <p>The member-names attribute specifies each of the printer-name attributes of
2613 the member printers and classes. Each name corresponds to the same element of
2614 the member-uris attribute.
2615
2616 <h4>member-uris (1setof uri)</h4>
2617
2618 <p>The member-uris attribute specifies each of the printer-uri attributes of
2619 the member printers and classes. Each URI corresponds to the same element of
2620 the member-names attribute.
2621
2622 </body>
2623 </html>