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